The main file that describes every extension is extension.json
, which is located in the root folder of the extension.
Following structure shows only root
fields of the extension.json. Detailed description about each of those fields is below.
{
// required
"name": "restaurants",
"version": "0.0.1",
"platform": "1.0.*",
// recommended
"title": "Restaurants",
"description": "List restaurants in your app",
"website": "https://www.shoutem.com/restaurants",
"icon": "server/assets/extension/icon.png",
// optional
"settingsPages": [{...}],
"settings": {...},
// optional exports (extension parts)
"shortcuts": [{...}],
"screens": [{...}],
"dataSchemas": [{...}],
"pages": [{...}],
"themes": [{...}],
"themeVariables": [{...}]
}
As you see in Structure of extension.json chapter, extension exports multiple extension parts (shortcuts, screens, dataSchemas, pages, themes, themeVariables). In order to be able to use these extension parts, we need to define them, so we can later reference them in other parts. Defining is done in name
field which value needs to be unique for that extension part (name List
can be only used for 1 shortcut, but also for 1 screen, etc.).
On the other hand, when referencing extension parts, fully qualified name needs to be used. Fully qualified name of extension is done by prefixing <developer-name>.
to name
field (for restaurants
extension developed by shoutem
, extension would have unique identifier shoutem.restaurants
). Fully qualified name of extension parts is done by suffixing <developer-name>.<extension-name>.
with the unique identifier for that extension part, e.g. shoutem.restaurants.List
for shortcut. If you’re referencing the extension part from within the same extension, use @.
instead of <developer-name>.<extension-name>.
(e.g. @.List
).
Here you can find field explanations in the same order fields appeared in the upper example:
Required field. Defines extension’s identity. Must be unique among your extensions and not longer than 32 characters.
Required field. Version of your extension.
Required field. Version of Shoutem platform, which defines versions of React, React Native, Redux and some other packages.
Title of your extension.
Description of your extension.
Website that promotes your extension.
Path to extension’s icon that will be present in Shoutem Extension Market. Store the icon in server
asset’s folder, as it will be used on Shoutem’s server side.
Array of extension settings pages used to manage the global settings of the extension.
[{
// required
"page": "@.Settings",
// recommended
"title": "Settings",
// optional
"parameters": {
"any-parameter": "any-value"
}
}]
Each object in settings pages array, settings page object, consist of these fields:
page
: Required field, references the extension pagetitle
: Title of extension pageparameters
: Dictionary of arbitrary key/value pairs that will be passed to extension settings pageDictionary of arbitrary key/value pairs that represent default extensions’s settings passed to settings pages objects.
{
"any-parameter": "any-value"
}
Shortcuts are links to the starting screen of your extension. Format:
[{
// required
"name": "List",
// required (pick one)
"screen": "@.List",
"action": "@.visitRestaurants"
// recommended
"title": "Restaurants",
"description": "Allow users...",
"icon": "server/assets/shortcuts/restaurants-list.png",
// optional
"type": "navigation",
"adminPages": [{
// required
"page": "@.CmsPage",
// recommended
"title": "Content",
// optional
"parameters": {
"schema": "@.Restaurants"
},
}],
"settings": {
"any-parameter": "any-value"
}
}]
Each object in shortcuts array, shortcut object, consists of these fields:
name
: Required field, defines shortcut’s identityscreen/action
: Shortcut can either open a Screen
or call an Action
(see example in Shoutem Auth extension)title
: Shortcut’s titledescription
: Shortcut’s descriptionicon
: Path to shortcut’s icon that will be shown in builder. Store in server
asset’s foldertype
: Indicates the type of shortcut. It can be navigation
or undefined
. If navigation
, it will be possible to nest other shortcuts below the currentadminPages
: Array of shortcut’s admin pages. Admin page object inside of array consists of:
page
: Required field, references a settings pagetitle
: Title of admin pageparameters
Dictionary of arbitrary key/value pairs that will be passed to admin page instancesettings
: Dictionary of arbitrary key/value pairs that represent default Shortcut’s settings passed to admin pagesScreens are nothing more than React components which represent full mobile screen. Format:
[{
// required
"name": "List",
// recommended
"title": "List",
"image": "server/assets/screens/restaurants-list.png",
// optional
"navigatesTo": [{
"details": "@.Details"
}],
"settingsPage": {
// required
"page": "@.List",
// optional
"parameters": {
"any-parameter": "any-value"
}
},
"settings": {
"any-parameter": "any-value"
}
}, {
"name": "Grid",
"title": "Grid",
"image": "server/assets/screens/restaurants-grid.png",
"extends": "@.List",
"settingsPage": {
"page": "@.List",
"parameters": {
"any-parameter": "any-value"
}
},
}]
Each object in screens array, screen object, consists of these fields:
name
: Required field, defines screen’s identitytitle
: Screen’s title that will be shown in layout selectorimage
: Path to screen’s image that shows it’s layoutnavigatesTo
: Array of key/value pairs that indicates to which screens the current one can navigate tosettingsPage
: Screen’s settings page. Object consists of:
page
: Required field, references an settings pageparameters
: Dictionary of arbitrary key/value pairs that will be passed to settings page instancesettings
: Dictionary of arbitrary key/value pairs that represent default Shortcut’s settings passed to admin pagesextends
: References screen that the current one is extendingIn the example above, we included 2 screen objects inside of the screens
array. We wanted to show you the usage of extends
field. Extending makes it possible to switch between multiple screen layouts.
Data Schemas are Shoutem-flavored JSON Schemas which describe data stored on Shoutem’s CMS.
[{
// required
"name": "Restaurants",
"path": "server/data-schemas/restaurants.json"
}]
Each object in data schemas array, data schema object, consists of these fields:
name
: Required field, defines data schema’s identitypath
: Required field, path to actual schema implementation. Should be stored in server
folderSettings pages are web pages written by extension developers. They can be used to manage 3 different types of settings:
settingsPages
in the root of extension.json)adminPages
in the shortcut object)settingsPage
in the screen object)[{
// required
"name": "List",
"type": "html",
"path": "server/assets/pages/tab-bar/index.html"
}],
Each object in pages array, extensions page object, consists of these fields:
name
: Required field, defines extension page’s identitytype
: Required field, defines type of an extension. Only html
available for nowpath
: Required field, path to actual extension page implementation. Should be stored in server
folderThemes represent files where you can provide set of styles for your UI components.
[{
// required
"name": "Rubicon",
// recommended
"title": "Rubicon",
"description": "Rubicon is a beautiful template built...",
"showcase": ["server/assets/theme/rubicon.mp4","server/assets/theme/rubicon1.jpg", "server/assets/theme/rubicon2.jpg", "server/assets/theme/rubicon3.jpg"],
// optional
"icons": "app/themes/Rubicon/assets/icons/",
"themeVariables": "@.Rubicon"
}]
Each object in themes array, theme object, consists of these fields:
name
: Required field, defines theme’s identitytitle
: Theme’s titledescription:
Theme’s descriptionshowcase
: Array of strings which represent paths to multimedia files in server
folder, such as videos and images, which present your theme. Dimensions for @2x quality resolution are 750 × 1334.icons
: Path to icons of theme, should be stored in app
asset’s foldervariables
: Reference to variables used by themeTheme variables are used to define the structure of the variables used by theme. These variables can be used to customize the theme.
[{
// required
"name": "Rubicon",
"path": "server/themes/rubiconVariables.json"
}]
Each object in theme variables array, theme variables object, consists of these fields:
name
: Required field, defines theme variables namepath
: Required field, path to actual theme variables implementation. Should be stored in server
folderFinally, here’s the full example of extension.json:
{
"shoutem": "1.0",
"name": "restaurants",
"version": "0.0.1",
"title": "Restaurants",
"website": "https://extensions.shoutem.com/shoutem.navigation",
"description": "Make your users rate products.",
"icon": "server/assets/extension/icon.png",
"defaultLocale": "en",
"settingsPages": [{
"page": "@.settings",
"title": "Settings",
}],
"settings": {
"any-parameter": "any-value"
},
"shortcuts": [{
"name": "List",
"title": "Restaurants",
"description": "Allow users...",
"screen": "@.list",
"icon": "theme://events.png",
"adminPages": [{
"page": "@.CmsPage",
"title": "Content",
"parameters": {
"schema": "@.Restaurants"
},
}],
"settings": {
"any-parameter": "any-value"
}
}],
"screens": [{
"name": "List",
"title": "List",
"image": "server/assets/screens/restaurants-list.png",
"navigatesTo": [{
"details": "@.Details"
}]
}, {
"name": "Grid",
"title": "Grid",
"image": "server/assets/screens/restaurants-grid.png",
"extends": "@.List",
}, {
"name": "Details",
"title": "Details",
}],
"pages": [{
"name": "settings",
"path": "server/assets/settings/settings/index.html",
}],
"dataSchemas": [{
"name": "Restaurants",
"path": "server/data-schemas/restaurants.json"
}],
"themes": [{
"name": "Rubicon",
"title": "Rubicon",
"variables": "@.Rubicon",
"description": "Rubicon is a beautiful template built...",
"showcase": ["server/assets/theme/rubicon.mp4","server/assets/theme/rubicon1.jpg", "server/assets/theme/rubicon2.jpg", "server/assets/theme/rubicon3.jpg"],
"icons": "app/themes/Rubicon/assets/icons/"
}, {
"name": "Arno",
"title": "Arno",
"variables": "@.Rubicon",
"description": "Arno is a beautiful template built...",
"showcase": ["server/assets/theme/arno1.jpg", "server/assets/theme/arno2.jpg"],
"icons": "app/themes/Arno/assets/icons/"
}],
"themeVariables": [{
"name": "Rubicon",
"path": "server/themes/rubiconVariables.json"
}]
}