From b0c18ece0988b1573b2286bb73b32e48a1d8c59a Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 9 Nov 2017 09:46:08 -0600 Subject: Basic manifest docs (#7806) * basic manifest docs * add a bit more documentation * space out fields for better godoc formatting --- model/manifest.go | 100 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 85 insertions(+), 15 deletions(-) diff --git a/model/manifest.go b/model/manifest.go index 501153982..48024fe92 100644 --- a/model/manifest.go +++ b/model/manifest.go @@ -22,40 +22,110 @@ const ( ) type PluginOption struct { + // The display name for the option. DisplayName string `json:"display_name" yaml:"display_name"` - Value string `json:"value" yaml:"value"` + + // The string value for the option. + Value string `json:"value" yaml:"value"` } type PluginSetting struct { - DisplayName string `json:"display_name" yaml:"display_name"` - Type string `json:"type" yaml:"type"` - HelpText string `json:"help_text" yaml:"help_text"` - RegenerateHelpText string `json:"regenerate_help_text,omitempty" yaml:"regenerate_help_text,omitempty"` - Default interface{} `json:"default" yaml:"default"` - Options []*PluginOption `json:"options,omitempty" yaml:"options,omitempty"` + // The display name for the setting. + DisplayName string `json:"display_name" yaml:"display_name"` + + // The type of the setting. + // + // "bool" will result in a boolean true or false setting. + // + // "dropdown" will result in a string setting that allows the user to select from a list of + // pre-defined options. + // + // "generated" will result in a string setting that is set to a random, cryptographically secure + // string. + // + // "radio" will result in a string setting that allows the user to select from a short selection + // of pre-defined options. + // + // "text" will result in a string setting that can be typed in manually. + Type string `json:"type" yaml:"type"` + + // The help text to display to the user. + HelpText string `json:"help_text" yaml:"help_text"` + + // The help text to display alongside the "Regenerate" button for settings of the "generated" type. + RegenerateHelpText string `json:"regenerate_help_text,omitempty" yaml:"regenerate_help_text,omitempty"` + + // The default value of the setting. + Default interface{} `json:"default" yaml:"default"` + + // For "radio" or "dropdown" settings, this is the list of pre-defined options that the user can choose + // from. + Options []*PluginOption `json:"options,omitempty" yaml:"options,omitempty"` } type PluginSettingsSchema struct { - Header string `json:"header" yaml:"header"` - Footer string `json:"footer" yaml:"footer"` + // Optional text to display above the settings. + Header string `json:"header" yaml:"header"` + + // Optional text to display below the settings. + Footer string `json:"footer" yaml:"footer"` + + // A mapping of setting keys to schema definitions. Settings map[string]*PluginSetting `json:"settings" yaml:"settings"` } +// The plugin manifest defines the metadata required to load and present your plugin. The manifest +// file should be named plugin.json or plugin.yaml and placed in the top of your +// plugin bundle. +// +// Example plugin.yaml: +// +// id: com.mycompany.myplugin +// name: My Plugin +// description: This is my plugin. It does stuff. +// backend: +// executable: myplugin +// settings_schema: +// settings: +// enable_extra_thing: +// type: bool +// display_name: Enable Extra Thing +// help_text: When true, an extra thing will be enabled! +// default: false type Manifest struct { - Id string `json:"id" yaml:"id"` - Name string `json:"name,omitempty" yaml:"name,omitempty"` - Description string `json:"description,omitempty" yaml:"description,omitempty"` - Version string `json:"version" yaml:"version"` - Backend *ManifestBackend `json:"backend,omitempty" yaml:"backend,omitempty"` - Webapp *ManifestWebapp `json:"webapp,omitempty" yaml:"webapp,omitempty"` + // The id is a globally unique identifier that represents your plugin. Reverse-DNS notation + // using a name you control is a good option. For example, "com.mycompany.myplugin". + Id string `json:"id" yaml:"id"` + + // The name to be displayed for the plugin. + Name string `json:"name,omitempty" yaml:"name,omitempty"` + + // A description of what your plugin is and does. + Description string `json:"description,omitempty" yaml:"description,omitempty"` + + // A version number for your plugin. Semantic versioning is recommended: http://semver.org + Version string `json:"version" yaml:"version"` + + // If your plugin extends the server, you'll need define backend. + Backend *ManifestBackend `json:"backend,omitempty" yaml:"backend,omitempty"` + + // If your plugin extends the web app, you'll need to define webapp. + Webapp *ManifestWebapp `json:"webapp,omitempty" yaml:"webapp,omitempty"` + + // To allow administrators to configure your plugin via the Mattermost system console, you can + // provide your settings schema. SettingsSchema *PluginSettingsSchema `json:"settings_schema,omitempty" yaml:"settings_schema,omitempty"` } type ManifestBackend struct { + // The path to your executable binary. This should be relative to the root of your bundle and the + // location of the manifest file. Executable string `json:"executable" yaml:"executable"` } type ManifestWebapp struct { + // The path to your webapp bundle. This should be relative to the root of your bundle and the + // location of the manifest file. BundlePath string `json:"bundle_path" yaml:"bundle_path"` } -- cgit v1.2.3-1-g7c22