From d2cff9b77cca87c339e65591179a2d7456a6915a Mon Sep 17 00:00:00 2001 From: Chris Date: Fri, 3 Nov 2017 11:34:44 -0500 Subject: more plugin doc updates (#7767) --- plugin/api.go | 6 ++++-- plugin/example_hello_user_test.go | 38 ++++++++++++++++++++++++++++++++++++++ plugin/example_hello_world_test.go | 20 ++++++++++++++++++++ plugin/example_hooks_test.go | 38 -------------------------------------- plugin/hooks.go | 8 ++++---- plugin/plugin.go | 12 ++++++++++++ plugin/supervisor.go | 3 ++- 7 files changed, 80 insertions(+), 45 deletions(-) create mode 100644 plugin/example_hello_user_test.go create mode 100644 plugin/example_hello_world_test.go delete mode 100644 plugin/example_hooks_test.go create mode 100644 plugin/plugin.go diff --git a/plugin/api.go b/plugin/api.go index d7443d813..8d27bc794 100644 --- a/plugin/api.go +++ b/plugin/api.go @@ -7,8 +7,10 @@ import ( "github.com/mattermost/mattermost-server/model" ) -// API implementations can be used to retrieve data or perform actions on behalf of the plugin. Most -// methods have direct counterparts in the REST API and very similar behavior. +// The API can be used to retrieve data or perform actions on behalf of the plugin. Most methods +// have direct counterparts in the REST API and very similar behavior. +// +// Plugins can obtain access to the API by implementing the OnActivate hook. type API interface { // LoadPluginConfiguration loads the plugin's configuration. dest should be a pointer to a // struct that the configuration JSON can be unmarshalled to. diff --git a/plugin/example_hello_user_test.go b/plugin/example_hello_user_test.go new file mode 100644 index 000000000..4aefbc5f5 --- /dev/null +++ b/plugin/example_hello_user_test.go @@ -0,0 +1,38 @@ +package plugin_test + +import ( + "fmt" + "net/http" + + "github.com/mattermost/mattermost-server/plugin" + "github.com/mattermost/mattermost-server/plugin/rpcplugin" +) + +type HelloUserPlugin struct { + api plugin.API +} + +func (p *HelloUserPlugin) OnActivate(api plugin.API) { + // Just save api for later when we need to look up users. + p.api = api +} + +func (p *HelloUserPlugin) ServeHTTP(w http.ResponseWriter, r *http.Request) { + if userId := r.Header.Get("Mattermost-User-Id"); userId == "" { + // Our visitor is unauthenticated. + fmt.Fprintf(w, "Hello, stranger!") + } else if user, err := p.api.GetUser(userId); err == nil { + // Greet the user by name! + fmt.Fprintf(w, "Welcome back, %v!", user.Username) + } else { + // This won't happen in normal circumstances, but let's just be safe. + w.WriteHeader(http.StatusInternalServerError) + fmt.Fprintf(w, err.Error()) + } +} + +// This example demonstrates a plugin that handles HTTP requests which respond by greeting the user +// by name. +func Example_helloUser() { + rpcplugin.Main(&HelloUserPlugin{}) +} diff --git a/plugin/example_hello_world_test.go b/plugin/example_hello_world_test.go new file mode 100644 index 000000000..5dea28823 --- /dev/null +++ b/plugin/example_hello_world_test.go @@ -0,0 +1,20 @@ +package plugin_test + +import ( + "fmt" + "net/http" + + "github.com/mattermost/mattermost-server/plugin/rpcplugin" +) + +type HelloWorldPlugin struct{} + +func (p *HelloWorldPlugin) ServeHTTP(w http.ResponseWriter, r *http.Request) { + fmt.Fprintf(w, "Hello, world!") +} + +// This example demonstrates a plugin that handles HTTP requests which respond by greeting the +// world. +func Example_helloWorld() { + rpcplugin.Main(&HelloWorldPlugin{}) +} diff --git a/plugin/example_hooks_test.go b/plugin/example_hooks_test.go deleted file mode 100644 index 7ca1cf5f0..000000000 --- a/plugin/example_hooks_test.go +++ /dev/null @@ -1,38 +0,0 @@ -package plugin_test - -import ( - "fmt" - "net/http" - - "github.com/mattermost/mattermost-server/plugin" - "github.com/mattermost/mattermost-server/plugin/rpcplugin" -) - -type MyPlugin struct { - api plugin.API -} - -func (p *MyPlugin) OnActivate(api plugin.API) { - // Just save api for later when we need to look up users. - p.api = api -} - -func (p *MyPlugin) ServeHTTP(w http.ResponseWriter, r *http.Request) { - if userId := r.Header.Get("Mattermost-User-Id"); userId == "" { - // Our visitor is unauthenticated. - fmt.Fprintf(w, "Hello, stranger!") - } else if user, err := p.api.GetUser(userId); err == nil { - // Greet the user by name! - fmt.Fprintf(w, "Welcome back, %v!", user.Username) - } else { - // This won't happen in normal circumstances, but let's just be safe. - w.WriteHeader(http.StatusInternalServerError) - fmt.Fprintf(w, err.Error()) - } -} - -// This example demonstrates a plugin that handles HTTP requests which respond by greeting the user -// by name. -func Example_plugin() { - rpcplugin.Main(&MyPlugin{}) -} diff --git a/plugin/hooks.go b/plugin/hooks.go index a40ac0e5c..04d5c7c14 100644 --- a/plugin/hooks.go +++ b/plugin/hooks.go @@ -7,10 +7,10 @@ import ( "net/http" ) -// Hooks represents an object that handles events for a plugin. Methods are likely to be added over -// time, and plugins are not expected to implement all of them. Instead, plugins are expected to -// implement a subset of them and pass an instance to plugin/rpcplugin.Main, which will take over -// execution of the process and add default behaviors for missing hooks. +// Methods from the Hooks interface can be used by a plugin to respond to events. Methods are likely +// to be added over time, and plugins are not expected to implement all of them. Instead, plugins +// are expected to implement a subset of them and pass an instance to plugin/rpcplugin.Main, which +// will take over execution of the process and add default behaviors for missing hooks. type Hooks interface { // OnActivate is invoked when the plugin is activated. Implementations will usually want to save // the api argument for later use. Loading configuration for the first time is also a commonly diff --git a/plugin/plugin.go b/plugin/plugin.go new file mode 100644 index 000000000..b14ab7ced --- /dev/null +++ b/plugin/plugin.go @@ -0,0 +1,12 @@ +// Copyright (c) 2017-present Mattermost, Inc. All Rights Reserved. +// See License.txt for license information. + +// The plugin package defines the primary interfaces for interacting with a Mattermost server: the +// API and the hook interfaces. +// +// The API interface is used to perform actions. The Hook interface is used to respond to actions. +// +// Plugins should define a type that implements some of the methods from the Hook interface, then +// pass an instance of that object into the rpcplugin package's Main function (See the HelloWorld +// example.). +package plugin diff --git a/plugin/supervisor.go b/plugin/supervisor.go index f3e576e99..76f20eaee 100644 --- a/plugin/supervisor.go +++ b/plugin/supervisor.go @@ -3,7 +3,8 @@ package plugin -// Supervisor provides the interface for an object that controls the execution of a plugin. +// Supervisor provides the interface for an object that controls the execution of a plugin. This +// type is only relevant to the server, and isn't used by the plugins themselves. type Supervisor interface { Start() error Stop() error -- cgit v1.2.3-1-g7c22