Build your own CMS Packages and share them with the world.

CMS Packages are best described as self-contained install scripts, which can update and add content, code and configuration on a C1 CMS site. You should build a CMS Package if you need to roll out the same change/feature on multiple sites or you want to share a functionality via the C1 CMS Add-on Market Place.

CMS Packages can be installed via a CMS Package Server or by uploading a CMS Package to the CMS Console directly. For information on installing packages, please see http://users.c1.orckestra.com/Superuser/Packages

In the following article, we will cover ways to create and share CMS Packages. Most often, you will find tools, which automate the process for you, but for scenarios that are more complex, you may need to tweak the installation script by hand or even write your own install step providers.

CMS Package Servers

While this article is primarily focused on creating CMS Packages we will briefly touch on how you can distribute and install your CMS Packages.

C1 CMS comes with a CMS Package Server pre-registered. This is a URL that points to a web service that exposes CMS Package metadata and files. When you browse the “Packages | Available Packages” section in the CMS Console, the packages shown here is drawn from this web service.

You can add more package sources if you like. You can set up your own package servers and register them in the CMS Console (go to the System perspective and select “Packages | Package Sources” and execute “Add Package Source”).

The fastest way to set up your own CMS Package Server is to set up a C1 CMS site and install the Package Server add-on on it. After installation, you can use this site as a “Package Source”.

If you have created a package you would like to share with the CMS Community (as either an open source, free or commercial product) you can set up a public CMS Package Server and spread the word on pages like http://c1.orckestra.com/Community/Contribs or you can send your package to Composite to get it hosted on the default CMS Package Server. See http://c1.orckestra.com/Add-ons/Share-your-Addon

The anatomy of a CMS Package

At the file level, a CMS Package is a ZIP file, which contains an install.xml file at the root. This install.xml file contains some metadata (like the package name, description, supported versions of C1 CMS etc.) and a number of steps to be executed during installation and uninstallation.

Besides the install.xml file, the ZIP will typically contain other files, used by the installer steps.

The anatomy of install.xml

The overall structure of the install.xml looks like this:

<?xml version="1.0" standalone="yes"?>
<mi:PackageInstaller xmlns:mi="http://www.composite.net/ns/management/packageinstaller/1.0">
  <mi:PackageRequirements  />
  <mi:PackageInformation />
  <mi:PackageFragmentInstallerBinaries />
  <mi:PackageFragmentInstallers />
</mi:PackageInstaller>

PackageRequirements

The <mi:PackageRequirements  /> element defines the maximum and minimum C1 CMS Versions required to install the package. Here you should ensure that the minimum version specified contains the needed APIs and the like required by your package.

<mi:PackageRequirements 
	minimumCompositeVersion="4.2.0.0" 
	maximumCompositeVersion="9.9999.9999.9999" />

PackageInformation

The <mi:PackageInformation /> element contains descriptive elements and also tells the installer system about the identity and overall behavior of the package.

<mi:PackageInformation 
	name="Composite.Sample.Package" 
	groupName="Composite.Sample" 
	version="1.2.3" 
	author="Contoso" 
	website="http://www.contoso.com" 
	readMoreUrl="http://www.contoso.com/readmore.htm" 
	id="00000000-0000-0000-0000-000000000000" 
	canBeUninstalled="true" systemLocking="hard" 
	flushOnCompletion="false" 
	reloadConsoleOnCompletion="true">
  <Description>longer text here ...</Description>
  <TechnicalDetails>longer tech text here ...</TechnicalDetails>
</mi:PackageInformation>

The attributes name and nameGroup control how the package will be presented in the package tree view. The version, author, website and readMoreUrl attributes and the Description and TechnicalDescription elements are purely informational.

The id attribute should be unique for your package, since C1 CMS will prevent installation of a package with a previously installed id. This should be a GUID.

The canBeUninstalled attribute (true or false) indicates if the CMS Console should provide a UI to uninstall the package.

The systemLocking attribute - ”soft”, “hard” or “none” – defines the way the system should act while the install (or uninstall) process is executing.

• “none” means that no system locking should take place.
• “soft” means that the user installing the module should be put in a “wait mode”
• “hard” means that the entire website – including the public render engine – should be taken offline.

The attributes flushOnCompletion and reloadConsoleOnCompletion are optional.

When the attributes flushOnCompletion is set to "true", the system will “reboot” C1 CMS in the current application domain, reloading all configuration and data. The default value is "false". When the attributes reloadConsoleOnCompletion is set to "true", the system will force the user installing or uninstalling the package to reload his console. The default value is false.

PackageFragmentInstallerBinaries

The <mi:PackageFragmentInstallerBinaries /> element is optional, but allow you to register your own fragment installer assemblies in the install process. In the PackageFragmentInstallers element (see below) you refer to installer actions by specifying a class name, and if one or more of those classes exist in an assembly you created yourself, you need to include this assembly in the ZIP file and refer to it as an element below <mi:PackageFragmentInstallerBinaries /> like this:

<mi:PackageFragmentInstallerBinaries>
    <mi:Add path="~\Bin\My.Own.FragmentInstallers.dll" />
</mi:PackageFragmentInstallerBinaries>

PackageFragmentInstallers

The <mi:PackageFragmentInstallers /> element contains the steps to be executed during installation. The steps will be executed in the order you specify.

Each step is represented with a specific package fragment installer. Please see "Package Fragment Installers" for more information.