Packaging a Theme

The Package Format

To distribute a Concrete theme, it's best to package it using the Concrete CMS Package format. This not only facilitates easy updates and deployment but is also required for submission to the Concrete marketplace. When packaging a theme, include various Concrete functionalities such as themes, blocks, and custom code. However, this guide focuses solely on packaging a theme.

To begin, create a directory in the packages folder with a unique name. For instance, if your theme is called "Urbanic," you might name the directory "theme_urbanic" to clearly indicate its content and purpose. This name becomes the package handle.

Place two essential files in this directory: an icon and a controller.php file. The icon, preferably square with rounded corners, represents the package. The controller.php is crucial for defining the package, its version, and includes installation and update routines.

Here’s an example structure for controller.php:

namespace Concrete\Package\ThemeUrbanic;
use Concrete\Core\Package\Package;
use Concrete\Core\Page\Theme\Theme;
defined('C5_EXECUTE') or die("Access Denied.");

class Controller extends Package {
    protected $pkgHandle = 'theme_urbanic';
    protected $appVersionRequired = '5.7.1';
    protected $pkgVersion = '1.0';

    public function getPackageDescription() {
        return t("Adds Urbanic Theme.");
    }

    public function getPackageName() {
        return t("Urbanic");
    }

    public function install() {
        $pkg = parent::install();
        Theme::add('urbanic', $pkg);
    }
}

The namespace and class structure is critical. For example, the namespace should follow the pattern \Concrete\Package\YourCamelCasedPackageHandle. Additionally, the install method must correctly implement theme installation, with attention to passing the $pkg variable to the add method.

After setting up controller.php, move your theme from the application/themes/theme_urbanic directory to the package directory (packages/theme_urbanic). Modify the namespace in your theme's page_theme.php file to align with the package structure. For example:

namespace Concrete\Package\ThemeUrbanic\Theme\Urbanic;

This ensures the theme is correctly recognized within the package context.

Once these steps are completed, your theme is packaged in a format suitable for the Concrete marketplace or sharing across Concrete sites.

Enabling Full Content Swap

Concrete CMS themes are evolving into standalone sites, featuring custom blocks, page templates, and attributes designed for specific configurations. To address compatibility issues with existing sites, we've introduced "Full Content Swap." This feature allows any Concrete package to replace an existing site's front-end content with theme-specific content upon admin consent, ensuring the theme appears as intended by its developers.

Package Your Theme

Ensure your theme is properly packaged. Details here.

Understand the Content Import Format

Learn the XML-based Content Import Format. It defines site structure and content for Concrete sites. For example:

• Installing Dashboard Pages:

  <concrete5-cif version="1.0">
  <singlepages>
    <page name="Sitemap" path="/dashboard/sitemap" ...>
      <attributes>...</attributes>
    </page>
  </singlepages>
  </concrete5-cif>
  

• Activating Themes:

  <concrete5-cif version="1.0">
  <themes>
    <theme handle="elemental" activated="1"/>
  </themes>
  </concrete5-cif>
  

• Adding Page Templates:

  <concrete5-cif version="1.0">
  <pagetemplates>
    <pagetemplate handle="full" name="Full" ... />
  </pagetemplates>
  </concrete5-cif>
  

Inspect concrete/config/install/packages/ for varying content.xml files.

Generate sample content

Steps to create sample content for the content.xml file:

1. Start with a clean installation of the Blank starting point.
2. Install and activate the Theme Package and Sample Content Generator add-on.
3. Design your sample site: Page Types, Page Templates, content, and images to show off the blocks and features of the theme.
4. Install the Migration Tool and create an export batch that includes the theme, pages, stacks, express entities, page types, and any other item types that are part of the theme sample content. Export the content.
5. Archive and download images. Store in "content_files" in your package.
6. Generate content.xml by exporting the batch and copy the file in your package.

Prepare Package

• Add protected $pkgAllowsFullContentSwap = true; to the package's controller.php.
• Create packages/your_package/elements/dashboard/install.php for user information. Note this file is required to exist when allowing a full content swap, even if the file is empty.

Installation Steps

1. Install on a new blank site to test: In a separate webroot, install Concrete with the blank starting point. Install your package and test.
2. Install on site with full content swap: Confirm the installation process on a site with the full content swap option enabled.

Testing and Adjustments

Expect initial failures and adjustments, especially while refining the content.xml file. Test installation on both blank and full-content sites for confirmation.