Fragments

Using ScriptRunner, you can customize the web UI through dynamically adding web fragments. See the Atlassian documentation on web fragments for Confluence.

You can use web fragments to:

  • Show an announcement banner

  • Show different banners for admins, non-admins, and users who are not logged in

  • Add buttons to the Tools menu for particular pages

This is accomplished by adding a UI customization at Administrator > UI Fragments.

Types

There are several different types of fragment scripts available:

  • Web Item - A link or button that appears in your chosen location.

  • Web Panel - Displays additional information in a panel.

  • Web Section - Defines new locations to add items.

  • Web Resource - Defines custom JavaScript and CSS resources in specific contexts.

  • Hide UI Element - Hide any system web item or panel, including ones provided by plugins.

  • XML Module Item - Define a custom web item using raw XML, which gives you more flexibility. 

As always, test in a development environment before deploying to your production environment.

Using Web Fragments

You can add, execute, edit, and delete the scripts from Administrator > UI Fragments. After restarting your instance, the UI customizations are in place. Some scripts are reloaded automatically, but you can edit the script item and click update if they are not.

Keys

When creating web fragments, the key field is required. Be sure to use original keys for each element. Web fragments with reused keys will not function properly.


All of the built-in scripts produce XML that is similar to XML found in a plugin descriptor. You will notice that, for usability reasons, the forms do not provide all the possible configuration elements available in plugins. For example, the web item script does not give you the option to provide a tooltip for the web item link, a velocity context provider, or an icon URL.

You can work around this limitation using the Raw XML Module script.

Fragment Locator 

Finding the locations and/or sections for web items, web sections, and web panels can be difficult. The Fragment Locator tool is designed to show you the places where you can put these fragments. You can enable (and disable) it from the main UI Fragments page.

Enabling the Fragment Locator changes the UI appearance for every user, so it should not be enabled in a production system.

When you turn on the Fragment Locator, you can select Binding Info on the location you select. A window appears where you can copy the binding information to use in your scripts. 

Copy the location path

You can copy the location path by selecting the copy button.


Script Fragment Variables

The variables available to you depends on the fragment location. The Fragment Locator tool can help you see which variables are available, so your scripts run as expected.

Fragment binding variables are context-specific and knowing what is available in certain contexts could help you avoid unexpected scripting errors. After enabling the Fragment Locator, you can hover over a fragment to view available binding variables for an item or panel in a specific context.

For an example, the following image is of the Confluence homepage with the fragment locator enabled: 

Browse Script Fragment Functionality

You can use the Search ScriptRunner Functionality search bar to search the available script fragments.

For example, if you’re looking for a script fragment that works with web items, you could type "web items" and press Enter. Then, the list of script fragments is narrowed down to only those containing the word "web items" in their title or description.

On this page