Using soy template with web-panel

Hi ,

I am able to get velocity template working with web-panel , however when referencing soy template it doesn’t work.

Can somebody help me with a snippet on how to reference soy-template within a web-panel ?

I tried the example listed out here - Adding a board configuration page , but the reference to soy template doesnt work

<web-panel key="my-configuration-page" location="jira.agile.board.configuration" weight="1">
        <label key="my.configuration.page.label">My Configuration Page</label>
        <resource type="soy" name="view" location=":soy/My.addOn.tpl.board.config.myConfigurationPage" />
    </web-panel>

Hello @ajay!

The snippet you pasted assumes that in the same atlassian-plugin.xml file you have a web-resource with the key “soy” that contains of soy resource, having for example My.addOn.tpl.board.config namespace with .myConfigurationPage template inside.

<web-resource key="soy" name="My app soy server-side resources">
        <transformation extension="soy">
            <transformer key="soyTransformer"/>
        </transformation>
        <resource type="soy" name="boardConfigPage" location="templates/boardConfigPage.soy"/>
    </web-resource>

and in your templates/boardConfigPage.soy the following structure:

{namespace My.addOn.tpl.board.config}

/**
    Some description of this template to be filled.
     If you need/pass params, do not forget to include them in SoyDoc as well.
*/
{template .myConfigurationPage}
    <div>Your markup here</div>
{/template}

Kind regards,
and have a great time at App Week!

2 Likes

Thanks @mrzymski … that explains and solves the problem :blush:

1 Like

@mrzymski

I am now trying to get react working on the web-panel … now that my soy template is loading…
However I am struggling to get the react components loaded on the soy template…

Any clues on why the web-resources are not loading … (The global page works for me though which is served using a servlet) . How do you specify the context for loading the web-resources in a web-panel?

{template .scmglobalpage}
    {webResourceManager_requireResourcesForContext('scmglobalpage')}
    <html>
    <head>
        <meta charset="utf-8"/>
        <meta name="decorator" content="atl.admin">
        <meta name="admin.active.section" content="atl.jira.view.issue.right.context">
        <title>SCM Global Page</title>
    </head>
    <body>
    <div id="maincontainer">
        <div id="container">
        </div>
    </div>
    </body>
    </html>
{/template}

Sample workspace attached

https://drive.google.com/drive/folders/1_Wo2dMpbonoABwJ5nn5Fyu_vrzWZ3lEZ?usp=sharing

Hi,
Depending on how web-panel is rendered, the calls to WRM to load contexts or web-resources may not necessary work:

  • it works when the page along with those web-panels is server-side rendered and there’s a point where WRM is drained and resource tags are put to the page
  • on the other hand when the web-panel is rendered async. or via REST there’s no point for WRM drain
    In the latter case, it’s common to use the client-side WRM client to load contexts or web-resources.
    For cases when the web-panel can be rendered in both ways, there are both calls: one that you have (calling WRM Java API) and the client-side call.
    (a note: WRM client is aware that a given context was already loaded, so the 2nd call for the same thing will be a no-op, doesn’t hurt).
    You can call WRM client inside a script type=module (but there’s an issue with that when jQuery is used later on to put such async. fetched markup on the page) or a regular script with resourcePhaseCheckpoint (since Jira 9.0). This is especially important for pages with defer scripts, such as Dashboard and Issue view since Jira 9.0, otherwise you won’t be able to access WRM client at that point.
<script type="module">
    require('wrm/require')('wrc!scmglobalpage_or_other_name_of_the_context');
</script>
<script>
window.resourcePhaseCheckpoint.defer.then(() => {
    require('wrm/require')('wrc!scmglobalpage_or_other_name_of_the_context');
});
</script>

Yet another way for case with a template with both WRM type of calls, when you know that the async one is going to happen always after DCL, which has the additional benefit of working pre and post Jira 9.0:

{webResourceManager_requireResourcesForContext('scmglobalpage_or_other_name_of_the_context')}
<script>
if (WRM.require) {
    require('wrm/require')('wrc!scmglobalpage_or_other_name_of_the_context');
}
</script>

I hope that it helps,
Cheers!

1 Like

Hi @mrzymski

Its been some time since I had switched to Forge development…but I am back debugging the React loading on the web-panel for DC App :slight_smile:

I have the below soy file boardConfigPage.soy in resources/templates folder

{namespace My.addOn.tpl.board.config}

/**
 * This template is needed to draw the issue glance page.
 */
{template .issueglance}
    {webResourceManager_requireResourcesForContext('issueglance')}
    <html>
    <head>
        <meta charset="utf-8"/>
        <meta name="decorator" content="atl.admin">
        <meta name="admin.active.section" content="atl.jira.view.issue.right.context">
        <title>SCM Issue Glance</title>
    </head>
    <body>
    <div id="maincontainer">
        <div id="container">
            <script>
            if (WRM.require) {
            require('wrm/require')('wrc!issueglance');
            }
            </script>
        </div>
    </div>
    </body>
    </html>
{/template}

My Atlassian-plugin.xml file has the below definition for the web-panel

  <web-panel key="scm-issue-glance" location="atl.jira.view.issue.right.context" weight="1000">
      <label key="scm-issue-glance.label">My Configuration Page</label>
      <resource type="soy" name="view" location="templates/boardConfigPage.soy" />
  </web-panel>

I am not sure how to solve the below error
Screenshot 2023-05-15 at 3.13.37 PM

Any tips as I cannot find any resources to fix this issue…

Hello,
the first observation I have is why do you need atl.admin decorator for the issue view panel?
It looks like mixed template structure for an admin page and the issue view panel.

Regarding soy template reference, the following should fix the problem.
Soy templates are wired via a web-resource, so you need to have a web-resource (with its key, e.g. soy), inside declaring soy resource. As the web-panel is server-side rendered (depending on the view either on the page load or within the REST call, e.g. when navigating between issues for JQL search), the soy <resource /> element can have soy type (vs download type which would be suitable for both SSR and client-side rendering).

<web-panel ...>
  <resource name="view" type="soy" location=":soy/My.addOn.tpl.board.config.issueglance"/>
  ...
</web-panel>

together with previously shared snippet for the web-resource

<web-resource key="soy" name="My app soy server-side resources">
      <transformation extension="soy">
          <transformer key="soyTransformer"/>
      </transformation>
      <resource type="soy" name="boardConfigPage" location="templates/boardConfigPage.soy"/>
  </web-resource>

The final note about resource loading phases and the performance:

  • worth considering splitting your feature to init chunk and the lazy-loaded rest; to avoid delaying rendering the whole issue view due to extra resources needed for the panel
  • since Jira 9.0 Issue view pages are using Defer phase by default, so that your code (context) should be also loaded in Defer phase or later
    {webResourceManager_requireResourcesForContext('issueglance')} this call will load the context at require phase, so earlier than Defer, and this can cause some issues if your code requires anything from Jira JS to be available at this moment, apart from performance issues
    See
    https://developer.atlassian.com/server/framework/atlassian-sdk/WRM-resource-loading-phases/ and linked page for changes introduced in Jira 9.0 for more details.

Cheers!

3 Likes

@mrzymski ,
Thank you for the solution!
Yes … I think its messed up and I am not sure of the decorator to be used…I have removed it as of now…

{template .issueglance}
    {webResourceManager_requireResourcesForContext('issueglance')}
    <html>
    <head>
        <meta charset="utf-8"/>
        <meta name="admin.active.section" content="atl.jira.view.issue.right.context">
        <title>SCM Issue Glance</title>
    </head>
    <body>
    <div id="maincontainer">
        <div id="container">
            <script>
            require('wrm/require')('wrc!issueglance');
            </script>
        </div>
    </div>
    </body>
    </html>
{/template}

I have the error fixed with the solution suggestion… however now when I open up the issue view the glance page takes up the entire section

The JQL issue list view shows the issue glance context empty…

Hello,
as the web-panel markup is embedded pretty much as-is, there’s no iframe etc., have you tried with just your app’s panel container <div id="your-app-some-unique-id"> ... </div>?

Cheers!

2 Likes