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, and, as of OctoberCMS v2, adding a git tag!

After editing the plugin, you will need to run php artisan october:migrate (as of OctoberCMS v2; run php artisan october:up in previous versions).

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)

And how to roll back to a previous version (for example, to fix and re-test a buggy migration script)? Frollow "Meysam"'s answer on this StackOverflow question:

One way of rolling back migrations is via the builder plugin in admin control panel (make sure to install this plugin first if you have not already).
1. Select the builder plugin menu (from top of the page)
2. Select your plugin (by clicking on the arrow '>' button)
3. From left side menu, select Versions
4. Select the version you want to rollback
5. Click on the Rollback version button

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) }}

*update December 2020: the debugbar plugin seems to be unmaintained and it is no longer available for the latest build of October. However, we have some new plugins offering similar functionality:

1. Twig Dump + with Laravel 6 support

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