Plugins and Frameworks

V4 plugins are structured the same as v3, with read(), write(), and ioctl() methods.

The same ioctl commands are recognized, and you can follow the same general methodology as in v3. One new ioctl command is recognized: PublishRule. It should return a publish rule (eg. static, dynamic, daily, weekly, etc.) to help the CMS decide when its content needs to be published.

If your plugin is built on the v4 CMS framework (eg. it manages a new content type), then it can inherit from Modules::Content to get a full suite of CMS admin functions, including:

• pathbar() to display your current position in the site
• configure() to set the content record fields and specific metadata attributes
• update() to add a new revision, and rollback() to discard the latest revision
• delete() to remove the content and its descendants
• copy() to make a copy of the content
• search() to find content within an object (eg. find an event in a calendar)
• pricing() to manage the prices of an item
• order() to change the sorting of the items under the content
• todo() to add a to-do item on this content
• translations() to manage the translations of this content
• images() to manage the images under this content
• contacts() to manage the contact records for this content
• about() to display all of the relevant information about this content
• tags() to manage all of the keyword tags on the content
• metadata() to manage the specific and generic metadata for the content
• schedule() to manage the scheduled tasks for the content
• wf_tools() to display appropriate workflow actions in a toolbar or menu, and schedule_tool() to include a schedule button
• publish(), unpublish(), archive(), approve(), submit(), queue(), unqueue(), draft(), expire(), cancel(), and reject() methods to perform those workflow operations

You simply need to decide which ones to expose to the admin in your toolbar menu, and your command switch statement. These methods all accept a content object as a parameter, so they can be used to manage any content object, including ones from other content classes that are not explicitly handled by your plugin.

In cases where your content makes use of other content objects (like images, email templates, or forms), those secondary content objects should simply be embedded under their parent objects, and managed using the same tools as above. Do not place them in libraries unless it is your intent to share them between multiple content objects.

Plugin Best Practices

• inherit from the Modules::Content class to get standardized UI and methods for managing content objects
• use the global ML object to keep heading and other context

$ml = &get_obj("ML");

• do not duplicate underlying CMS features if possible
• use static or interval publishing, where possible
• use wf_tools() to suggest reasonable workflow operations
• avoid using a section selector if the next step just makes you select from a small number of content objects; select those objects on the first screen, and show all sections at once
• use $ui->OverlayFrame() when cross-linking to other plugins, live website views, or other operations that would normally use a popup to avoid losing your control panel
• control panels should display, in order, and where appropriate: pathbar, toolbar, status messages, work area/preview
• when linking to another plugin or inclined to use a popup, try an OverlayFrame
• use the bad tone for destructive actions, such as delete buttons.
• if your toolbars are too busy, group and hide the less-used functions in drop-down menus.
• wrap previews in a BasicBox or something similar

Should you rebuild your plug-in using the V4 CMS framework?

Your plug-in can probably be converted to v4 with some simple changes:

• if you are calling into any CMS objects (like Section, Page), those calls may need to be updated
• direct references to a section_id in the data may need to be replaced with content_id
• update the control panel UI calls

Otherwise, it should just work. But you should consider a rewrite using the V4 CMS framework if your module has any of the following features:

• hierarchical data structures
• translations
• HTML editing (TinyMCE)
• workflow, moderation, approvals
• uploaded images or files
• scheduled tasks
• search
• prices, e-commerce
• access controls
• metadata or other settings
• forms
• templates
• contact records

Sharing those common frameworks means less coding, less debugging, more UI consistency, and it's easier to extend your tools to include additional features on this list.

Frameworks

Several important plug-in frameworks have received major overhauls in v4, including:

• E-commerce
• Forms
• Memberships
• Contacts

These are detailed in separate documents, at those links.