Concrete Interchange Format

Edit

Improvements?

Let us know by posting here.

Introduction

Concrete Interchange Format (CIF) is an XML-based data serialization format used within the Concrete CMS ecosystem. As CIF files are XML documents they can represent complex data structures while stille being human-readable and to large extent, self-explanatory. It is used for initial setup and updatings of a sites and packages, migrating content across sites, and sharing configurations across multiple environments.

For example, when installing a package, developers can automate the creation of pages, blocks, attributes, users, and other content elements. This eliminates the need for manual configuration by end users and reduces the risk of errors.

Another common use case is when upgrading or migrating a site from one server to another. The Concrete migration tool produces CIF files which reliably transfer content, attributes, users, and other site information to the new site. CIF can also be used to facilitate setting up or updating

Understanding CIF Structure

CIF files are XML documents that adhere to a specific schema (XSD). Below are detailed descriptions of some of the most commonly used elements, however many more exist. The best way to investigate the details of a specific element are to find the element in the schema (above) or use the migration tool to export examples and inspect the result.

Developers can create CIF files manually or edit files generated by using Concrete migration tools. When editing CIF manually, there are various tools that can be used to validate the file (including concrete-cif.jar created specifically for validating CIF). Adding the XSD to the root element, as in the following example, enables IDEs and other tools to validate the content against the schema.

<?xml version="1.1"?>
<concrete5-cif 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://github.com/concretecms/concrete-cif/releases/latest/download/concrete-cif-1.0.xsd"
    version="1.0"
>
    <!-- data -->
</concrete5-cif>

Root Element: <concrete5-cif>

  • Attributes:
    • version: The version of the CIF format. In this example, it's "1.0".

Themes

<themes>

This section contains information about the themes available in the system.

<theme>

  • Attributes:
    • handle: The unique identifier for the theme.
    • package: The package associated with the theme. It's empty if not associated with any specific package.
    • activated: Indicates whether the theme is activated (1 for activated, 0 for deactivated).

Attribute Keys

<attributekeys>

This section defines the various attribute keys available in the system. An attribute key represents a specific type of data associated with collections or objects.

<attributekey>

  • Attributes:
    • handle: The unique identifier for the attribute.
    • name: The name of the attribute.
    • package: The package associated with the attribute key.
    • searchable: Indicates whether the attribute is searchable (1 for searchable, 0 otherwise).
    • indexed: Indicates whether the attribute is indexed (1 for indexed, 0 otherwise).
    • type: The type of the attribute. Examples include select, textarea, topics, text, etc.
    • category: The category to which the attribute belongs, such as collection or event.

<type>

This tag, nested within <attributekey>, provides additional details about the attribute's type. It can contain the following attributes depending on the type of the attribute key:

  • allow-multiple-values: For select type attributes, this indicates whether multiple values can be selected (1 for allowing multiple, 0 otherwise).
  • display-order: For select type attributes, this indicates the display order of options. Possible values include display_asc (ascending) and display_desc (descending).
  • allow-other-values: For select type attributes, this indicates whether users can input values not listed as options (1 for allowing other values, 0 otherwise).

<options>

The <options> tag is used within select type attributes to list the available options.

<option>

Each <option> represents a selectable choice within a select type attribute.

  • Attributes:
    • value: The value of the option.
    • is-end-user-added: Indicates if the option was added by an end-user (1 for yes, 0 for no).

<tree>

For topic type attributes, the <tree> tag specifies the hierarchy of topics associated with the attribute.

  • Attributes:
    • name: The name of the tree (e.g., "Blog Entries").
    • path: The path to the root of the topic tree.

Attribute Sets

<attributesets>

This section defines the sets of attributes, categorizing them into logical groups.

<attributeset>

  • Attributes:
    • handle: The unique identifier for the attribute set.
    • name: The name of the attribute set.
    • package: The package associated with the attribute set.
    • locked: Indicates if the set is locked (1 for locked, 0 for unlocked).
    • category: The category of the set, such as collection or event.

Each <attributeset> can contain one or more <attributekey> elements representing the keys within that set.

Page Templates

<pagetemplates>

This section defines the page templates available in the system.

<pagetemplate>

  • Attributes:
    • icon: The filename of the icon representing the template.
    • name: The name of the page template.
    • handle: The unique identifier for the page template.
    • package: The package associated with the page template.
    • internal: Indicates if the template is internal (1 for internal, 0 otherwise).

Page Types

<pagetypes>

This section defines the types of pages available in the system.

<pagetype>

  • Attributes:
    • name: The name of the page type.
    • handle: The unique identifier for the page type.
    • package: The package associated with the page type.
    • is-frequently-added: Indicates if the page type is frequently added (1 for frequently added, 0 otherwise).
    • launch-in-composer: Indicates if the page type launches in the composer (1 for yes, 0 otherwise).

Each <pagetype> can have several nested elements, including:

<pagetemplates>

Defines the templates that can be used for a specific page type.

  • Attributes:
    • type: Specifies whether all templates are available (all) or just custom ones (custom).
    • default: The default template for the page type.

<target>

Specifies the target configuration for the page type.

  • Attributes:
    • handle: The handle for the target configuration.
    • package: The package associated with the target configuration.

<composer>

Defines the composer settings for the page type.

<formlayout>

Defines the layout of the composer form for the page type. It contains one or more <set> elements.

<set>

Represents a logical grouping of controls in the form layout.

  • Attributes:
    • name: The name of the set.

Each <set> contains multiple <control> elements.

<control>

Represents a control in the form layout.

  • Attributes:
    • custom-template: Specifies a custom template for the control.
    • required: Indicates if the control is required (1 for required, 0 otherwise).
    • custom-label: Specifies a custom label for the control.
    • type: The type of control, such as core_page_property or collection_attribute.
    • handle: The handle for the control.

<output>

Defines the output configuration for the page type. It contains one or more <pagetemplate> elements.

Pages

<pages>

This section defines the pages in the system.

<page>

Represents a page in the system.

  • Attributes:
    • name: The name of the page.
    • path: The path to the page.
    • filename: The filename associated with the page.
    • template: The template used by the page.
    • user: The user associated with the page.
    • description: The description of the page.
    • package: The package associated with the page.

Each <page> contains several possible elements:

<attributes>

Defines the attributes for the page.

<area>

Represents a content area on the page. It can contain multiple <block> elements representing individual pieces of content.

<block>

Represents a block of content within an area.

  • Attributes:
    • type: The type of block, such as content or image.
    • name: The name of the block.
    • custom-template: Specifies a custom template for the block.
    • mc-block-id: A unique identifier for the block.