Modules, Components, and Children

Three of the most important concepts to understand when creating apps with App Maker are Modules, Components, and Children.

Apps are a hierarchy of components, each nested within each other (think "Russian nesting doll" - but Australian, and with a lot more JSON...)

REMINDER

• Modules: App Maker support various areas where you can mount your apps into the UI of Atlassian products. These areas are called modules.

• Components: Inside those modules, you will create apps composed of a series of nested Components.

• Children: Each Component can have a series of children Components. This is how you create "nesting"; that is, the hierarchical structure.

Using Different Modules

Adding apps to different modules within the UI is as simple as updating a single field in the request you made to create your first app.

1. Open up your API client from the Getting Started guide.
2. Update the "module" field from jira:issueContext to jira:issueActivity, as shown below.

{
  "resourceType": "site",
  "module": "jira:issueActivity", 
  "title": "my-first-app",
  "action": "set",
  "componentData": {
    "type": "StackedInformationGroup",
    "title": "My First App",
    "children": [
      {
        "type": "FieldValue",
        "key": "App Name",
        "value": "My First App"
      }
    ]
  }
}

3. You'll notice that we're using the same title as before! This is fine in this context because we're creating this app in a different module.

WARNING

Apps within the same module must have unique title values to avoid overwriting each other.

3. Press Send in your API client.
4. Observe the API response. Wait... what? 🙈 You should now see an error!
5. On to debugging!

Debugging Component Errors

TIP

We put a lot of effort in to making sure our error messages are as helpful as possible. If you ever get stuck, make sure to read the error messages you are receiving.

1. You should receive an error saying something like Invalid top-level component type for module jira:issueActivity. Expected TabPanel, got StackedInformationGroup.
   • In this case, you're trying to create an App in the "jira:issueActivity" module, but you have a "StackedInformationGroup" component at the top-level of your app, which the module does not support.
   • Most modules have a specific type of component they need to have at the top level, so that App Maker can ensure your apps are displayed consistently.
     • To see the full list of Components available, check out the Components reference.
     • To see the details of all the different modules and the components they support, check out the Modules reference.

NOTE

A quick look at the Modules documentation reveals that the jira:issueActivity reference requires a "tabPanel" at the top level. This is because we often use a tabbed layout to allow you to have multiple unrelated apps within the same area of the UI.

2. Now that we know what, why, and where the problem is, on to fixing the error!

Fixing The Error

TIP

Most modules require a "TabPanel" component at the top level of your app.

1. Inside componentData, change the value of type to use the TabPanel component as the top level in your app, as shown below.

{
  "resourceType": "site",
  "module": "jira:issueActivity",
  "title": "my-first-app",
  "action": "set",
  "componentData": {  
    "type": "TabPanel"
  }  
}

2. According to the TabPanel reference, the TabPanel component needs a tabTitle property. The tab title populates the tab button text, which will hold the panel your app will display in.

{
  "resourceType": "site",
  "module": "jira:issueActivity",
  "title": "my-first-app",
  "action": "set",
  "componentData": {
    "type": "TabPanel",
    "tabTitle": "My First App Tab"
  }
}

3. Now, add a children property.

{
  "resourceType": "site",
  "module": "jira:issueActivity",
  "title": "my-first-app",
  "action": "set",
  "componentData": {
    "type": "TabPanel",
    "tabTitle": "My First App Tab", 
    "children": []  
  }
}

4. Now we can begin building out our app. Add a "StackedInformationGroup" inside children, like we used for our first app, as shown below.
   1. Note that the children components are arranged in a list, wrapped with square brackets [...].
   2. Many components support children. This is how the App Maker UI system works. You nest components inside each other to create the layout and UI you want to show to your users.

{
  "resourceType": "site",
  "module": "jira:issueActivity",
  "title": "my-first-app",
  "action": "set",
  "componentData": {
    "type": "TabPanel",
     "tabTitle": "My First App Tab",
     "children": [
        {
           "type": "StackedInformationGroup",
           "title": "My First Child Component",
           "children": [ 
              { 
                 "type": "FieldValue", 
                 "key": "App Name", 
                 "value": "My Second App"
              } 
           ] 
        }
     ]
  }
}

4. Press Send in your API client.
5. You should see a success message instead of that annoying error from before.
6. Head back to Jira and refresh an Issue.
7. At the bottom of the issue where you usually see things like "Comments", there will be a "Custom Apps" button. Locate and click the "Custom Apps" button to activate the App Maker module.
8. A new panel will appear below! It will load for a few seconds, and then your new app will appear inside the tab you created.

Next Steps

Awesome work! You've learned how to create apps in different areas of the UI, how to debug errors and use different top-level Components, and how to nest Components inside each other to create more sophisticated UI.

Next, we're going to take a quick look at the UI Update JSON object you've been using so you can understand how it all works.