Install the Package and Theme

We’ve got everything in place to install our theme. It won’t do much, of course, since there aren’t any page templates in it yet! But one thing at a time.

In order to install the theme when we install the package, we need to add some code to the package controller’s install() method we wrote earlier to install the theme. This could be as simple as adding this class to the top of the controller.php file:

use Concrete\Core\Page\Theme\Theme;

and then adding this code to the install() method:

public function install()  
{  
    $pkg = parent::install();  
    $theme = Theme::install(‘theme_dreamrs’, $pkg);  
}

That code would install the package and the theme, registering the theme with the package so Concrete CMS knows where to look for its assets. However, I’d like to install this theme in a different way.

Concrete Interchange Format

Instead of using PHP to install the Dreamrs theme, let’s use the Concrete Interchange Format, which I will abbreviate as CIF from this point. CIF is an XML format that describes the current state of a Concrete site. You can include multiple types of content and functionality in a single, readable XML document, and install all of the items with a single line of code. Even better, when you need to add functionality to a site, just add it to the CIF file, and install the file again within the package update() method. Concrete will figure out what currently exists, skip it, and only install new items.

Create the XML File

Let’s create a CIF XML file for our Concrete theme. From within the root of your Dreamrs package,

mkdir install  
cd install  
touch theme.xml

Within this empty XML file, add this content:

<?xml version="1.0"?>
<concrete5-cif version="1.0">
  <themes>
    <theme handle=“theme_dreamrs” package=“dreamrs” activated="1"/>
  </themes>
</concrete5-cif>

Hopefully this is a little self-explanatory: we have the opening tag that denotes the file is a CIF file. Next, we have a <themes> node that wraps all themes we’re going to install with this file. Within that we have a single entry that lists our theme -- it’s handle is theme_dreamrs within the dreamrs package. Finally, we’re going to activate this theme as well, which is why we’re passing activated=“1”.

How do you know what to write?!

Obviously you wouldn’t know how to write this off the top of your head. Fortunately there are two decent ways of getting a CIF reference:

Elemental

A good example of creating a relatively complex website completely from CIF XML is the Elemental Full starting point. You can find its XML file in concrete/config/install/packages/content.xml.

Generating CIF XML

You can generate CIF files from an existing Concrete site using the Migration Tool. While most of the migration tool is geared toward importing content into a Concrete site (also in CIF XML), it also provides tools for exporting CIF XML from Concrete sites.

This is most useful when you’re creating content in your site, and you’d like to include that content when you install a package.

Modify the Install Routine.

Now that we have a theme.xml file that lists our theme in CIF format, let’s install that file from within our install() and upgrade() methods. Modify the package controller.php like this:

public function install()
{
    parent::install();
    $this->installContentFile('install/theme.xml');
}

public function upgrade()
{
    parent::upgrade();
    $this->installContentFile('install/theme.xml');
}

That’s it. We’re now going to be installing this content file every time we install this package, or upgrade the package. The theme will only be installed once, though.

Install the Package

With those changes in place, we should be ready to install the package, which now looks like this in the filesystem:

Clicking install from the Dashboard will install the Dreamrs package, which will install the Dreamrs theme and activate it across the site.

Success! Now let’s make sure the theme was properly installed and activated by going over to Dashboard > Pages & Themes.

Also positive! The Dreamrs theme is installed and activated. It has its custom thumbnail displayed, and its name and description are also displaying properly.

And, when we navigate back to the home page, we’re not going to see much, but that’s ok; it means that our theme is activated and just can’t find any way to render the site’s content:

We’ll fix that shortly.