Skip to main content

"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: 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​

Language Settings​

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 check Background 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 plugin

    example: "languages": ["en" , "fr"]

    note

    You 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

    note

    Datastore 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 case media is not provided in the config file the image.png in the resources 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.
IMPORTANT

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

note

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 in usesApiKeys ensures that the app owner fills the specified keys for your plugin to work properly.

Example

"usesApiKeys": [
  { "name": "googleApiKey" },
  { "name": "googleMapKey" }
]
note

Only add an API key name if your plugin requires it to function properly, otherwise avoid adding it.

info

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"}]
}