builder-plugin

Builder is a visual development tool. It shortens plugin development time by automating common development tasks and makes programming fun again. With Builder you can create a fully functional plugin scaffold in a matter of minutes.
Builder makes the learning curve less steep by providing a visual interface that naturally incorporates October’s design patterns and documentation. Here’s an example, instead of looking into the documentation for a list of supported form controls and their features, you can just open the Form Builder, find a suitable control in the Control Palette, add the control to the form and explore its properties with the visual inspector.
Builder implements a Rapid Application Development process that automates the boring activities without sacrificing complete control. With this tool you can spend more time implementing the plugin’s business logic in your favorite code editor rather than dealing with the more mundane tasks, like building forms or managing plugin versions.
Plugins created with the help of Builder are no different to plugins that you would usually create by hand. That means that you can continue to use your usual “hands on” workflow for updating your servers, managing the code versions and sharing work with your teammates.

Video tutorial

We also recorded a video tutorial showing how to use the plugin to build a simple library plugin: watch the video.

What you can do with Builder

This tool includes multiple features that cover almost all aspects of creating a plugin.

• Initializing a new plugin – this creates the plugin directory along with any necessary files.
• Creating and editing plugin database tables. All schema changes are saved as regular migration files, so you can easily update the plugin on other servers using your regular workflow.
• Creating model classes.
• Creating back-end forms with the visual Form Builder.
• Creating back-end lists.
• Managing a list of user permissions provided by the plugin.
• Creating plugin back-end navigation – in the form of main menu items and sidebar items.
• Creating back-end controllers and configuring their behaviors with a visual tool.
• Managing plugin versions and updates.
• Managing plugin localization files.
• A set of universal components – used for displaying data from the plugin on the front-end in form of lists and single record details.

Put simply, you can create a multilingual plugin, that installs database tables, has back-end lists and forms protected with user permissions, and adds CMS pages for displaying data managed with the plugin. After learning how Builder works, this process takes just a few minutes.
Builder is a productivity tool, it doesn’t completely replace coding by hand and doesn’t include a code editor for editing PHP files (the only exception is the version management interface). Builder never overwrites or deletes plugin PHP files, so you can rest assured knowing that the code you write never gets touched by Builder. However, Builder can create new PHP files, like models and controllers.
Most of the visual editors in Builder work with YAML configuration files, which are a native concept in OctoberCMS. For example, after creating a model class in Builder, you can choose to add a form to the model. This operation creates a YAML file in the model’s directory.
There are currently some limitations when using Builder. Some of them are missing features which will be added later. Others are ideas intentionally omitted to keep the things simple. As mentioned above, Builder doesn’t want to replace coding, while at the same time, it doesn’t go too far with visual programming either. The limitations are explained and described in the corresponding sections of the plugin documentation. Those limitations don’t mean you can’t create any plugin you want – the good old approach to writing the code manually is always applicable for plugins developed with Builder. Builder’s aim is to be a modest, yet powerful tool that is used to accelerate your development cycle.

Getting started

Before you create your first plugin with Builder you should configure it. Open the Settings page in OctoberCMS back-end and find Builder in the side menu. Enter your author name and namespace. The author name and namespace are required fields and should not change if you wish to publish your plugins on OctoberCMS Marketplace.
If you already have a Marketplace account, use your existing author name and namespace.

Initializing a new plugin

On the Builder page in OctoberCMS back-end click the small arrow icon in the sidebar to expose the plugin list. After clicking the “Create plugin” button, enter the plugin name and namespace. The default author name and namespace can be pre-filled from the plugin settings. Select the plugin icon, enter the description text and plugin homepage URL (optional).
Please note that you cannot change the namespaces after you create the plugin.
When Builder initializes a plugin, it creates the following files and directories in October’s plugins directory:

authornamespace
    pluginnamespace
       classes
       lang
           en
               lang.php
       updates
           version.yaml
       Plugin.php
       plugin.yaml

The file plugin.yaml contains the basic plugin information – name, description, permissions and back-end navigation. This file is managed by the Builder user interface.
The initial contents of the lang.php localization file is the plugin name and description. The localization file is created in the default locale of your October installation.
When a new plugin is created, it’s automatically selected as the current plugin that Builder works with. You can select another plugin in the plugin list if you need.

Managing plugin database tables

Tables are managed on the Database tab of Builder. You can create tables, update their structure and delete tables with the visual interface.
Click Add button to open the Create Table tab. Builder automatically generates prefixes for plugin tables. The prefixes are compliant with the Developer Guidelines for the Marketplace plugins.
Every time when you save changes in a table, Builder shows a popup window with the automatically generated migration PHP code. You can’t edit the code in the popup, but you can inspect it or copy to the clipboard. After reviewing the migration, click Save & Apply button. Builder executes the migration immediately and saves the migration file to the plugin’s updates directory. Afterwards you can find all plugin migrations on the Versions tab of Builder.

Note: Although Builder generates migration files automatically, it can’t prevent the data loss in some cases when you significantly change the table structure. In some cases it’s possible – for example, when you alter length of a string column. Always check the migration PHP code generated by Builder before applying the migration and consider possible consequences of running the migration in a production database.

Currently Builder doesn’t allow to manage table indexes with the visual user interface. Unique column management is not supported yet as well. Please use the Version Management feature to manually create migration files.
Please note that the enum data type is not currently supported by the Builder due to limitations in the underlying Doctrine classes.

Managing models

You can edit models on the Models tab of Builder. Click the Add button, enter the model class name and select a database table from the drop-down list.
The model class name should not contain the namespace. Some examples: Post, Product, Category.
Please note that you cannot delete model files with builder because it would contradict the idea of not deleting or overwriting PHP files with the visual tool. If you need to delete a model, remove its files manually.

Managing back-end forms

In OctoberCMS forms belong to models. For every model you can create as many back-end forms as you need, but in most cases there is a single form per model.

Note:…