Version 3.2 of October CMS contains extra features, including tabbed repeaters and tailor permission improvements.

Table of Contents

• Paginated List Change
• New Page Finder Form Widget
• Partial Improvements
• New AJAX Partial
• Tabbed Repeaters
• New Twig Functions
• File Downloads using the AJAX Framework
• Improved Mail Template Registration
• File Model Output Returns a Response by Default
• Authentication Error Improvements
• Notable Minor Changes

List Pagination Change

When navigating using the page numbers on a list, the page number is now stored in the page URL instead of in the session. You may notice that when closing or cancelling a form, the redirection back to the list now appears on the first page, since the page number is reset.

To retain the previous behavior inside forms, you may redirect to the previous page and keep the list pages numbers using the data-browser-redirect-back attribute. Adding the attribute to any button will give the previous URL (including page numbers) redirection priority over any standard redirect.

For example, the Save and Close (Save and Back) button.

<button
    type="button"
    data-request="onSave"
    data-request-data="close:1"

    data-browser-redirect-back

    data-hotkey="ctrl+enter, cmd+enter"
    data-load-indicator="Saving Person..."
    class="btn btn-default">
    Save and Back
</button>

The attribute also works on hyperlinks, for example, the Cancel button.

<span class="btn-text">
    or <a
        href="<?= Backend::url('october/test/people') ?>"
        data-browser-redirect-back>
        Cancel
    </a>
</span>

New Page Finder Form Widget

A new pagefinder control has been included in the CMS module that searches for page links used throughout the website. This includes linking to CMS pages and Tailor records.

featured_page:
    label: Featured Page
    type: pagefinder

Use the |link Twig filter to convert the page finder value to a URL.

{{ featured_page|link }}

The page finder is included in the markdown and rich editors so you can create more robust links within your content. The plural |content filter can process multiple links within HTML content.

{{ html_content|content }}

{{ markdown_content|md|content }}

See the Page Finder form widget documentation to learn more.

Partial Improvements

When using the {% partial %} tag, the contents now access the variables from the current context and the additional ones provided.

{% partial 'mypartial' foo='bar' %}

In the following example, the foo variable is available inside the mypartial partial template.

{% set foo = 'bar' %}
{% partial 'mypartial' %}

You can disable access to the context by appending the only keyword. In this example, only the foo variable is accessible.

{% partial 'mypartial' foo='bar' only %}

In the next example, no contextual variables will be accessible.

{% partial 'mypartial' only %}

New AJAX Partial

A new {% ajaxPartial %} Twig tag has been created to add AJAX handler support to partials and improve the overall developer experience. When using the tag:

• The partial's AJAX handlers can be called
• The partial can update itself using the _self reference
• The partial can be updated without a selector, as { partialname: true }

==
<?
function onRefresh()
{
    // This can be called when using {% ajaxPartial %}
}
?>
==
<button
    data-request="onRefresh"
    data-request-update="{ _self: true }">
    Refresh
</button>

Check out the AJAX Partial Twig Tag documentation to learn more.

Tabbed Repeaters

The repeater widget now supports tabbed content by setting the useTabs property to true.

myrepeater:
    tab: My Repeater
    type: repeater
    useTabs: true
    form:
        fields:
            primary_text:
                label: Primary Text
                tab: General

            alt_text:
                label: Alt Text
                tab: Alternative

New Twig Functions

Some new Twig functions have been added to the CMS system.

The carbon() function can be used to handle dates and times using Twig, prepared with a Carbon object and all its available functions.

Meeting starts at {{ carbon('now').format('H:i') }} in Johannesburg.

The config() and env() functions allow access to configuration values when safe mode is disabled.

{{ config('app.locale') }}

{{ env('APP_ENV', 'production') }}

The d() function acts as a shorter syntax for debugging in Twig. It will recursively dump provided variables in the same manner as the dd() PHP function.

{{ d(user) }}

The dd() function is an alternative that will dump the values and then terminate the process.

{{ dd('dump and die') }}

See the Templating documentation to learn more.

File Downloads using the AJAX Framework

The AJAX framework can now handle downloading files. Add a data-request-download attribute to enable this feature.

<button
    data-request="onDownloadDocument"
    data-request-download>
    Download Document
</a>

Now in the AJAX handler, you can return a download response to download a file. The Response facade as described in the documentation handles everything internally and accepts a local file path.

public function onDownloadDocument()
{
    return Response::download(base_path('modules/media/tests/fixtures/media/images/small.png'));
}

View the AJAX documentation to learn more about this feature.

Improved Mail Template Registration

The registration of mail templates has been consolidated to a single method. Previously it was spanned across three different methods.

public function registerMailTemplates()
{
    return [
        'templates' => [
            'october.test::mail.test-message'
        ],
        'layouts' => [
            'test' => 'october.test::mail.test-layout'
        ],
        'partials' => [
            'test' => 'october.test::mail.test-partial'
        ]
    ];
}

If you see the error View [templates] not found. it means this newer syntax is used on an old version of October CMS (backward incompatible plugin).

File Model Output Returns a Response by Default

The default parameters of the System\Models\File methods output() and outputThumb() have changed. The methods now return a response by default instead of using echo to output them.

Previously the default value for the last argument was false and now it defaults to true. If you use direct output, set the last argument to false explicitly.

// Backwards compatible
$file->output('inline', false)

$file->outputThumb($width, $height, $options = [], false)

Soon the method will only return a response, so it is best to chain with the ->send() method. The following code can be used, if you are not worried about backwards compatibility.

// Optimal update
$file->output()->send();

$file->outputThumb($width, $height)->send();

Authentication Error Improvements

The AuthException class has been improved. It is possible to override the soft error configuration using the config/system.php file:

'soft_auth_errors' => false,

It might be a good idea to use this setting programmatically, instead of globally. So you can control the desired context.

if (App::runningInFrontend()) {
    Config::set('system.soft_auth_errors', false);
}

Notable Minor Changes

Tailor Publish Permissions

The publishing permissions for Tailor have improved. If a user does not have permission to publish, then they can only create drafts from existing records.

Tailor Soft Deletion

Records in tailor are now soft deleted instead of being deleted permanently. These records can be restored by selecting the Deleted filter, opening the record and clicking Restore. There is also a Delete Forever button to delete them permanently.

The public_path() is Now Dynamic

If the /public directory exists, such as when created via php artisan october:mirror, then the public_path() function now refers to this location. Otherwise, it refers to the base path. The check App::hasPublicFolder() is used to determine the result.

The input() Helper Includes Files

There is a new files() input helper for retrieving uploaded files. The input() helper also will include files since it qualifies as user input. In summary, the global function convention is as follows:

• post() resolves $_POST variables
• get() resolves $_GET variables
• files() resolves $_FILES variables
• input() resolves $_POST + $_GET + $_FILES variables

Editor Content Types

When editing CMS content files via the Editor in the admin panel:

• if the extension ends with .htm it will show a code editor (previously rich editor)
• if it ends with .html it will show a rich editor

Sorting List Structures

List structures now support traditional sorting by clicking the column headers, this will disable the structure and enable pagination. Clicking the column a third time or resetting the list configuration will restore the structure view.

Error Flash Messages

The default timer of five (5) seconds has returned for error flash messages. Previously error messages would have no timer so the error message can be captured. This has been replaced with logic that cancels the timer if the flash message is clicked (i.e when copying the error).

This is the end of the document, you may read the announcement blog post or visit the changelog for more information.