plugin sdk manifest

manifest definition

{
   "manifest": {
    "schemaVersion":0.0.1,
    "id": "{{devportal-id}}",
    "name": "tw-spaces-core",
    "description": "This is a Teamwork core plugin package including the Checklist and Desk Demo modules",
    "extendedDescription": "s3://tw-spaces-core.html",
    "version": "0.2.5",
    "author": "Spaces team",
    "organisation": "teamwork",
    "repository": "https://github.com/Teamwork/tw-spaces-core-widgets",
    "marketplace":{
     "coverImage":"plugin-cover.png",
     "moduleImages":{
         "checkList":['checklist-img1.png','checklist-img2.png','checklist-img3.png'],
         "fullContact":['full-contact-img1.png','full-contact-img2.png','full-contact-img3.png']
     }
    },
    "settings": {
          "fullContact.apiKey": {
                "displayName": 'The API key for FullContact',
                "type": 'string',
                "defaultValue": '',
                "isPublic": false
           },
           "fullContact.authScheme": {
                "displayName": "The Auth Scheme  for FullContact",
                "type": "string",
                "defaultValue": "Bearer",
                "isPublic": false
           },
           "fullContact.host": {
               "displayName": "The endpoint address for FullContact",
               "type": "string",
               "defaultValue": "https://api.fullcontact.com",
               "isPublic": false
            },
           "fullContant.httpMethod": {
                "displayName": "The http method for calling FullContact",
                "type": "string",
                "defaultValue":"POST",
                "isPublic": false
           }
     },
    "modules": [{
      "name": "Checklist",
      "type": "custom-element",
      "url": "js://Checklist",
      "placements": {
        spaces:['editor', 'inline-comments']
        projects: ['notebooks','tasks-comments']
      },
      "configuration": {
        "customElementName": "tw-spaces-core-checklist",
        "description": "Checklist Component for Spaces Editor",
        "extendedDescription": "s3://full-contact.html",
        "keywords": "[]",
        "editorConfiguration":{
           "attributes": "[]",
           "childNodeNames": "['tw-json']",
           "shouldIncludeInPrint": true,
           "isInlineElement": false,
           "requiresProjects": false,
         },
        "icons": ["checklist-icon-sm", "checklist-icon-md", "checklist-icon-lg"]
      }
    },
    {
      "name": "FullContact",
      "type": "custom-element",
      "url": "js://FullContact",
      "placements": { 
        "desk": ["ticket"]
      },
      "configuration": {
        "customElementName": "tw-desk-full-contact",
        "description": "Desk Full Contact for embedding on Tickets",
        "keywords": "[]",
        "extendedDescription": "s3://full-contact.html",
        "editorConfiguration":{},
        "icons": ["full-contact-icon-sm", "full-contact-demo-icon-md", "full-contact-icon-lg"]
        }
      }
    }
    ]
  }
}

One more thing... perhaps we could rename module.settings to module.config for clarity and to avoid confusion. plugin.settings would then be for user-modifiable settings and module.config would be for read-only module configuration.

OK, so I lifted out installationConfiguration and put it as settings at the plugin level. I have renamed module.settings to module.configuration, I lifted name up to the module level also. I guess I will introduce a manifest-version prop and set that to 0.0.1 @gkubisa

I think its worth introducing a screenshots attribute, an plugin cover image based upon this POC,
https://vue-zeit.shaydoc.now.sh/plugin-packages/tw-spaces-core

I'm now happy with the structure and core properties. Thanks for your patience, Shay! :-)

Regarding the marketplace-related properties, I'd keep them all at the plugin level (like settings). Maybe they could be nested too, to keep it clean: manifest.marketplace.[...]? In there you could just add whatever you need on the page in the marketplace/dev-portal.

PS. "module.settings" -> "module.configuration" (or "module.config") for "FullContact". ;-)

Can we add a plugin level settings page for user configurable settings (the settings pane on a plugin), this could be an area to select a project or add some other property. This should be an object something like pluginConfig:[{"name":"projectID", "displayName":"Enter ProjectID","type":"int", "defaultValue":0}]

Can we change this

 "placements": [
        { "app": "spaces", "location": "editor" }
      ],

to a map instead? This means each app could only have one entry and an array for each location the plugin is supported. Would also make it a bit faster to access the locations for a specific app

"placements":{
"spaces":["editor","comments","inlinecomments"]
}

As discussed in Chat, the id should be a random string (App ID) obtained from the developer portal.

thanks, this should conclude everything for this version

Can we add a plugin level settings page for user configurable settings (the settings pane on a plugin), this could be an area to select a project or add some other property. This should be an object something like pluginConfig:[{"name":"projectID", "displayName":"Enter ProjectID","type":"int", "defaultValue":0}]

My only feeling here, is that feels like plugin instance settings, and would vary from instance to instance, is it necessary if the plugin can self contain this type of config without the need to declare it ?

I think this is just a bad example and the intention is to change the format of the end-user-modifiable plugin-level settings, as we discussed during the meeting.

manifest: {
  settings: [
    {
      name: 'fullContact.apiKey',
      displayName: 'The API key for FullContact',
      type: 'string',
      defaultValue: '',
      isPublic: false
    }
  ]
}

PS. I'm not sure about the best way to handle the proxy settings. Perhaps we could discuss that at our next meeting?

Yep, can discuss at the next meeting, OK, but maybe still a map structure?

  manifest: {
     settings: {
           'fullContact.apiKey': {
                displayName: 'The API key for FullContact',
                type: 'string',
                defaultValue: '',
                isPublic: false
           },
           'fullContact.authScheme': {
                displayName: 'The Auth Scheme  for FullContact',
                type: 'string',
                defaultValue: 'Bearer',
                isPublic: false
           },
           'fullContact.host': {
               displayName: 'The endpoint address for FullContact',
               type: 'string',
               defaultValue: 'https://api.fullcontact.com',
               isPublic: false
            },
           'fullContant.httpMethod':{
                displayName: 'The http method for calling FullContact',
                type: 'string',
                defaultValue:'POST',
                isPublic: false
           }
     }
 }

I don't really mind, if it's an object or an array. Having said that, I think an array gives us a bit more flexibility in terms of defining the settings page, like allowing control over the order of the settings and insertion of auxiliary items like horizontal lines, headers, etc. See also my previous comment.

Is it likely the plugins will be shared and reused across applications ?
Should we have an attribute on the top level to describe what application this plugin is for do we rely on the module placements element ?

Is it likely the plugins will be shared and reused across applications ?

It's really hard to say... I suppose things like Chat, time logging and some other widgets launched from the header could be distributed as plugins.

Should we have an attribute on the top level to describe what application this plugin is for do we rely on the module placements element ?

This information can already be obtained from module placements, however, I think it would be reasonable to have "supported apps" at the plugin-level too, perhaps under the "marketplace" key.

Can we change this

 "placements": [
        { "app": "spaces", "location": "editor" }
      ],

to a map instead? This means each app could only have one entry and an array for each location the plugin is supported. Would also make it a bit faster to access the locations for a specific app

"placements":{
"spaces":["editor","comments","inlinecomments"]
}

I'd like to echo this. It also allows us to get rid of marketplace/supportedApplications. If the key spaces is provided then it's available for spaces, otherwise not. There is a bit of duplication in having both. Additionally when they are keys rather than values it's more clear to describe.

We have already stopped using this gist and moved the information to this Spaces page.

PS. I see the placements property was already updated as you suggested.