diff --git a/packages/lib/services/plugins/utils/manifestFromObject.ts b/packages/lib/services/plugins/utils/manifestFromObject.ts index e9231747c..d509cbce2 100644 --- a/packages/lib/services/plugins/utils/manifestFromObject.ts +++ b/packages/lib/services/plugins/utils/manifestFromObject.ts @@ -1,4 +1,4 @@ -import { PluginManifest, PluginPermission, Screenshot, Icons } from './types'; +import { PluginManifest, PluginPermission, Image, Icons } from './types'; import validatePluginId from './validatePluginId'; export default function manifestFromObject(o: any): PluginManifest { @@ -31,11 +31,15 @@ export default function manifestFromObject(o: any): PluginManifest { return o[name]; }; - const getScreenshots = (defaultValue: Screenshot[] = []): Screenshot[] => { + const getScreenshots = (defaultValue: Image[] = []): Image[] => { if (!o.screenshots) return defaultValue; return o.screenshots; }; + const getPromoTile = (): Image => { + return o.promo_tile || null; + }; + const getIcons = (): Icons => { if (!o.icons) return null; for (const size of [16, 32, 48, 128]) { @@ -62,6 +66,7 @@ export default function manifestFromObject(o: any): PluginManifest { screenshots: getScreenshots(), permissions: permissions, icons: getIcons(), + promo_tile: getPromoTile(), _recommended: getBoolean('_recommended', false, false), }; diff --git a/packages/lib/services/plugins/utils/types.ts b/packages/lib/services/plugins/utils/types.ts index ef19341ae..01e9c5a6e 100644 --- a/packages/lib/services/plugins/utils/types.ts +++ b/packages/lib/services/plugins/utils/types.ts @@ -2,7 +2,7 @@ export enum PluginPermission { Model = 'model', } -export interface Screenshot { +export interface Image { src: string; label: string; } @@ -26,9 +26,10 @@ export interface PluginManifest { repository_url?: string; keywords?: string[]; categories?: string[]; - screenshots?: Screenshot[]; + screenshots?: Image[]; permissions?: PluginPermission[]; icons?: Icons; + promo_tile?: Image; // Private keys _package_hash?: string; diff --git a/readme/api/references/plugin_manifest.md b/readme/api/references/plugin_manifest.md index 004534e39..9328ce8ee 100644 --- a/readme/api/references/plugin_manifest.md +++ b/readme/api/references/plugin_manifest.md @@ -14,8 +14,9 @@ Name | Type | Required? | Description `homepage_url` | string | No | Homepage URL of the plugin. It can also be, for example, a link to a GitHub repository. `repository_url` | string | No | Repository URL where the plugin source code is hosted. `categories` | string[] | No | [Categories](#categories) that describes the functionality of the plugin. -`screenshots` | Screenshot[] | No | [Screenshots](#Screenshot) are used for listing on Joplin Plugin website. +`screenshots` | Image[] | No | [Screenshots](#Screenshot) are used for listing on Joplin Plugin website. `icons` | Icons | No | If [Icons](#Icons) is not supplied, a standard extension icon will be used by default. You should supply at least a main icon, ideally 48x48 px in size. This is the icon that will be used in various plugin pages. You may, however, supply icons of any size and Joplin will attempt to find the best icon to display in different components. Only PNG icons are allowed. +`promo_tile` | Image | No | [Promo tile](#promo-tile) is an optional image that is used to promote your extension on the Joplin Plugins website. ## Categories @@ -29,7 +30,7 @@ Name | Type | Required? | Description | personal knowledge management | managing and organizing notes. | | productivity | making Joplin more productive to use. | | search | enhancing search inside the app. | -| tags |  dealing with note tags. | +| tags | dealing with note tags. | | themes | changing theme of the app. | | viewer | enhancing the rendering of a note. | @@ -46,10 +47,23 @@ Name | Type | Required? | Description | Properties | Description | | --- | --- | -| 16 | a relative path to a PNG icon. | -| 32 | a relative path to a PNG icon. | -| 48 | a relative path to a PNG icon. | -| 128 | a relative path to a PNG icon. | +| 16 | path to a PNG icon. | +| 32 | path to a PNG icon. | +| 48 | path to a PNG icon. | +| 128 | path to a PNG icon. | + +Note: All paths should be relative to the root of the repository. + +## Promo tile + +This is an optional image that is displayed in the Joplin Plugin website main page. It is an opportunity to promote your plugin by using a catchy image. A good way to start with the promo tile is to display your icon or logo and the plugin name next to it. Have a look at the Chrome Web Store [which has many good examples of promo tiles](https://chromewebstore.google.com/category/extensions/lifestyle/social). + +If no promo tile is provided, your plugin icon will be displayed instead. + +| Properties | Description | +| --- | --- | +| src | a path or URL to a screenshot. It must be a **440 x 280 image** JPEG or PNG (no alpha). If a path, `src` should be relative to the root of the repository (e.g. `images/promo_tile.png`). | +| label | description of the image. This label will be used by screen readers or if the image cannot be loaded. | ## Manifest example @@ -64,19 +78,23 @@ Name | Type | Required? | Description "homepage_url": "https://joplinapp.org", "screenshots": [ { - "src": "path/to/image.png", - "label": "image description" + "src": "images/screenshot.png", + "label": "An example of the plugin being used" }, { - "src": "https://example.com/path/to/the/screenshot.png", - "label": "image description" + "src": "https://example.com/images/screenshot.png", + "label": "The plugin loading screen" } ], "icons": { - "16": "path/to/icon16.png", - "32": "path/to/icon32.png", - "48": "path/to/icon48.png", - "128": "path/to/icon128.png" + "16": "images/icon16.png", + "32": "images/icon32.png", + "48": "images/icon48.png", + "128": "images/icon128.png" + }, + "promo_tile": { + "src": "images/promo_tile.png", + "label": "A logo of a plugin on a clear background" } } ```