-
-
Save shaydoc/3d52670c7874f52f79ca14fbc9e29bdd to your computer and use it in GitHub Desktop.
| { | |
| "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"] | |
| } | |
| } | |
| } | |
| ] | |
| } | |
| } |
The example for me here is say I have:
- Google Calendar Module
- MS Outlook Calendar Module
- Figma Module
I need to set api keys for both against my installation, in that way it makes sense to have these at a module setting level @gkubisa
This would likely be the case withintw-spaces-core-widgetsrepo if we added these modules to our plugin package.
I would have each calendar integration in a separate plugin. :-) If they need to share code, they can do so through node modules. This way many plugins can be very small and simple, often containing only a single module. I think it would actually be easier for users, as most would use only a single calendar integration. So, if they use Google Calendar, they install the Google Calendar plugin and see only Goolge Calendar settings. It's also easier from the developer's point of view, as each plugin can be developed, tested, updated and published separately - plus we can naturally keep all user-modifiable setting at the plugin-level. ;-)
Another reason for having each calendar (or any other single well defined feature) in a separate plugin is that we might want to extend it later, for example so that it would work in more than one of our apps. This is naturally much easier to do when the scope of the plugin is smaller, eg only Google Calendar, instead of an arbitrary group of calendars (assuming we'd want to maintain feature parity between all (calendar) modules in a single plugin, which I think we should do, if we went that route).
Even though most plugins will be simple, often with only one module, I still think the concept of modules is very useful, as some features will require more than just a custom element. For example, you'd want a SingleTeamworkTask editor component module and an associated paste handler module in the same plugin, so that when you paste a link to a task, the paste handler rewrites the pasted content to create an instance of the SingleTeamworkTask component. Another example could be an editor component module and a sidebar component module, which aggregates the data from the editor components, eg extracts all CheckListItems from the content.
Regarding tw-spaces-core-widget, I think it's ok, if it contains multiple unrelated editor component modules as long as they don't require any user configuration. Then again, I wouldn't mind if it was split into multiple plugins. If they are all automatically enabled on all installations, the user wouldn't see a difference anyway.
I understand the idea here. And that makes sense that a plugin would typically contain a single module.
The only concern this may present is the bundle sizes when splitting our own vue based modules into to separate plugins. That means we would unnecessarily ship vue, vuex vuerouter as part of every bundle. In this way maybe it is preferable to keep them as a list of modules and therefore including module configuration for an installation. The only other issue splitting raises is additional script overhead to the document in spaces, instead of registering one lightweight script that supports maybe 50 or 60 good plugin modules built by ourselves, we would be adding alot of blocking script references at runtime ?
That's a very good point about the bundle sizes. Could we provide an option in the (webpack) SDK to choose whether Vue and Vuex should be bundled, or reused from the host application?
The number of scripts shouldn't be a big problem I think... Caching would help a lot (except for the first load). They could be loaded in parallel with HTTP/2. We could also preload them in the background.
Having said that, bundling lots of modules is still an option for me, as long as we manage to keep it all simple and flexible for end users, plugin developers and SDK developers. :-) I think it is possible, however, I'd still keep all user settings at the plugin level. Apart from simplifying module definitions, a big reason is that the same setting might be applicable to multiple modules, or it might affect modules which the user shouldn't need to know about (eg a paste handler), so we'll need plugin-level settings anyway. What I'm after is basically to decouple settings from modules. Perhaps instead of supporting both plugin and module level user-modifiable settings we could have only plugin-level settings and enrich the definition format in the manifest to support sections/headings? Something like this:
manifest: {
settings: [
{ type: 'heading', text: 'General' },
{ type: 'select', name: 'general.startOfWeek', label: 'Start of Week', options: ['Monday', 'Sunday'] },
{ type: 'select', name: 'general.display.type', label: 'Display Type', options: ['compact','full'] },
{ type: 'heading' , text: 'Google Calendar' },
{ type: 'input', name: 'google.apiKey', label: 'API Key', default: '' },
]
}
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.
The example for me here is say I have:
I need to set api keys for both against my installation, in that way it makes sense to have these at a module setting level @gkubisa
This would likely be the case within
tw-spaces-core-widgetsrepo if we added these modules to our plugin package.