From 889ff0317c6f5d912f427d5d84dffda702012f0a Mon Sep 17 00:00:00 2001 From: Matt Holt Date: Tue, 10 Dec 2019 15:00:00 -0700 Subject: [PATCH] Finish edit from last change --- v2:-Writing-a-Module.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/v2:-Writing-a-Module.md b/v2:-Writing-a-Module.md index 36201dc..77fe5bb 100644 --- a/v2:-Writing-a-Module.md +++ b/v2:-Writing-a-Module.md @@ -241,23 +241,22 @@ A host module will need to load and use its guest modules. Caddy provides facili First, host modules need a way to receive the guest modules' configuration. This is typically done by adding `json.RawMessage` fields to the struct, and then using the Provision method to load them into a non-JSON type. For example, if your module `Gizmo` has a `Gadget` guest module that implements a `Gadgeter` interface, you would add two fields, `GadgetRaw` and `Gadget`: ```go - GadgetRaw json.RawMessage `json:"gadget,omitempty" caddy:"namespace=foo.gizmo.gadgets inline_key=gadgeter"` +GadgetRaw json.RawMessage `json:"gadget,omitempty" caddy:"namespace=foo.gizmo.gadgets inline_key=gadgeter"` - // the decoded value of the guest module will be - // stored here, but it doesn't get used for JSON - // so make sure to either exclude it with "-" or - // unexport it - Gadget Gadgeter `json:"-"` +// the decoded value of the guest module will be +// stored here, but it doesn't get used for JSON +// so make sure to either exclude it with "-" or +// unexport it +Gadget Gadgeter `json:"-"` ``` -The configuration for `Gadget` would come in on the `GadgetRaw` field and then your `Provision()` method would be used to decode the config and load the instance of the Gadget. +The configuration for `Gadget` would come in on the `GadgetRaw` field, then your `Provision()` method would be implemented to load the instance of the Gadget from the RawMessage. -There are two functions for loading guest modules: `LoadModule()` and `LoadModuleInline()`. +You can load guest modules with the `LoadModule()` method. You pass in a struct pointer and the field name, and it loads a module from the json.RawMessage on the field by reading the caddy struct tag. -- `LoadModule()` loads a module from its json.RawMessage when you already know the module's name. This is often the case when the module name is stored outside of the module's configuration; like as a map key, where the value is the module's config. -- `LoadModuleInline()` is used when you have only a json.RawMessage and you do not know the module's name, because its name is stored _within_ the JSON. In other words, its module name is found _inline_ with its configuration. To use this function, you provide the namespace as well as the name of the property that contains the module's name in that namespace. +The struct tag must define a namespace from which to load the module, and also a way to obtain the module name. If `inline_key` is specified in the struct tag, then the module name will be found _inline_ with its configuration at that key. If `inline_key` is omitted from the struct tag, then the module name must be the key of a `caddy.ModuleMap` (or `map[string]json.RawMessage`); if the field is not this type when `inline_key` is missing, that is an error, since it does not know how to get the module name. -Here's an example of using `LoadModuleInline()` to get a Gadgeter for our Gizmo module: +Here's an example of using `LoadModule()` to get a Gadgeter for our Gizmo module: ```go // Provision sets up g and loads its gadget.