Submitting User Interface Pull Requests for concrete5 Version 9

Mar 26, 2020

concrete5 version 9 features a number of interface improvements geared toward lightening the UI, making things more accessible, increasing contrast and feedback performance. The dashboard is getting a refined UI as well. All of these updates are based on the new concrete5 Bedrock Asset System, a system for managing core UI dependencies, third party theme asset dependencies, assets for core features and much more.

The concrete5 asset bedrock is a superset of Bootstrap 4; as of this writing concrete5 version 9 in the release/9.0.0 branch is based off of Bootstrap 4.4. This means that a lot has to happen in the core to make things look nice: everything in the Dashboard is built for Bootstrap 3. While most everything still functions, a lot of small UI improvements need to happen, since Bootstrap 4 has changed the name of some of its core alignment and button classes. That means we need help cleaning things up!

Dashboard Pull Requests

See a broken button in the release/9.0.0 branch? Something that uses the old btn-default class instead of the new btn-secondary, or something that handles float with pull-right instead of the new float-right? Send us a pull request? You may just have to update the view layer in the Dashboard. We'll happily accept it.

Core JS or CSS Requests

See something that isn't working in the core, but that can only be fixed by modifying a CSS or JS file? That's gonna be more difficult. We definitely want help fixing these issues, but you'll need to understand how Bedrock works in order to help fix them.

The Old Days

In every version of concrete5 up til version 9, the JS and CSS files that you'd need to change to affect the core ship with the core itself. For many years you could edit the JS and CSS files found in concrete/css and concrete/js directly. Awhile ago, however, we switched to a build process that took source JavaScript and (LESS)[] files and compiled them into minified JS and CSS files. That means editing the files within concrete/css and concrete/js wasn't really possible anymore; instead you'd edit files within concrete/css/build and concrete/js/build and run grunt in your local environment in order to see the changes.

While this process was more complex than in the old days, it let us write JS and CSS in more modular ways; and the code still shipped with concrete5, so it was easy for anyone to edit and submit pull requests for.

The New School

In version 9, we're providing not just core assets for things like the toolbar or the dashboard, but we're actually providing a framework for creating a concrete5 theme will full support for concrete5's many features. In the past, we'd just have developers include bootstrap in their theme, and go on with their day. But if you read the Bedrock document, you'll see that Bedrock is designed to power the assets within the core, along with third party themes. That was always the goal.

What that means, then, is that Bedrock itself can't be included with the core. Third party themes shouldn't have to download a full copy of the core in order to get access to its UI assets. Instead, Bedrock is a separate npm package. The core includes it, and third party themes can include it. The core still includes all the outer SCSS and JS files (oh, yeah, in version 9 – we're switching to SASS), but the assets that those files include are downloaded by Bedrock. Bedrock also takes care of downloading all the third party assets that we require, like jQuery, jQuery UI, etc...

Practical Example: Add Container Panel

Let's take a practical example of how the process of update the "Add Container" panel might work in this new system. Containers are a new feature of version 9, and as such they don't have much of a nice style.

Currently, in the release/9.0.0 branch the containers panel looks like this:

while our new design requires that they look like this:

(See - much nicer.).

What will the process of fixing this be like?

  1. Clone the Bedrock repository to your local machine from
  2. Within the bedrock repository, create a new git branch with git checkout -b feature/container-panel-ui-updates.
  3. Within your local concrete5 version, check out the release/9.0.0 branch with git checkout release/9.0.0.
  4. Link the two repositories together for local development using npm link: from within the concrete5 build/ directory, run npm link ../../path/to/local/bedrock. (Interested in more information on npm link? Click here).
  5. Now that you're on the release/9.0.0 branch, create a new git branch with git checkout -b feature/container-panel-ui-updates.

See what's going on here? We now have two feature branches - one for the concrete5 core and one for the bedrock.

Now, let's make UI changes that we need to make.

  1. Within the bedrock repo, find the panels SCSS assets. The panels are all within the cms domain, so look within assets/cms/scss. You'll see that _panels.scss exists, and it's including _panels/_shared.scss. Add a new file _add_container.scss within panels/, and update the _panels.scss file to include it.
  2. Make container specific SCSS updates within this _add_container.scss file.
  3. Since you've run npm link, your changes will be symlinked into the concrete5/ repo even though you're changing them within the bedrock repo.
  4. To test your updates, run npm run prod or npm run dev from within your concrete5 build/ directory.
  5. Clear your browser cache and test your updates. You should start seeing changes.
  6. You will very likely also need to make changes to the panel PHP/JS code itself, which you'll do by finding it within the concrete5 repository (for the add container panel, its view is found at concrete/views/panels/add.php.

When you're done, now it's time to submit the pull request. Pay attention to this part too so you don't accidentally undo all your hard work.

  1. Commit changes in the bedrock repo, and then run git push origin feature/container-panel-ui-updates.
  2. Now, submit a pull request against the bedrock repo updates, and make a note that this requires a companion pull request in the core.
  3. From within your concrete5 core repo, do the same thing: commit your change and push to feature/container-panel-ui-updates.
  4. Create the pull request.

At this point you should have two pull requests. One contains the changes within the bedrock code, and one contains the changes within the core code that use those CSS changes.

Aside: Where should I make my changes?

SCSS and Bootstrap 4 give you a lot of options when it comes to ensuring that components are styled properly? Want to style something to match our new version 9 designs, but you're not sure how that style should make its way into the core? Try to follow these guidelines?

  1. Is this directly controlled by a variable defined in bootstrap's _variables.scss? Then you should make it from within assets/cms/scss/_bootstrap-overrides.scss. This file is specifically designed to contain overridden BS4 variables. If something is defined here, it will directly affect the Bootstrap 4 components that concrete5 uses. By defining
  2. Is this something that's shared between the Dashboard and the front-end CMS layer? Examples of this include form elements, base components like buttons, panels, and more. If this is true, then make sure you include it in a file that's included within assets/cms/scss/_base.scss. This file is included by the cms.scss endpoint that's used on the frontend of the site when showing the editing interface, but it's also included within the Dashboard. If this is something that's only shown in the Dashboard, you can include it within the SCSS files included by the Dashboard theme in the concrete5 repository.

Happy Hunting!

Is this process more complicated? Yes. We really don't want to deter core development, but in this case the benefits of bedrock – much easier ability to keep third party assets up to date, a solid foundation for themes and addons, a faster and more flexible way to ensure that themes include only the files they need – outweigh the increased learning curve.

We're actively in GitHub getting concrete5 version 9 ready for you; we hope you'll come join us.

Recent Tutorials
Add-On Developers: Get Your Add-Ons Ready for Concrete CMS 9.0
Aug 6, 2021
By andrew.

Concrete CMS 9.0 is coming! But there are some changes in version 9 that might affected your add-ons and themes. This document aims to answer questions about the most common ways that your add-ons might need to be changed, and common problems you'll run into.

Permissions for editors in a multilingual site
Jun 2, 2021
By myq_1.

How to set up a multilingual Concrete CMS site for groups of language-specific editors

Getting Started with Doctrine in Concrete CMS
Jan 20, 2021
By linuxoid.

Doctrine is a very flexible, simple (once you get to know it better) and powerful PHP library for database interactions primarily focused on the ORM = Object Relational Mapping and DBAL = DataBase Abstraction Layer.

How To Upgrade PHP Using the MultiPHP Manager In cPanel
Nov 23, 2020

This article will explain how to upgrade your PHP version using cPanel.

How To Add Google Analytics To Your Website - The easy way
Oct 9, 2020

Adding analytics to your website is an important part of running your website. There’s no need to edit your theme or install a plugin to add a tracking code to Concrete CMS you can do it right from the CMS.

How to Generate Sitemap xml File
Oct 9, 2020

Learn how to create a sitemap.xml in a couple clicks

Was this information useful?
Thank you for your feedback.