OctoberCMS Plugin Development Tips
August 18, 2019

OctoberCMS Plugin Development Tips

For now this is a collection of "tips" and reminders for myself in regards to developing OctoberCMS plugins.

Plugin Migration

Plugin migration involves editing /updates/version.yaml

See the official docs!

After editing the plugin, all you need to do is log out of the backend and log back in. Alternatively, run php artisan october:up

Caution! Running php artisan plugin:refresh will destroy all existing data and should only be run if you are manually installing a plugin (via git or filesystem)

Debugging

Debugging from a CMS Page/Partial/etc.

Add the OctoberCMS debugbar plugin and then you can do:

  1. set debug: true in app/config/app.php
  2. in twig template add dump(your_variable)
    {{ debug(helyszinRecord.toArray) }}
    {{ dump(helyszinRecord.toArray) }}
    {{ dump(this) }} 
    {{ dump(helyszinRecord.images.toArray) }}

Customization

Overriding a Plugin Template

  1. Find the relevant template (either from the filesystem, or from GitHub if it's open source, for example the Blog Posts default template is here)
  2. Create a new file under Partials, the filename should be COMPONENT_ALIAS/TEMPLATE_NAME.htm

Miscellaneous

$this->id is NOT available in ComponentBase.onRun()

Put any code that requires $this->id into onRender()

Default Settings values set in fields.yaml are initially useless

This is pretty ugly gotcha: you develop a plugin, test it over and over again, inluding by uninstalling it and reinstalling it, and everything's dandy. Until you try to use it on a virgin instance. Bam - it doesn't work. Why? Possibly because when you first install a plugin, the settings haven't been persisted to database yet - not even the default settings you set in fields.yaml. Wtf you think!?

Apparently defaults set in fields.yaml only work once the user has actually navigated to the plugin backend settings page and saved the form, because until then there isn't actually a record in system_settings for the plugin. Instead, you also have to define your setting model defaults in initSettingsData(). This seems like pretty poor design.

The ThemeData module seems to be doing some magic to get around this,  but I haven't gotten around to making any use of it yet:

https://github.com/octobercms/october/blob/master/modules/cms/models/ThemeData.php

OctoberCMS Plugin Development Tips
Share this