"plugin.json" File
plugin.json
is main configuration file used to configure the preferences for your plugin.
Config File Elements:
Author
author
(required): the developer/author's name for the plugin.example:
"author":"Harry Potter"
Plugin Name
pluginName
(required): the name for the plugin.example:
"pluginName":"Event Calendar"
Plugin Description
pluginDescription
(required): a short and meaningful description for your plugin .example:
"pluginDescription":"This is a simple Event Calendar plugin"
Support Email
supportEmail
(required): the support email for the plugin which will be used by App Owners for reporting bugs or suggestions.example:
"supportEmail":"support@buildfire.com"
Support Site
supportSite
: a url that will be used in the Control Panels > Plugin Help button. This will open up a new browser window with the url given.example:
"supportSite":"http://learn.appdocumentation.com/plugin-tutorials/using-the-text-wysiwyg-feature"
Disable Delete
disableDelete
: if set to true, once the plugin has been added to an app, it can't be deleted.example:
"disableDelete": true
Singleton
singleton
: if set to true, once the plugin has been added to an app, another instance can't be added.example:
"singleton": true
Menu
menu
: allows you to add a link to your plugin instance(s) from the left hand navigation of the control panel. The menu item can be a top level link, or can be a submenu item under one of these sections "Nav Root Level, App Components, Design, Security, Commerce, Notifications, Users, and Advanced". You can specify the text used for the menu item, and the order to display the menu item. The sort is ordered from lowest to highest. For example, and item with a sort of 1, will appear before an item with a sort of 2. The out of the box menu items have a sort of 0. Therefore if you wish your menu item to come before the out of the box menu items, you need to specify a negative number. Each plugin can have one menu item. A single app can have multiple custom menu items; one for each plugin that specifies a custom menu item. The sort order between menu items is respected.Menu object will have these three properties:
root
:rootLevel
: indicates that menu item will be at the root level.appComponents
: indicates that menu item will be under App Components section.design
: indicates that menu item will be under Design section.security
: indicates that menu item will be under Security section.commerce
: indicates that menu item will be under Commerce section.notifications
: indicates that menu item will be under Notifications section.users
: indicates that menu item will be under Users section.advanced
: indicates that menu item will be under Advanced section.
item
: Plugin or item name that will appear as menu item name.sort
: For sorting menu items.icon
: Icon class name to be previewed in the Control Panel menu. Check all available Control Panel Icons.
Example 1
"menu": {
"root": "appComponents", // Submenu item under App Components section.
"item": "My Plugin",
"sort": -1, //Appear as the first item in the submenu
"icon": "icon-star" //Control Panel icon
}
Example 2
"menu": {
"root": "rootLevel", //Top level menu item
"item": "My Plugin",
"sort": 1, //Appear on the bottom
"icon": "icon-users" //Control Panel icon
}
Control
control
(required): this element will be used to enable/disable the plugin major components (Content, Design, Settings) and allows defining additional Custom Tabs to show on the control, Remove Header to hide the control's header and Height to set the height of the control (in pixels).
Example
"control": {
"content": {
"enabled": true
},
"design": {
"enabled": true
},
"settings": {
"enabled": false
},
/* optional */
"customTabs": [
{ "title": "BuildFire.com", "url": "http://www.buildfire.com" },
{ "title": "Custom Control", "url": "/customTab/index.html" }
],
"removeHeader": true,
"height": 600
}
CSS Injection
- to know more about this tab please check
CSS Injection Documentation
Language Settings
- to know more about this tab please check
Language Settings Documentation
Custom Tabs
customTabs
(not required): tabs defined here will be appended to the control tabs and will have the specified URL loaded into the tab when opened. If the URL is a relative URL then it must map to a local file under Control folder.
Widget
widget
(not required): this element will be used to show/hide the emulator on the BuildFire control panel and make your plugin controller full width when your plugin gets loaded on the control panel. for additional info on background services please checkBackground Services
Example
"widget": {
"enabled": true,
"service": "service.html"
}
Features
features
: the supported features for your plugin.
Example
"features": [
{ "name": "GPS" },
{ "name": "Bluetooth" }
]
Languages
languages
: the supported languages for your pluginexample:
"languages": ["en" , "fr"]
noteYou must use the abbreviation for the language.
Enable Offline Support
enableOfflineSupport
: this element will be used to specify whether the plugin on the mobile device side supports working offline (without an internet connection) or does the plugin not support this feature. An example is if your plugin pulls content from third party server, it will work on offline mode.example:
"enableOfflineSupport": true
noteDatastore operations are supported in both online and offline mode.
Media
media
(not required): allow you to provide screenshots and video that showcase your plugin feature and functionality on the control panel market place, you can help your plugin attract new users, in casemedia
is not provided in the config file theimage.png
in theresources
folder will be used to showcase your plugin in the marketplace.Media will be array of objects and can't be empty and each object should have two properties:
type
:image-resource
: indicates that media is an image and it's located inside the resources folder for the plugin.image
: indicates that media is an image and it should be fetched from external URL.youtube-video
: indicates that media is youtube video and it should be fetched from external URL.
path
: the path for the resource inside the resources folder or the URL for the external resource.
youtube-video
&& image
types will be fetched from external URL and no need to be stored in the resources folder but for image-resource
the image should be exists in the resources folder, otherwise you get an error while trying to upload the plugin through the developer portal.
Example
"media": [
{ "type": "image-resource", "path": "promo.gif" },
{
"type": "image",
"path": "https://buildfire.com/wp-content/uploads/2018/11/app-builder@2x.jpg"
},
{
"type": "youtube-video",
"path": "https://www.youtube.com/embed/Y_MjvCy8Ugo"
}
]
Keywords
keywords
(not required / max 255 characters): hidden keywords which will be used to filter out your plugin in the marketplace when the app owner search for plugins, this will increase your plugin discoverability in the marketplace.example:
"keywords": "social,twitter,tweets "
Require Login
requireLogin
(not required): this element will be used to force the user to login before the app load the widget.example:
"requireLogin": true
The element will be available after plugin is published and opened in Control Panel
Uses API Keys
usesApiKeys
(not required): Allows you to list standard API keys that your plugin uses. Declaring an API key inusesApiKeys
ensures that the app owner fills the specified keys for your plugin to work properly.
Example
"usesApiKeys": [
{ "name": "googleApiKey" },
{ "name": "googleMapKey" }
]
Only add an API key name if your plugin requires it to function properly, otherwise avoid adding it.
Currently we only support Google API Key and Google Maps Key.
API key name
property should match it's corresponding key in API keys
A simple example of plugin.json file:
{
"author":"Harry Poter",
"pluginName":"Hello World",
"pluginDescription":"A simple hello world plugin",
"supportEmail":"support@buildfire.com",
"control":{
"content":{
"enabled":true
},
"design":{
"enabled":false
},
"settings":{
"enabled":false
}
},
"features" : [],
"languages" : ["en"]
}
A full example of plugin.json file:
{
"author": "Harry Poter",
"pluginName": "Event Calendar ",
"pluginDescription": "This is a simple Event Calendar",
"supportEmail": "support@buildfire.com",
"supportSite": "http://learn.appdocumentation.com/plugin-tutorials/using-the-text-wysiwyg-feature",
"control": {
"content": {
"enabled": true
},
"design": {
"enabled": true
},
"settings": {
"enabled": false
}
},
"widget": {
"enabled": true,
"service": "path_to_background_service.html"
},
"features": [{ "name": "GPS" }, { "name": "Bluetooth" }],
"languages": ["en", "fr"],
"enableOfflineSupport": true,
"media": [
{ "type": "image-resource", "path": "promo.gif" },
{
"type": "image",
"path": "https://buildfire.com/wp-content/uploads/2018/11/app-builder@2x.jpg"
},
{
"type": "youtube-video",
"path": "https://www.youtube.com/embed/Y_MjvCy8Ugo"
}
],
"keywords": "events,scheduling",
"requireLogin": true,
"usesApiKeys": [{"name": "googleMapKey"}]
}