Finish edit from last change

Matt Holt 2019-12-10 15:00:00 -07:00
parent 54ccf2f30c
commit 889ff0317c

@ -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.