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

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 in the 9.0.0 release candidate threads and I'll do my best to answer them as quickly as possible!

Recent Tutorials
Updating Concrete Themes from Version 8 to Version 9
Nov 24, 2022

This tutorial covers commonly encountered issues when upgrading a Concrete CMS theme from version 8 to version 9

Transferring ownership of an add-on and a theme
Nov 15, 2022
By katzueno.

If you encounter a Concrete CMS add-on or theme that you love but not being maintained, you may want to ask the author to help or take over the add-on or theme. Here is the quick step-by-step guide of how to transfer the ownership.

How to update Add-Ons if not on the Update Add-Ons Menu item
Jul 4, 2022

How to manually download an add-on and update it when your site's core versions isn't considered compatible with the add-on version.

Generate a report with author information and form summaries in Concrete CMS.
May 9, 2022

In Concrete CMS, you can use a form to initiate contact between logged-in users and then create helpful reports. After form submissions are collected, they can be searched, sorted, and exported as a spreadsheet. This tutorial will detail how to add author information to a report using the advanced search.

How to clone and customize Atomik theme
Feb 14, 2022
By linuxoid.

How to clone and customize Atomik theme

Update jQuery to 3.5 on Concrete CMS version 8.5.x
Dec 1, 2021
By hissy.

If you have to take some time to fix your site to work with version 9 and want to update jQuery immediately, you can override it.

Was this information useful?
Thank you for your feedback.