Problem Solving - Container Magic

How does Container Magic work?

The Concrete CMS core implements containers using a specialized block type. Container Magic overrides the core view.php for that block type and inserts a few of its own lines of code just before a container is rendered. The process is exactly the same as a theme providing a custom default view for a core block.

This enables Container Magic to render a container from any package, not just containers in the current theme.

Container Magic also provides many carefully crafted container php files that should cover many uses of containers through most sites. These are flexible with collapsible (optional) header and footer areas and compatible with a wide selection of theme grid systems, so you can use Container Magic to provide containers for most themes.

The Container Magic dashboard page can then be used to fine tune containers by adding and editing classes used in their structure or creating new variants of the complete set of containers. You can use theme classes to add design to the containers and even change the grid classes used.

Do I need to be a developer to use Container Magic?

Absolutely not! The whole purpose of Container Magic is to enable those who are not developers to use an expanded suite of containers with any theme.

However, if you have some basic knowledge of the classes provided by your theme, Container Magic allows you to use that knowledge to expand the use of containers. This can come in especially useful for managing consistent styling across large sites that make a big use of containers or layouts.

What themes will Container Magic work with?

The containers installed by Container Magic work with Bootstrap based themes such as the core Atomik and Elemental themes and with Ensemble based themes such as Modena.

If they need slight adjustment to work within variations of these themes, or more detailed adjustment to work with other theme grids, the Container Magic dashboard page at Dashboard > Pages & Themes > Container Magic enables CSS classes including grid framework classes to be added or changed for the key elements that structure the containers.

How do I add my own containers?

Container Magic can detect and render any installed containers from:

Your site theme
Container Magic
/application/elements/containers/
Any package providing containers in /packages/package_handle/elements/containers/
The core Atomik theme (if not the same as your site theme)

Container Magic only installs its own containers. If you have other containers in a package or /application/ directory, it is up to you to install them. Then Container Magic can render them.

What if I only want some of the containers?

The easy way to manage this is to let Container Magic install everything, then use the dashboard page at Dashboard > Pages & Themes > Containers to remove the containers you don't want.

To prevent a container from being automatically reinstalled by Container Magic next time it is updated, before uninstalling you can first set an option for Container Magic to not automatically install or reinstall a container.

This makes a note in the configuration file/key jl_container_magic.variant_no_reinstall. The list of containers in the configuration file/key can also be manually edited to disable or re-enable installation of specific containers.

Do I need to create new containers for different styling?

If a design requires two containers using a similar overall area structure and layout, but different CSS styles, such as a background image or colour scheme, Container Magic can create and manage Variants of existing Container Magic containers.

Each Variant is a copy of the entire suite of Container Magic containers. You can then use the Container Magic dashboard page to add or change classes for containers in the variant.

For example, you could have a complete suite of Container Magic containers with a blue theme, and a complete suite of containers with the same structure but a green theme. In the Container Magic dashboard simply create a blue variant and a green variant, then use the Container Magic dashboard page to assign the required blue or green classes from your theme to the containers in each variant.

You don't have to use Variants. For one off styling you can continue to use the Concrete CMS design menu with individual containers and their areas.

Container Magic only manages variants for containers installed within Container Magic.

How do I create new classes?

The dashboard pages in Container Magic allow you to add or change the CSS class names assigned to elements of each container. That is fine if your theme already contains the classes you want to add to a container to provide a design, but what do you do if there are no classes available for what you need?

The scope of Container Magic doesn't extend to declaring new classes. The dashboard editing facility of Container Magic is all about adding classes to containers and adding variants of containers, not creating new classes.

Declaring new classes is up to you, so you may need to know a little CSS. If you need to declare further classes or override existing class styling:

If you are using your own theme, update your theme with your new new classes and styles.
Use the Concrete CMS left side panel for editing theme styles [Cog] > Design > Customize.
Use @mesuva's excellent Theme Styling Tool.
Craft your own <style> element in the Header Tracking Codes at Dashboard > System & Settings > SEO & Statistics > Tracking Codes to create your new new classes and styles
For individual pages, you can also use a <style> element in a Header Extra Content attribute.
Add a <style> element to an HTML block, which can be added to a Page Area or to a Global Area.

Will containers look the same in all themes?

The grid layout of Container Magic containers is designed to work with any Bootstrap based themes such as the core Atomik and Elemental themes and with Ensemble based themes such as Modena.

However, themes will have different colour schemes, spacing, typography and breakpoints. Hence when you switch a site between themes, the containers installed by Container Magic will continue to work and will have a similar structure, but the rest is really up to your theme.

Containers look different to those provided by Atomik

Where your site is using the Atomik theme and Atomik and Container Magic provide a container with the same handle, the container provided by Container Magic will usually be a little bit different

Container Magic provides more collapsible areas.
Containers provided by Container Magic are structured to work across many themes and frameworks. To achieve this they use slightly different structure and classes to the default Atomik containers.
The same applies when comparing containers with the same handle installed by other themes.

A dashboard switch manages the priority of which actual container code is used. This can be set so containers from your site theme are used in preference and Container Magic fills in where a container handle is not provided by your site theme, or that containers from Container Magic are used in preference and your site theme fills in where a container handle is not provided by your Container Magic.

A final option is to render any container not already rendered by your site theme or Container Magic using container code from Atomik. Of course that is only safe where your site theme has a compatible grid framework

Grids skew at some screen sizes

Skewing of gridded areas is an unfortunate glitch with some grid frameworks, so this issue is highly theme dependent.

If you find it affects your use of containers, the simple way round it is to apply a flexbox style to the parent of the gridded areas. In Container Magic's terms, this would be the item Grid Row and the css would be.

display: flex; 
flex-wrap: wrap;

Some theme's include classes you can add to a row to make it flex. For example, when using the Bootstrap 5 framework the classes would be d-flex and flex-wrap.

If your theme or framework already provides classes for implementing flexbox, it is best to use those classes by adding them to the Grid Row item of a variant of the Container Magic container set.

If your theme or framework does not provide suitable flexbox classes, Container Magic provides the cm-flex-wrap class you can add to the Grid Row Item of a variant:

.ccm-page .cm-magic .cm-flex-wrap{ 
   display: flex; 
   flex-wrap: wrap; 
}

Or you could modify all uses of the grid-row class within your theme, either across your site or purely within Container Magic containers:

.ccm-page .cm-magic .grid-row{ 
   display: flex; 
   flex-wrap: wrap; 
}

What happens when containers provide collapsing or optional areas?

Most containers provided by Container Magic include some optional areas that will only render if they have blocks in them. These follow a convention that enables the Container Magic dashboard page to edit the associated css classes.

For other containers, Container Magic can identify some of the usual code structures used for optional or collapsible areas and in most cases can extract the names of those areas.

If the optional areas use the <code>(Optional)</code> marker convention of Container Magic, then integration with Container Check will usually be able to mark the individual areas within the container.

What happens when containers use a loop to render areas?

There is no reason why you can't write code for looped areas. You just won't be able to use the full editing capabilities of Container Magic's dashboard page.

Container Magic can identify some of the usual code structures used for looped areas and will add a note to the dashboard report for that container.

In general the dashboard page will only show a single area listed for the area that is looped.

Can I break my site?

You can't break your site by changing the classes a container uses. To break a site you would need to write bad PHP or HTML and doing that is outside of anything Container Magic does. Nevertheless, it is remotely possible you could add the wrong class in the wrong place and make your site hard to edit. In the remote chance that you do break something badly, Container Magic has you covered:

When editing container's classes in the Container Magic dashboard, you can use the option to Restore Defaults. For the container being edited this will reset the classes in the edit dialogue to the installed defaults.
The Container Magic dashboard page has a Panic Mode option. When set, Container Magic will not insert any classes into containers. You can then edit the classes or Restore Defaults before switching Panic Mode off.
In a worst case, you can also set and clear Panic Mode manually in /application/config/generated_overrides/jl_container_magic.php.

What happens when I update Container Magic?

When Container Magic is updated, all your custom settings are preserved. Any variants you have created will have their PHP and HTML updated to match those provided by Container Magic, including any changes to container structure or new containers added by the addon version update.

Do I need Container Check?

Container Check and Container Magic are both designed to work independently. You can install either addon by itself, or both together.

When both addons are installed you benefit from enhanced functionality in each dashboard page where Container Check can look specifically inside containers built for Container Magic and the Container Magic dashboard page can show additional information sources from Container Check.

Manually Installing or Updating an Addon or Theme

Perhaps you are unable to connect your site directly to the ConcreteCMS marketplace to install an addon or theme. This manual install or update process works for all addons and themes - not just mine.

In your concrete account, find the addon/theme in your Account > Licenses and download. Make sure to scroll down to the most recent version before downloading.
You will not be able to download if the license is assigned to your site. If the license is already assigned, first clear the site assignment and you should then be able to download.
Copy the zip to your site /packages/ directory and unzip (not /concrete/packages !!!). This is usually easiest using your host cPanel file manager.
In your site, visit the Dashboard > Extend page and the theme package will be ready to install or update

The process is exactly the same for addons and themes, except themes have an extra step of activating the theme after installing.

Sometimes the last step can run out of PHP execution time. This is most likely when installing an addon or theme that installs a large amount of sample content. You should not run into such an issue with any of my addons or themes.

If you do run into such issues, you can run the install manually from the shell command line.

$ concrete/bin/concrete5 c5:package-install my_package_handle

$ concrete/bin/concrete5 c5:package-update my_package_handle

When updating, be sure to replace the previously installed package directory rather than adding to it. If not, you could end up accumulating obsolete debris from a previous version of the package. In general you should not uninstall - uninstalling will loose existing data and blocks. Just replace the /packages/_addon_handle_/ directory with the unzipped package update.

If you find yourself often needing to install or update many addons or themes manually, consider my Package Magic addon. Once Package Magic is installed, through the marketplace or manually, all further installs can be handled from the site dashboard using Package Magic. If you build custom code in packages, Package Magic can do a lot more. Package Magic can analyze package structure, zip up packages, upload and download zip files directly to various stores.