How do I use soy with stash to make useful configuration pages?

[Carl Myers]

I've seen plenty of documentation but all it shows is how to do simple forms. I can do text fields and checkboxes. How do I do dropdown boxes? How do I do password fields? Where is this crap documented at ALL?

https://answers.atlassian.com/questions/153952/are-there-repository-hook-examples-for-more-complex-configuration-ui This link implies that widget.aui.form.* is deprecated and I should use aui.form.* instead, but they cause errors for me when I try to use them. I see AUI docs but nothing has actual SOY examples! THIS IS INFURAITING. I have spent OVER A WEEK messing with this crap.

Here is my working code:

{call widget.aui.group.group}
    {param contents}
      {call widget.aui.form.form}
        {param action: '' /}
        {param contents}
          {call widget.aui.form.checkbox}
            {param id: 'ciEnabled' /}
            {param labelHtml: stash_i18n('stash.web.stash.enable-ci-radio.button.label', 'Enabled') /}
            {param checked: $ciEnabled /}
            {param description: stash_i18n('stash.web.stash.enable-ci-radio.button.description', 'Enables Stashbot to do CI builds for this repo') /}
          {/call}
          {call widget.aui.form.text}
            {param id: 'jenkinsServerName' /}
            {param labelHtml: stash_i18n('stash.web.stash.jenkinsServerName.label', 'Jenkins Server to use') /}
            {param initialValue: $jenkinsServerName /}
            {param description: stash_i18n('stash.web.stash.jenkinsServerName.description', 'Jenkins Server to use') /}
          {/call}
          {call widget.aui.form.input}
            {param id: 'stash.web.stash.ci-prefs.submit' /}
            {param labelHtml: stash_i18n('stash.web.stash.ci-prefs.submit', 'Save') /}
            {param value: stash_i18n('stash.web.stash.ci-prefs.submit', 'Save') /}
            {param type: 'submit' /}
          {/call}
        {/param}
      {/call}
    {/param}
{/call}

No matter what I do, the "submit button" always has the text "Submit Query", rather than save. I can't make a dropdown box. I can't make a password firled with obscured contents. ARGH!

[jpoh · Accepted solution]

Hi Carl,

Sorry that you've been having problems using the Soy templates, and yes, we need to document the use of Soy templates a bit better. The Soy templates in AUI are relatively new (compared to Stash) and there may have been some changes in the template and param names, which is probably why your attempt to use them by just changing `{call widget.aui.form.form}` to `{call aui.form.form}` (and all the rest) might have resulted in errors.

I've had a look at your soy template, and re-written it to use the correct AUI soy template names and pass in the right params. I've also added additional fields as examples on how to add a dropdown `<select>` field with multiple options, and a password type input field.

{call aui.form.form}
    {param action: '' /}
    {param content}
        {call aui.form.checkboxField}
            {param legendContent: 'Jenkins Builds' /}
            {param fields: [[
                'id': 'ciEnabled',
                'labelText': stash_i18n('stash.web.stash.enable-ci-radio.button.label', 'Enabled'),
                'isChecked': $ciEnabled
                ]] /}
            {param descriptionText: stash_i18n('stash.web.stash.enable-ci-radio.button.description', 'Enables Stashbot to do CI builds for this repo') /}
        {/call}
        {call aui.form.selectField}
            {param id: 'jenkinsServerName' /}
            {param labelContent: stash_i18n('stash.web.stash.jenkinsServerName.label', 'Jenkins Server') /}
            {param options: [[
                  'text': 'Server One',
                  'value': 'server-1'
                ],[
                  'text': 'My Jenkins Server',
                  'value': 'server-2'
                ],[
                    'text': 'A Third Server',
                    'value': 'external-jenkins'
                 ]] /}
            {param descriptionText: stash_i18n('stash.web.stash.jenkinsServerName.description', 'Choose a Jenkins Server to use') /}
        {/call}
        {call aui.form.textField}
            {param id: 'jenkinsServerUser' /}
            {param labelContent: stash_i18n('stash.web.stash.jenkinsServerUser.label', 'Username') /}
            {param value: $jenkinsServerName /}
            {param descriptionText: stash_i18n('stash.web.stash.jenkinsServerUser.description', 'Jenkins user') /}
        {/call}
        {call aui.form.passwordField}
            {param id: 'jenkinsServerPassword' /}
            {param labelContent: stash_i18n('stash.web.stash.jenkinsServerPassword.label', 'Password') /}
        {/call}
        {call aui.form.buttons}
            {param content}
                {call aui.form.submit}
                    {param id: 'stash.web.stash.ci-prefs.submit' /}
                    {param text: stash_i18n('stash.web.stash.ci-prefs.submit', 'Save') /}
                    {param type: 'submit' /}
                {/call}
            {/param}
        {/call}
    {/param}
{/call}

This should give you a form that looks something like:

Documentation on Soy templating (aka Google Closure Templates) can be found at https://developers.google.com/closure/templates/ . For the time being, the best way to see which Soy templates are available in AUI and what parameters they take would be to check out the AUI source repo at https://bitbucket.org/atlassian/aui/ and look in the auiplugin/src/main/resources/soy/atlassian/ directory for the soy files and templates. Most of the params have SoyDoc comments explaining what they are for.

Good luck and hope this helps.

[jpoh]

my sentence got cut off, I meant to say:

Check out the AUI source repo at https://bitbucket.org/atlassian/aui/ and look in the auiplugin/src/main/resources/soy/atlassian/ directory for the soy files and templates. Most of the params have SoyDoc comments explaining what they are for.

[Carl Myers]

This is VERY helpful, thanks very much! I have everything working now except populating the dropdown box correctly. My code currently looks like this:

{let $curdata: [] /}
              {foreach $name in $allJenkinsServerNames}
                {let $curdata: [$curdata, ['value': $name, 'name': $name ] /}
              {/foreach}
            {/param}

This (inside of a {param options} ... {/param} block) doesn't work, I get:

[INFO] [talledLocalContainer] com.google.template.soy.tofu.SoyTofuException: In template aui.form.select: In 'foreach' command {foreach $option in $options}{call .optionOrOptgroup data="$option" /}{/foreach}, the data reference does not resolve to a SoyListData.

I've tried MANY permutations trying to figure out how to do this. Any ideas? Once I figure it out, I will accept this answer.

[cofarrell]

Hi Carl,

I'm afraid you can't redefine variables in Soy (variable is a bad name really). From the documentation.

The local variable defined by let is not modifiable. You might use let because you'll need to reuse the intermediate value multiple times, or you'll need to print a rendered value using a directive, or you feel it improves the readability of your template code.

The other problem is that foreach isn't going to return a new array. What you want is a typical 'map' function. Generally foreach is usd to generate HTML, not another soy object/list. Can you possibly have $allJenkinsServerNames be in the exact form expected by select, rather than trying to do that transformation in Soy?

If you can't do that, I might be tempted to write out your server names in a JS <script> block and manipulate the select input DOM on render. I'm hoping someone can suggest a better/nicer way.

Sorry I couldn't be more help.

Charles

[Carl Myers]

Where did you find the list of parameters? The documentation you linked seems to be HTML/JS stuff, I don't see any soy anywhere. Also, grepping the stash source, "selectField" appears nowhere, so I presume it is in the aui library somewhere....

[Carl Myers]

I did figure out what I needed - the source is located at the link you posted, so I just had to read the source: https://bitbucket.org/atlassian/aui/

Looking in ./auiplugin/src/main/resources/soy/atlassian/form.soy I saw that the variable "selected" was passed through, so by passing a map variable named "selected" => "true", I could specify the default selection in the selectField. So I am producing an array, in java, that looks like this:

[['name': 'foo', 'value': 'foo'],['name': 'bar', 'value': 'bar', 'selected': 'true']]

This let me cause the entry "bar" to be selected by default.

[jpoh]

Hi Carl,

Sorry I didn't get back to you earlier, but it seems you've figured it out already. The syntax for the $options param for aui.form.selectField is a bit confusing and we hope to improve that at some point. You've nailed it in that the outermost square brackets creates a SoyList/array where each element is a map of params for each <option> for the <select> dropdown. Since $selected is a boolean value, I think you can remove the quote marks from your java output that's passed into the template, eg

[['name': 'foo', 'value': 'foo'],['name': 'bar', 'value': 'bar', 'selected': true]]

[Carl Myers]

My plugin is now open-sourced, so if you found this question looking for code examples, see: https://github.com/palantir/stashbot