Soy API

Stash exposes a Soy (Closure Templates) API that you can use to add widgets to your pages.

Currently the Stash team only supports a single template as API. That component is the Stash.template.branchSelector.field template and is primarily meant for use in Repository Hook configuration forms. No Web Resource dependency is required to use it from a configuration form.

Expanding our Soy API to include more UI components is on our roadmap.

Compatibility Policy

The Soy API's compatibility policy matches that of Stash's other APIs. Soy APIs will not contain breaking changes between minor versions (e.g. 3.0 and 3.1). Instead, any removed or modified templates and parameters will have a 'deprecated' CSS class added to their output HTML when used, and the legacy behavior will cease to work in the next major release (e.g. Stash 4.0).

"Breaking changes" describes removal of templates or template parameters, or changes to accepted template parameter values that would cause previously valid input to generate invalid HTML, or throw an error. Behavior for invalid inputs may change at any release, and mutation of Soy templates is not supported. See API Scope for details.

Loading the APIs

Soy APIs are not guaranteed to be available on the page. Before using an API you MUST depend on the matching web-resource module for that API. Look at the documentation for a template to determine the dependency required. See the Web Resource Plugin Module documentation for details about how they work.

API Scope

Templates

The scope of the Soy API is limited to the Soy namespaces of Stash.template.* and aui.*. The stability of any other Soy templates is not guaranteed between minor versions.

For any template under that namespace, we guarantee that the template will continue to exist across minor versions. New templates may also be added between minor versions.

Parameters

If a template parameter is listed as @param? it is an optional parameter and won't become a required parameter between versions.

If a parameter name ends in Content, then it expects valid, pre-escaped HTML strings as the value. You should not pass raw strings into these parameters, especially if they come from user input, as this would create a security vulnerability in Stash.

Explicitly out of scope

The markup generated by the Stash templates is explicitly undefined and unstable. You MUST NOT rely on the shape of that markup, except through CSS classes and IDs you have explicitly defined through the extraClasses and id parameters to the template.

The version of Closure Templates used in Stash MAY change. We will make a best-effort attempt not to introduce breaking changes through upgrades to Closure Templates.