Social - GUI - Modules - Install

Owned by AlexI (Unlicensed)
Last updated: May 19, 2015 by andrew johnston (Unlicensed)
3 min read
/social/gui/modules/install

Note - the "widget uploader" (widgetUploader.jsp) should be used in most cases, rather than this lower level call.

Used to POST a JSON object (specified below) to upload widget metadata (not the widget itself, which is stored separately either on a filesystem or via the sharing API.

Once the metadata has been successfully uploaded, the widget can be accessed from the GUI's module browser.

A simple web-based utility is available for installing widgets in one step.

Authentication

Required, see Auth - Login

Arguments

The content must be POSTed as a JSON object in the following format (see also the "get" API call.

{
    "_id": string, // Optional - auto-generated if not specified. If the "_id" is specified then updates the module as described below.
    "url": string, // Will normally either be a public URL or the location of a shared object in Infinit.e.
    "title": string, // The widget title displayed in the widget browser and on the widget window title bar
    "description": string, // A description of the widget, displayed in the widget browser
    "version": string, // An arbitrary string used for external versioning
    "imageurl": string, // The URL of an image used to represent the widget in the GUI framework (again normally either a public URL or share)
    "communityIds": [ string ], // The communities with which to share the module (must be owner/moderator/admin to share a module)
    "searchterms": [
        string // A list of strings that are used in the "modules/search" API call
    ]
}

There are 2 ways a module can be updated rather than uploaded:

  • If the "_id" is specified and matches an existing module
  • If no "_id" is specified but the owner has already uploaded a widget with the same "url"
    Modules can only be updated either by the owner or by the system administrator.

Note also that the URL can contain the special variable "$infinite/". This is replaced at runtime with the URL from which Infinit.e is currently running (eg in the SaaS version, "http://infinite.ikanow.com/api/"). This is particularly useful when using the share API, eg:

{
    //...
    "url": "$infinite/share/get/4d88d0f1f9a624a4b0c8bd71"
    //...
}

Note finally that the following fields are added to the uploaded/updated JSON object (and are retrieved via the "module/get" API call):

{
    //...
    "_id": string, // If not specified
    "created": string, // First time inserted, the Unix time in ms
    "modified": string, // Each time created or modified, the Unix time in ms
    "author": string, // The (unique) email address of the uploader
    "approved": boolean, // Currently hardwired to true
    //...
}
Example
#bash> curl -XPOST 'http://infinite.ikanow.com/social/gui/modules/install' -d '{
    "url": "$infinite/share/get/4d88d0f1f9a624a4b0c8bd71",
    "title": "Test widget",
    "description: "A widget designed to test some new visualization",
    "version": "0.9",
    "imageurl": "$infinite/share/get/4d88d0f1f9a624a4b0c8bd72",
    "searchterms": [ "test", "visualization" ]
}'

A normal set of steps would be to upload the widget and thumbnails using the share API (saving the returned "_id"s, then upload the widget metadata as above, then test, then finally share the uploaded binaries to the relevant communities to let other users access them).

Note that there is currently a limitation in the above scenario, that all widget metadata are currently visible to all users (even though the share API protects access to the binaries themselves). A future release will fix this limitation.

Response

The response format is straightforward, and most easily shown with this example:

{
    response:
    {
        action: "Install Module",
        success: true,
        message: "module installed/updated successfully" // (or the error message if success:false)
    },
    data:
    {
        _id: "4d88d0f1f9a624a4b0c8bd71", // The _id of the store, used for updating/deletion
        approved: true // Currently hardwired to true, since no approval mechanism currently exists
    }
}