Yes

This property allows you to specify the container types your custom content can appear in, and its supported child content types. It also allows you to enable indexing of your custom content.

This property allows you to specify the container types your custom content can appear in, and its supported child content types. It also allows you to enable indexing of your custom content.

1
2
{
  "bodyType": "storage",
  "supportedContainerTypes": [
    "page",
    "space"
  ],
  "supportedChildTypes": [
    "attachment",
    "comment"
  ],
  "supportedSpacePermissions": [],
  "preventDuplicateTitle": false,
  "indexing": {
    "enabled": true
  }
}

In the above example, you'll see we specify content type keys in the supportedContainerTypes and supportedChildTypes fields. There are 2 categories of content type you can reference \u2013 built-in content and custom content.

Built-in content types example

• Be contained in a space or a page
• Have a child comment or a child attachment

1
2
{
  "bodyType": "storage",
  "supportedContainerTypes": [
    "page",
    "space"
  ],
  "supportedChildTypes": [
    "attachment",
    "comment"
  ],
  "supportedSpacePermissions": [],
  "preventDuplicateTitle": false,
  "indexing": {
    "enabled": true
  }
}

Custom content example

• Be contained in a content item with type type1 or type2, defined in the app with the key my-first-addon
• Have a child of a content item with type type1 or type2, defined in the app with the key my-second-addon

1
2
{
  "bodyType": "storage",
  "supportedContainerTypes": [
    "ac:my-first-addon:type2",
    "ac:my-first-addon:type1"
  ],
  "supportedChildTypes": [
    "ac:my-second-addon:type1",
    "ac:my-second-addon:type2"
  ],
  "supportedSpacePermissions": [],
  "preventDuplicateTitle": false,
  "indexing": {
    "enabled": true
  }
}

Raw body type custom content example

1
2
{
  "bodyType": "raw",
  "supportedContainerTypes": [
    "space"
  ],
  "supportedChildTypes": [],
  "supportedSpacePermissions": [],
  "preventDuplicateTitle": false,
  "indexing": {
    "enabled": true
  }
}

Content with a raw body looks like this:

1
2

 {
     "title": "My title",
     "space": {"key": "DS"},
     "type": "ac:add-on-key:module-key",
     "body": {
         "raw": {
             "value": "{\"field\": \"value\"}",
             "representation": "raw"
         }
     }
 }
 

• storage
• STORAGE
• raw
• RAW

Defines the content body type of this custom content. Currently supported content body types are:

• storage: This is Confluence's default storage representation which can be rendered using the Content Body Conversion API
• raw: This representation is used for storing raw data in the body that is not storage format, this format is opaque to Confluence

Defines how this content type will be indexed

Defines how this macro parameter will be indexed for site search

1
2
{
  "enabled": true
}

The macro parameter indexing property allows apps to hook into the mechanism by which Confluence populates its search index for site search. Each time macro is created or updated in Confluence, the value that is stored in the macro parameter will be added to the search index. The value of this macro parameter will also be used in displaying the excerpt text for search result.

This is useful when the body of the macro is not searchable, for example: macros with bodyType: none. The app can still provide meaningful search text for this content by storing the extracted information to the macro parameter. The data in this macro parameter will get indexed as is without any modification.

Defines whether Confluence should prevent content with duplicate title from being created in the same space or container.

Defines types that can be contained in this custom content.
Currently supported content types:

• attachment: This custom content can contain attachment.
• comment: This custom content can contain comment.
• Any other custom content type defined in the same app.
  Please refer to The content type key for how to construct the content type key.

Defines the space permissions that this custom content supports. Allowable values are : read, create and delete. It is required that these permissions be granted through the space permissions UI in order to perform the given operation.

Otherwise the default permissions will be used.

A key to identify this module.

This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be globally unique.

Keys must only contain alphanumeric characters and dashes.

The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on key and module key.

A human readable name.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Yes

Declares information for rendering the custom content in the UI.

Declares information related for rendering the custom content in the UI.
Add-ons have the ability to control the UI components for user to view the custom content.

1
2
{
  "contentViewComponent": {
    "addonKey": "addon-key",
    "moduleKey": "general-page-module-key"
  }
}

View component example

1
2
{
  "url": "/my-general-page?content.plugin={content.plugin}&content.id={content.id}&content.version={content.version}&space.key={space.key}&customParameter={ac.customData}",
  "name": {
    "value": "My viewer page"
  },
  "key": "my-viewer"
}

And also the general page is used as a view component in ui support section.

1
2
{
  "contentViewComponent": {
    "moduleKey": "my-viewer"
  }
}

When a user clicks the title of the corresponding custom content in the search result. /my-general-page will be rendered in a iframe with following context parameters being passed.

• content.plugin: The content type key of the content. eg: ac:addon-key:module-key
• content.id: The id of the content
• content.version: The version of the content
• space.key: The key of the space which content is contained in

Context Parameters

Yes

Defines icons used for displaying the content.

Defines icons that used for displaying the custom content.

1
2
{
  "item": {
    "width": 16,
    "height": 16,
    "url": "/item.png"
  }
}

Defines the breadcrumbs used in

• Result of quick search dropdown
• Result of site search

Defines the breadcrumbs for this content

Use Relation API to generate breadcrumbs

1
2

 ...
 "breadcrumbs": {
   "relations": [
     {
       "name": "worksFor"
     }
   ]
 }
 ...
 

And we have following custom content created in the Confluence:

Defines a module for adding or editing custom content.
The module referenced must be a generalPage. Following context variable will be provided to the edit component URL

• customcontent.create: Indicates whether user is creating or editing a piece of custom content

Confluence will provide the breadcrumbs, title input, submit and cancel button on the edit component. Add-on needs to supply the editor area like the screenshot shown below in a general page module.
Please refer to the Custom Content JavaScript API for how to intercept the edit component events and override the default behavior.

A reference to a module defined in either this or another add-on

1
2
{
  "addonKey": "addon-key",
  "moduleKey": "general-page-module-key"
}

Defines the label for cancel button on edit component

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
{
  "value": "My text"
}

Defines the label for submit button on edit component

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
{
  "value": "My text"
}

Defines a placeholder for title input box that will be used in the edit component. Following variables will be replaced at runtime:

• {spaceName}: Name of the current space
• {spaceKey}: Key of the current space
• {contentTypeName}: Name of the current custom content

For example:
"What do you want to know about {SpaceName}" will become "What do you want to know about Demonstration Space" if user is creating a new piece of custom content in "Demonstration Space" space.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
{
  "value": "My text"
}

Defines a module that will be used when a user clicks the navigation link displayed in the space sidebar.
The module referenced must be a generalPage. A default list view will be provided if no view component was specified in this field.

A reference to a module defined in either this or another add-on

1
2
{
  "addonKey": "addon-key",
  "moduleKey": "general-page-module-key"
}

The description of the custom content

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
{
  "value": "My text"
}

The localization key for the human-readable value. Translations for the keys are defined at the top level of the add-on descriptor.