Add-On Developers: Get Your Add-Ons Ready for Concrete CMS 9.0

This tutorial is over a year old and may not apply to your version of Concrete CMS.
Aug 6, 2021
Note: this tutorial is a work in progress as new 9.0 issues are reported.

Debug your jQuery

Are you getting strange new JavaScript errors when working with your theme, block or single page? jQuery might be the culprit. Our jQUery in 8.5.5 was very out of date. Version 9 upgrades jQuery to the latest stable (at the time of this document it was 3.6.0.) If you're getting unexplained JavaScript errors, jQuery is the place to start.

$app->make() and Core::make are different now

This one is coming up a lot: if you use Core::make() or $app->make() or $this->app->make() to build a class and pass arguments to that class, you might need to modify this code.

Making a Class with No Arguments Passed at Runtime? No Modifications Needed

Are you building a simple class that might have constructor arguments, but you're not passing custom arguments to it? Something like this?

$object = $this->app->make(MyClass::class);

You don't need to change a thing.

Making a Class with Arguments Passed at Runtime? Check Your Code

If your class constructor takes parameters that you pass at runtime, you might need to modify your code. Consider this class.

<?php

class MyClass
{

    public function __construct($someVariable, $someOtherVariable)
    {
        // ... your code here.
    }

}

If you want to use $app->make() to build this class, while passing in $someVariable, you might have used custom code like this before.

$var1 = 'foo';
$var2 = 'bar';
$object = $this->app->make(MyClass::class, [$var1, $var2]);

This does not work in version 9. The underlying Laravel Container library that powers the Application object no longer works this way. Instead, you have to be explicit about what argument you are setting to what value:

$var1 = 'foo';
$var2 = 'bar';
$object = $this->app->make(MyClass::class, ['someVariable' => $var1, 'someOtherVariable' => $var2]);

In other words, you have to:

  1. check the __constructor method of the class you want to create
  2. take a note of the parameter names
  3. when calling make, use those parameter names (without the leading $) for the kays of the array you use as the second argument

Good news: these modifications are backward compatible with 8.5.5 and earlier.

Theme-level Element Path Changes

Beginning in version 8, we added the ability to override core elements from within your themes. For example, if the core requires an element via View::element(‘conversations/add_post’; the core looks for this add-on in concrete/elements/conversations/add_post.php. However, if the currently active theme provides this element in themes/my_theme/elements/concrete/conversations/add_post.php, it will be used instead. We are changing this to remove the concrete/ directory from the elements directory within your theme. That means in order to override any core element from within your theme, you only need to make it available at the same path within the elements/ directory of your theme.

Registering and Loading CSS and JavaScript Assets

Concrete CMS asset system lets you register and load your own CSS and JavaScript assets. Typically you'd do something like:

$al = AssetList::getInstance();
$al->register(
    'javascript',
    'SomeHandle',
    'js/some-js-file.js',
    [
        'version' => 1.0.0,
        'position' => Asset::ASSET_POSITION_FOOTER,
        'minify' => true,
        'combine' => true,
    ],
    $pkg
);

In v9 the 'minify' and the 'combine' options were removed.

Keeping them in your code won't hurt anything but it will also not do anything. You then have 4 things to keep in mind:

  • If your code should be backward compatible leave these options in place
  • If your code is for v9 only just remove these options
  • If it's important for your project, start providing already minified and possibly combined assets yourself
  • If your code makes independent use of the minifier class that was included in the core, find an alternative as it was also removed

Queuing

As the Job system was completely overhauled in v9, several classes included in the core were removed as not needed anymore. That included Queuing classes.

These classes could be (and were) used to process long-running tasks without building a job for it.

If your code made use of these classes, you have to find an alternative.

More Coming Soon

I'll add more to this document as more questions come in through the forums. Please ask questions in the forums and I'll do my best to answer them as quickly as possible!

Recent Tutorials
Redirect all requests to HTTPS
Oct 9, 2024
By myq.

How to follow best practices for a secure web

Upgrade Concrete versions 9.3.1 and 9.3.2
Sep 10, 2024
By myq.

How to get past a bug in versions 9.3.1 and 9.3.2 that prevents upgrading the Concrete core through the Dashboard

How to use Composer with Marketplace extensions
Aug 22, 2024

Composer can be used to manage third-party extensions from the marketplace

Controlling Google Tag Manager Tags Based on Concrete CMS Edit Toolbar Visibility
Aug 13, 2024

This document provides a step-by-step guide on how to control the firing of Google Tag Manager (GTM) tags based on the visibility of the Concrete CMS edit toolbar. It explains how to create a custom JavaScript variable in GTM to detect whether the edit toolbar is present on a page and how to set up a trigger that ensures GTM tags only fire when the toolbar is not visible. This setup is particularly useful for developers and marketers who want to ensure that tracking and analytics tags are not activated during content editing sessions, thereby preserving the accuracy of data collected.

Upgrading Concrete from 8.5 to 9.x
Jun 21, 2024
By myq.

How to avoid problems upgrading from 8.5 to 9.x

How to change the default date format
May 30, 2024
By myq.

Change the format of the default date

Improvements?

Let us know by posting here.