Difference between revisions of "Theme Package Structure"

Revision as of 11:44, 30 July 2012

The archive file of a theme is a simple file that provides a consistent way of moving all of the CSS, JS and Media assets used with an unroole theme from one system to another. Because of the design of Layouts in unroole all theme's can be developed that target a variety of different channel's without necessarily requiring layouts on those channel's to follow a specific design.

Properties

Any settings specific to a particular theme can be found in the properties.xml file that is part of every theme archive. The properties file includes the following information:

• Theme Frameworks - The frameworks available from this theme.
• Theme Stylesheets - The order in which the css from the theme in relation to system css will be loaded to prevent errors.
• Theme JavaScripts - The order in which the js from the theme in relation to system js will be loaded to prevent errors.
• Channel Compatibility - The channel types this theme is compatible with.
• Site Layout Restrictions - No longer used.

Please not that for any files referenced in the properties.xml file a relative path including file extensions must be provided. For any files loaded from the framework folder the term ":framework" should be added to the beginning of the path.

Example

An example of a complete properties.xml file can be seen below.

<?xml version="1.0" encoding="UTF-8"?>
<theme_package xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="properties.xsd">
	<load_files>
		<frameworks>
			<folder>colorbox</folder>
 		</frameworks>
		<javascripts>
				<file>unroole_system</file>
				<file>example</file>
				<file>:framework/colorbox/colorbox/jquery.colorbox</file>
		</javascripts>
		<stylesheets>
				<file>unroole_system</file>
				<file>example</file>
		</stylesheets>
	</load_files>
	<system>
		<compatibility>
				<channel>mobile_api</channel>
				<channel>website</channel>
		</compatibility>
		<site_layout>
		</site_layout>
	</system>
</theme_package>

Schema

During import the properties.xml file is compared with the following schema for consistency. Any properties.xml file which does not match this schema will not be uploaded into the system.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="theme_package">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="load_files">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="frameworks">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="folder" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element name="javascripts">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="file" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element name="stylesheets">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="file" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="system">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="compatibility">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="channel" minOccurs="0" maxOccurs="unbounded">
                      <xs:simpleType>
                        <xs:restriction base="xs:string">
                          <xs:enumeration value="mobile_api"/>
                          <xs:enumeration value="website"/>
                        </xs:restriction>
                      </xs:simpleType>
                    </xs:element>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element name="site_layout">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="layout" type="xs:nonNegativeInteger" minOccurs="0" maxOccurs="unbounded"/>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Archive File

A theme archive file in unroole is simply a zip file that conforms to a specific format and structure. The structure used in the zip file mimics the information stored in the properties.xml file. All files included in the following pre-determined folder will be uploaded from the archive into the system. Certain folders such as javascripts and stylesheets will only accept files ending in the css and js extensions. Below is a description of the theme archive contents.

• frameworks - Entire framework folders can be loaded here.
• javascripts - Any single javascript files not part of a framework.
• media_assets - Any media assets such as images or videos to be included in the theme.
• stylesheets - Any single stylesheet files not part of a framework.
• site_layout - (Optional) Exported HTML of Channel Layouts generated when exporting. These files will be ignored during import.
• unroole_system - (Optional) Additional system files generated on Channel Layouts export. These files will be ignored during import.

Example

Below is an example of a simple theme's archive.

media_assets/
media_assets/sample.png
media_assets/sample.mp4
javascripts/
javascripts/sample.js
stylesheets/
stylesheets/sample.css
frameworks/
frameworks/colorbox/...
frameworks/jquery_ui/...
site_layout/
site_layout/generic_layout.html
site_layout/site_layout_1.html
site_layout/my_other_channel_layout.html
unroole_system/

properties.xml