Fragments Tutorial

Fragments allow you to customize the UI of your Jira instance. Examples are hiding a button, adding a banner, adding a button, or customizing how areas of your Jira instance look.

Before you start this tutorial, make sure you have read the Fragments page for a feature overview. We also recommend that you familiarise yourself with the Atlassian documentation on web fragments. 

Continue reading below for an overview of the key terms you see when creating a UI fragment. Once you're happy with your understanding of UI fragments, try out some of the guided examples below. 

Key terms

There are many terms used within our UI Fragment documentation that may be unfamiliar to you. The following table explains these terms:

Available built-in UI fragments

We have developed a number of built-in UI fragments for you to use to customize your Jira instance:

• Custom web item: Create a custom link or button in a location of your choice.
• Show a web panel: Create a section of HTML content, such as a custom banner, in a location of your choice.
• Create a custom web section: Create a new area, within a location of your choice, that can be used to hold web items.
• Hide system or plugin UI element: Hide buttons, menus, or other UI elements so they are no longer visible for users.
• Constrained create issue dialog: Create a menu item that opens the Create Issue dialog with a predefined project and issue type.
• Planning board context menu item: Create a menu item in the context menu (right-click) of issues in a Scrum or Kanban board.
• Install web resource: Include JavaScript and CSS resources into certain contexts.
• Custom web item provider: Dynamically generate web items according to the current circumstances.
• Raw xml module: Customize your UI using XML alone.

Examples

The following examples walk you through how to use our web fragments feature, starting with simple examples and then moving to more complex examples:

• Create a simple web item
• Create a simple web panel
• Create a drop-down list
• Hide a UI item from certain users

Create a simple web item (add a button to top navigation bar that links to a website)

Great Adventure wants to add a button to the top navigation bar of Jira that leads back to their main website. Using the Web Item Locations page, Great Adventure knows that they want to put their button in the system.top.navigation.bar fragment location. 

1. From ScriptRunner, navigate to Fragments.
2. Select Create Fragment.
3. Select Custom web item.
4. Enter a name for the web item. In this example, we enter Link to Great Adventure Website.
5. Select system.top.navigation.bar for the section this web item should go in.
6. Enter a key for the web item. In this example, we enter great-adventure-web.
7. Enter the menu text for the web item. This is the button text that displays. In this case we enter Great Adventure Website. 
8. Optional: Enter a weight for the web item. In this example, we enter 110 so the button appears to the right of the Assets/Insight menu.
9. Optional: Enter a condition for the web item. For example, you could make sure the button only displays for certain users. 
10. Select Navigate to a link from the drop-down list. 
11. Enter a link for the website. You should use a URL of your choice—in this example we enter a fictitious website URL. 
12. Select Add.
    
    You can now refresh the page to see if this web item has been added.
    

Create a simple web panel (create an announcement banner on the Service Desk portal screen)

It's coming up to the holidays and Great Adventure wants to put an announcement banner on their Service Desk portal to make users aware that there will be less staff than usual to handle any issues. They also want the announcement banner to only display between a set date. Using the Web Panel Locations page, Great Adventure knows that they want to put their banner in the servicedesk.portal.header fragment location. 

1. From ScriptRunner, navigate to UI Fragments.
2. Select Create Fragment.
3. Select Show a web panel.
4. Enter a name for the web panel. In this example we enter Great Adventure Service Desk Holiday Banner.
5. Select servicedesk.portal.header for the section this web panel should go in.
6. Enter a key for the web item. In this example we enter great-adventure-sd-banner.
7. Optional: Enter a weight for the web panel. Weight is only necessary if you have other banners in the same location and wish to have them in a specific order. 

8. Enter a condition for the web panel. In this example we enter a condition so this web panel only displays during a certain time.

   groovy
   def startDate = Date.parse('yyyy-MM-dd', '2023-11-26').clearTime() // replace with your start date
   def endDate = Date.parse('yyyy-MM-dd', '2023-11-28').clearTime() // replace with your end date
   def currentDate = new Date().clearTime()
   
   return currentDate.after(startDate) && currentDate.before(endDate)

9. Enter a script that displays the banner text. In this example we enter the following:

   groovy
   writer.write("<div style='background-color: #ff0000; color: #ffffff; padding: 10px; margin-bottom: 10px; text-align: center'>" +
       "Please note that we currently have a reduced support team due to the holidays." +
       " Please be patient with us as it may take longer than usual to get back to you.</div>")

10. Select Add.
    

    You can test to see if this banner looks correct by adjusting the dates of the condition. 

    

Create a new drop-down list using web items and a web section

Great Adventure wants to create a drop-down list in the top navigation bar with links to other important pages. To create a drop-down list, Great Adventure needs split this task into three main steps:

1. Add a web item to system.top.navigation.bar.
2. Add a web section to web item created in step 1.
3. Add web items to the web section created in step 2. 

The above steps are described in detail below:

Add a web item

1. From ScriptRunner, navigate to UI Fragments.
2. Select Create Fragment.
3. Select Custom web item.
4. Enter a name for the web item. In this example, we enter Great Adventure Drop-down list.
5. Select system.top.navigation.bar for the section this web item should go in.
6. Enter a key for the web item. In this example, we enter item-great-adventure-dropdown.
7. Enter the menu text for the web item. This is the button text that displays. In this case we enter Great Adventure Quick Links. 
8. Optional: Enter a weight for the web item. In this example, we enter 110 so the button appears to the right of the Assets/Insight menu.
9. Select Do nothing - you will use javascript to bind an action from the drop-down list. 
10. Select Add.
    

Add a web section to the web item

1. Select Create Fragment.
2. Select Create a custom web section. 
3. Enter a name for the web item. In this example, we enter Great Adventure Drop-down Web Section.
4. Select item-great-adventure-dropdown for the location of the web section. This is the key name we chose in Add a web item. 
5. Optional: Enter a condition for the web section. For example, you could make sure the web item only displays for certain users. 
6. Enter a key for the web section. In this example, we enter ga-dropdown-list.
7. Select Add.
   

Add web items to the web section

1. Select Create Fragment.
2. Select Custom web item.
3. Enter a name for the web item. In this example, we enter Great Adventure Confluence.
4. Select item-great-adventure-dropdown/ga-dropdown-list for the location of the web item. This is the location generated from the two keys we entered in Add a web item and Add a web item to the web section. 
5. Enter a key for the web item. In this example we enter ga-confluence.
6. Enter the menu text for the web item. This is the button text that displays. In this case, we enter Great Adventure Confluence. 
7. Optional: Enter a weight for the web item. We recommend you add a weight if you have multiple items in the drop-down and wish to order them.
8. Select Navigate to a link from the drop-down list. 
9. Enter a link for the website. You should use a URL of your choice—in this example we enter a fictitious website URL.
10. Select Add.
    
    You can now test this new drop-down list:
    

Hide a UI item for certain users (hide the Create button from certain users)

Great Adventure wants to stop certain users from creating issues. To do this, Great Adventure wants to hide the Create button from Ayla Matic and Gustavo Bishop. 

1. From ScriptRunner, navigate to UI Fragments.
2. Select Create Fragment.
3. Select Hide system or plugin UI element.
4. Enter a name for the UI fragment. In this example, we enter Hide Create Button from Ayla Matic and Gustavo Bishop. 
5. For Hide what enter com.atlassian.jira.jira-header-plugin:create-issue.

6. Enter the following condition:

   groovy
   import com.atlassian.jira.component.ComponentAccessor
   
   def currentUser = ComponentAccessor.getJiraAuthenticationContext().getLoggedInUser()
   def userManager = ComponentAccessor.getUserManager()
   
   def usersToHideFrom = ['amatic', 'gbishop'].collect { userManager.getUserByName(it) } // replace usernames 
   
   return !usersToHideFrom.contains(currentUser)

7. Select Add.
   
   You can test if this UI fragment has worked using the Switch User feature.
   
   
   

Related content

• Fragments
• Custom web item
• Show a web panel