It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

Stash Plugin Settings

Scott Walter Jul 28, 2015

I'm writing a plugin for Stash v3.5.1 that is event driven. With this version of Stash, what is the best way to incorporate configurable global settings for the plugin? Is it with soy templates? I want to avoid reading from resource files because I want this data to be easily modified without needing to restart Stash.

I find a lot of questions about settings/soy templates in regards to Stash but not a whole lot of documentation on how to precisely incorporate a file in your plugin, pull data from it (unless you're using a hook which I am not), etc.

1 answer

0 votes
Mibex Software Jul 28, 2015

Hi,

I would definitely go with Soy templates. They are used by Stash internally as well and provide - beside having quite a nice syntax - the possibility to be used on the server as well as on the client side, as they are transformed to JavaScript on the client side.

For plug-in settings, I would go with a template similar to this (note the usage of the decorator and the active tab):

/**
 * @param config
 * @param? errors
 **/
{template .adminConfigurationPanel}
<html>
<head>
    <meta name="decorator" content="atl.admin">
    <meta name="admin.active.tab" content="your-webitem-key-from-atlassian-plugin.xml"/>
    <title>{{stash_i18n('adminconfig.title', 'Plug-in Admin Config')}}</title>
</head>
<body>
// YOUR SETTINGS PAGE CONTENT HERE
</body>
{/template}

Inside your SOY template, you want to use AUI to have a consistent look with the Atlassian products. There is not so much documentation about how to use the SOY templates provided by AUI, but the source code is of great help here: 

https://bitbucket.org/atlassian/aui/src/883995019420e253fcc22346a38b8624e838e908/src/soy/?at=master

As form elements are probably necessary when building a settings page, you should have a look at the aui-forms.soy file as well:

https://bitbucket.org/atlassian/aui/src/883995019420e253fcc22346a38b8624e838e908/src/soy/form.soy?at=master

Here's an example of how such a form could look like:

{call aui.form.form}
    {param action: '' /}
    {param id: 'adminConfig' /}
    {param content}

    {call aui.form.textField}
        {param id: 'server_url' /}
        {param labelContent: stash_i18n('serverurl.label', 'Server URL') /}
        {param value: $config.serverUrl /}
        {param descriptionText: stash_i18n('serverurl.description', 'This is the base URL of your Server server instance') /}
        {param errorTexts: $errors ? $errors['serverUrl'] : null /}
    {/call}
{/call}

 

The config and the optional errors variable you would pass from your servlet when rendering the SOY template:

// build Map with pageContext including the config object and optional errors hre
String soyTemplateName = "plugin.page.adminConfigurationPanel";
String pluginModuleKey = "your-plugin-id:your-resources-key";
soyTemplateRenderer.render(res.getWriter(), pluginModuleKey, soyTemplateName, pageContext);

 

Hope this helps.

Cheers,

Michael

Scott Walter Jul 29, 2015

Hi Michael, with this approach to creating settings for the plugin, what else do I need? Obviously the soy template, but you mention a servlet as well. Is what your describing have to do with this: https://developer.atlassian.com/docs/common-coding-tasks/creating-an-admin-configuration-form#CreatinganAdminConfigurationForm-Step1.Createthepluginproject

Mibex Software Jul 29, 2015

This is a bit hard to explain in a few sentences. If you are new to Stash plug-in development, I strongly recommend this tutorial: https://bitbucket.org/atlassianlabs/stash-tag-list-plugin It contains everything you need (servlet, SOY templates, web resources) and explains every step in detail. I hope this helps. If you have a concrete issue, please do not hesitate to ask here again!

Suggest an answer

Log in or Sign up to answer
This widget could not be displayed.
This widget could not be displayed.
Community showcase
Published in Next-gen

Introducing subtasks for breaking down work in next-gen projects

Teams break work down in order to help simplify complex tasks. This is often done iteratively, with tasks being broken down into smaller tasks and so on until the work is accurately captured in well-...

1,099 views 13 15
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you