Integrating your own containers

Container Magic will find and list all containers installed on your site. It is not limited to the containers provided by Container Magic. As long as a container is installed, Container Magic will list it and Container Check will do its best to show a preview.

Containers can be in your theme, in /application/elements/containers/, or in  /packages/your_package/elements/containers/. Its up to you to install them. But once installed, Container Magic will list them and they will render in your site pages.

If you want to take advantage of Container Magic's container class editing facility, there are a few conventions to follow.

Lets have a look inside a Container Magic template

[code]

<?php
defined('C5_EXECUTE') or die("Access Denied.");

use Concrete\Core\Area\ContainerArea;
use ContainerMagic\ContainerStyler;

/*
 * John Liddiard (aka JohntheFish) www.c5magic.co.uk
 * This package contains software copyright and proprietary to John Liddiard
 *
 */
$cs = new ContainerStyler(__FILE__);
?>
<div class="cm-two-column cm-magic <?php echo $cs->get(); ?>">
    <div class="<?php echo $cs->get('Grid Container'); ?>">
        <?php
        $area = new ContainerArea($container, 'Body Full Above');
        if ($c->isEditMode() || $area->getTotalBlocksInArea($c) > 0) {
            ?>
            <div class="<?php echo $cs->get('Grid Row'); ?>">
                <div class="cm-full-body-above cc-optional <?php echo $cs->get('Body Full Above'); ?>">
                    <?php
                    if ($c->isEditMode()) {
                        ?>
                        <code>
                            <?php
                            echo t('Optional')
                            ?>
                        </code>
                        <?php
                    }
                    $area->display($c);
                    ?>
                </div>
            </div>
            <?php
        }
        ?>
        <div class="<?php echo $cs->get('Grid Row'); ?>">
            <div class="cm-two-col-1 <?php echo $cs->get('Column 1'); ?>">
                <?php
                $area = new ContainerArea($container, 'Column 1');
                $area->display($c);
                ?>
            </div>
            <div class="cm-two-col-2 <?php echo $cs->get('Column 2'); ?>">
                <?php
                $area = new ContainerArea($container, 'Column 2');
                $area->display($c);
                ?>
            </div>
        </div>
        <?php
        $area = new ContainerArea($container, 'Body Full Below');
        if ($c->isEditMode() || $area->getTotalBlocksInArea($c) > 0) {
            ?>
            <div class="<?php echo $cs->get('Grid Row'); ?>">
                <div class="cm-full-body-below cc-optional <?php echo $cs->get('Body Full Below'); ?>">
                    <?php
                    if ($c->isEditMode()) {
                        ?>
                        <code>
                            <?php
                            echo t('Optional')
                            ?>
                        </code>
                        <?php
                    }
                    $area->display($c);
                    ?>
                </div>
            </div>
            <?php
        }
        ?>
    </div>
</div>

[/code]

And here is the same container rendered in this page. We have use area design for each area in the container to add a well class to help show the areas.

Lets have a look at how this fits together. Most of this is the kind of template code is what you would expect in a container template, so we will only go into detail on the parts unique to integrating with Container Magic.

ContainerStyler

The ContainerStyler class is the interface between a container and the styling rules managed by Container Magic. It is important to instantiate it as $cs because as well as running in the code, the container php source is also parsed to extract the keys passed to in $cs->get('Key Name') to facilitate both editing the classes and previewing the container with Container Check.

The settings are saved in the config file /application/config/generated_overrides/jl_container_magic.php. In our example, these are just the theme grid classes. Container Magic's dashboard page enables these to be edited to add further styling or to work with different grids.

There are no hard rules about the names used for these keys, but it is generally useful to match them to areas within the container or semantically to the grid. If no key is given, the key 'cm_magic' will be assumed and this is the key for the overall container.

[code]

'container_classes' => [
    'two_column' => [
            'cm_magic' => '',
            'grid_container' => 'container grid-container',
            'grid_row' => 'row grid-row',
            'body_full_above' => 'col-md-12 column-12',
            'column_1' => 'col-md-6 column-6',
            'column_2' => 'col-md-6 column-6',
            'body_full_below' => 'col-md-12 column-12',
        ],
]

[/code]

In the containers supplied with Container Magic these classes are verbose because they are a combination designed to work with multiple theme grid frameworks.

The image below shows how this appears in the dashboard edit dialogue.