Plugins

#TODO - what to add here

What's a plugin? Any component on the page that owns its own data in the DB and therefore needs to have its own model.

Each plugin should have a sub section that links to the relevant external repository. The external repositories should have their own documentation covering setup and running, tests and deployment.

Plugin refs

If you take look at the methods and service classes that tie together LiquidLayouts, LiquidPartials, and Plugins, you'll notice a lot of references to an entity called a 'ref'. It's a pretty straightforward scheme with one objective - allow a Page to have more than one instance of a plugin.

Though it's not immediately obvious why that's an important objective, there are a couple of use cases when that functionality is important. The first is if we want to put a modal or interstitial over the page with an action form, but still have a regular petition with a different form underneath. Another use case is if we want to have a layout with a scrollable sort of post-action with a second action form.

Though these use cases are not pressing, during the Widget Wars it felt important to engineer something that would be flexible enough to be a convincing replacement for everything widgets did. Therefore, this whole ref business has already been implemented.

Usage

When writing a layout, by default you don't need to worry about refs and can just include partials like this:

{% include 'action' %}

If you include the action partial twice on the layout, you can also just do it twice like above. If you do, any page using that layout will get one action plugin, and will display that action in both places the partial is referenced. But what if you want different action forms?

{% include 'action', ref: 'modal' }

If you add ref: 'modal' to one of the partial includes, then the two partials will now cause the page to instantiate different plugins - one with the default ref, and one with the 'modal' ref.

Whenever you want to reference a plugin in a liquid partial, you need to reference it with the local ref.

{{ plugin.action[ref].title }}

That says "look up all the 'action' plugins and find the one matching the current ref and display its title property". That way, when someone includes this partial, with or without a ref specified, it will know which version to display here.

The relationship between layouts, partials, and plugins

Each page has a layout. The layout includes many partials. Each partial can include other partials. Each partial can also reference a plugin. Plenty of partials, like a footer, don't need anything to do with plugins. Each plugin should have a partial that expresses it, and could have several alternatives. For example, the action plugin could have the 'action-sidebar' partial as well as the 'action-overlay' partial that each display the action plugin in different markup with different css classes.

A partial can only have one plugin, because a partial only has one ref value. However, a partial expressing one plugin can simply include another partial that expresses a different plugin, such as an action sidebar that includes a thermometer displaying in the middle.