Stash Plugin Settings

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

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

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

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
Community showcase
Posted Friday in United States

Confluence Security Advisory

Good morning Members, Not sure if you are aware. Please read the following: https://www.icloud.com/keynote/0RyJ4VEdNUpjDpGfMhfZx9fEg#Confluence_Security_Advisor More details: https://co...

43 views 1 0
View post

Atlassian User Groups

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

Find a group

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

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you