October CMS 2.1 - Stable Release

Release Note 27

Version 2.1 of October CMS hallmarks the stable version of this major release. It can be safely used in production environments.

Table of Contents

New october/all Package

October CMS will continue to increase its modularity by introducing additional modules. Currently, there are five modules that can be included within your project.

  • october/system
  • october/backend
  • october/cms
  • october/media
  • october/editor

For example, if you want to use the backend only, there is no need to include the october/cms module. The modules are detected automatically, so you can simply not include it as part of your composer file. Alternatively, you can explicitly disable modules using the system.load_modules configuration.

Conversely, we have introduced a new package called october/all that will include all the supported modules for the selected version. This will be used for all new installations and will ensure that your October CMS installation has all the available features.

"require": {
    "php": ">=7.2.9",
    "october/all": "^2.0",
    "october/rain": "^2.0",
    "laravel/framework": "^6.0"
},

New CMS Editor Extensibility API

A new API has been created for customizing the Editor toolbar for CMS items. More information can be found by reading the announcement blog post for this feature.

Backend Redesign

The October CMS backend user interface was designed more than 6 years ago. It has become dated and we received multiple requests for UI improvements. As a result, the backend user interface has been redesigned to appear more modern.

We have updated many elements of the backend user interface to meet the requests and requirements for a modern web application. This includes:

  • Navigation
  • Forms
  • Form widgets
  • Alerts and popups
  • Login page

Included is the ability to apply default customization settings to your October CMS applications by modifying the config/backend.php file. These branding values are all optional.

'brand' => [
    'enabled' => false,
    'app_name' => 'October CMS',
    'tagline' => 'Getting Back to Basics',
    'menu_mode' => 'icons',
    'favicon_path' => '~/app/assets/images/logo.png',
    'logo_path' => '~/app/assets/images/logo.png',
    'stylesheet_path' => '~/app/assets/less/styles.less',
    'login_background_type' => 'color',
    'login_background_color' => '#fef6eb',
    'login_background_wallpaper_size' => 'auto',
    'login_image_type' => 'autumn_images',
    'login_custom_image' => '~/app/assets/images/loginimage.png',
],

New Plugin and Theme Integrity Checks

Some new commands have been added specifically for validating the integrity of an installed system. The plugin:check command will check to make sure that all required plugins are currently installed. The theme:check command will make sure that all themes installed with composer are locked from edits. This ensures that composer will not overwrite your theme changes.

# Check that required plugins are installed
php artisan plugin:check

# Check that themes are protected from composer
php artisan theme:check

Improved CMS Partials

CMS Partials have been improved to support passing HTML markup to the partial in addition to placeholder support. The following partial defines two HTML areas where content can be added. This lets you build composable partials, the following card partial is composed of two content areas.

<div class="header">
    {% placeholder header %}
</div>
<div class="body">
    {{ body|raw }}
</div>

When including the partial, you can now specify the body attribute to enable the passing of HTML contents, which includes the ability to define placeholders.

{% partial "card" body %}
    {% put header %}
        <h2>This is the card header</h2>
    {% endput %}
    <p>This is the card contents</p>
{% endpartial %}

Themes Require an Author Code

When publishing themes to the marketplace, a new authorCode property is required in the theme.yaml file. Similar to a PHP namespace, this is used to verify the package naming convention.

# Acme.Demo (acme/demo-theme)
code: Demo
authorCode: Acme

This change is only required for themes that are published to the marketplace.

Overriding Messages in Form and Relation Controllers

The RelationController and FormController behaviors now support a customMessages property for overriding messages used by these behaviors. This feature has been added to the relevant documentation area.

customMessages:
    buttonCreate: Make Thing
    buttonDelete: Destroy Thing

In addition to this, the RelationController will now display a flash message whenever an action is performed. This functionality can be disabled with the showFlash option.

showFlash: false

No Longer Need to Elevate Plugins

In previous versions of October CMS, it was necessary to "elevate" a plugin to allow it to register within certain protected areas, such as backend login and system update screens. This was a common source of confusion for developers who didn't realise that they need to define the elevated property.

/**
 * @var boolean Determine if this plugin should have elevated privileges.
 * @obsolete This property is no longer used.
 */
public $elevated = false;

This property is no longer required since the system uses Composer as an external provider to perform updates and install plugins.

New Method For Counting Relations

Before Laravel introduced the feature, October CMS needed a way to count relations. The solution was to define the related record twice: Once for the relationship itself (roles) and another for counting that same relationship (roles_count), which would also specify the count option.

public $belongsToMany = [
    // The roles relationship
    'roles' => [
        Role::class,
        'table' => 'october_test_users_roles',
        'timestamps' => true,
        'order' => 'name'
    ],
    // Defining roles_count is deprecated
    'roles_count' => [
        Role::class,
        'table' => 'october_test_users_roles',
        'count' => true
    ],
];

Since Laravel introduced the withCount query method, using the roles_count definition above has been deprecated and removed from the documentation. The new approach below is used to request a count column using the query instead.

// Count the relationship using withCount
$user = User::withCount('roles')->first();

// Custom attribute with the number of roles
echo $user->roles_count;

The Property ignoreTimezone is Deprecated

The ignoreTimezone feature is a community contribution that has undergone a review internally and it was determined that the name did not provide an accurate API representation.

# Deprecated
ignoreTimezone: true

It has since been replaced with useTimezone that can be disabled with the equivalent setting.

# Replace with
useTimezone: false

In addition to this, form fields and list columns that do not contain a date and a time together will no longer use timezone conversions by default. To restore this functionality, the same setting is used.

useTimezone: true

To summarize, the default settings for these types are as follows.

  • date typed fields will useTimezone: false by default
  • time typed fields will useTimezone: false by default
  • datetime typed fields will useTimezone: true by default

Note: Deprecated means the ignoreTimezone option will still continue to work for this major version. You do not need to update your code, however, doing so will keep your project aligned with the documentation.

ReorderController is Deprecated

In previous versions of October CMS the ReorderController was needed to sort and reorder records. This functionality has now been combined with the ListController behavior. As a result, ReorderController is no longer needed but will continue to work for some time. We recommend switching to the new structure mode.

structure:
    showTree: true
    showReorder: true
    maxDepth: 2

In addition to this, the showTree option in the ListController has been moved to live under the new structured options.

# Deprecated
showTree: true

Both will also continue to work and we recommend switching to the new structure option.

# Replace with
structure:
    showTree: true
    showReorder: false

Learn more about this feature by reading the Sorting Records documentation.

The Plugin Rollback Command Has Moved

The previous console command plugin:rollback has been combined with the plugin:refresh command due to their similiar functions.

# Deprecated
php artisan plugin:rollback RainLab.User 1.0.1

# Replace with
php artisan plugin:refresh RainLab.User --rollback=1.0.1

The command will also prompt the user to confirm the changes since they are destructive in nature. You can override this prompt with the standard --force flag.

php artisan plugin:refresh RainLab.User --rollback=1.0.1 --force

Internal PHP Memory Caching Has Been Removed

In previous versions of October CMS, model objects would attempt to prevent duplicate queries from requesting source data twice in the same execution cycle.

// First time asks the database
User::find(1);

// Second time comes from a stored PHP variable
User::find(1);

This feature has since been removed because the benefits no longer justify the cost, especially instances where memory usage must be kept low. The responsibility for caching data or performance should not be done in the underlying Model class.

Version File Schema Changes

Regarding plugin and theme update files, the following is advanced notice of an upcoming upgrade to the YAML parser library. An update to the version schema is used by October CMS is required for all themes and plugins.

Version Numbers Should Be Prefixed With "v"

It has been observed that integer based keys will no longer be supported by the latest Symfony YAML parser and treated as invalid without being wrapped in quotation marks. The following will soon no longer be considered valid and will throw an error in the next major release.

# YAML will throw an error in October 3.0
1.0.0: Some update
1.2: Another update

As a result, all plugins and themes should place a v in front of the version number to represent a string. The following is valid YAML in a version.yaml file and will be compatible moving forward.

# Get prepared and update to this
v1.0.0: Some update
v1.2.0: Another update
v1.2.1: Important update

Important updates (!!!) are no longer necessary

The use of an exclamation point (!) before a message will also not be valid and cause an error.

# YAML will throw an error in October 3.0
1.2.1: !!! Important update

Since October CMS now uses Composer as its package manager, plugins should adhere to the semantic versioning schema of major.minor.patch where a major version is considered important and will not be delivered without manual intervention.

# Important updates increase the "major" version number
v2.0.0: Important update

To ensure compatibility with the next major version of October CMS, we recommend that authors prepare and update their products with this change.

Note: For backwards compatibility, support for "v" prefixes has been added to previous versions of October CMS from Build 472 and v1.1.5 onward.

The getThumb Method Outcome Has Changed

When calling on an attachment relationship (attachMany / attachOne) that associates to an image file, you have the ability to programatically generate thumbnails of that image using the getThumb method.

In previous versions of October CMS, when this thumb generation logic failed, it would save a broken image in place of the desired thumbnail. This was designed be a clear alert to the developer that the resizer is not functioning. However, temporary failures would prevent any possible retry attempt.

// First time, if the resize fails, a broken image is used
$file->getThumb(...);

// Second time, no resize performed, link to broken image
$file->getThumb(...);

As of October CMS 2.0, the getThumb method will now return an empty string if the resizer fails. This allows the developer to control the outcome.

// First time, if it fails, use a custom path
$file->getThumb(...) ?: 'path/to/custom/image.png';

// Second time, resizer will try again
$file->getThumb(...) ?: 'path/to/custom/image.png';

This is the end of the document, you may read the announcement blog post or visit the changelog for more information. We know you have a choice when choosing a CMS, so we thank you for using October CMS!

comments powered by Disqus