Creating CMS Packages
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.
Using the CMS Package Creator
Most packages can be created using the CMS Package Creator. This tool allows you to define packages and register elements like CMS Functions, pages, media, data, data types, files and configuration changes using the tree view and a “Add [element] to Package Creator” command in the CMS Console.
For more information on this tool, please see the Package Creator documentation.
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.
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>
<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="188.8.131.52" maximumCompositeVersion="9.9999.9999.9999" />
<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>
nameGroup control how the package will be presented in the package tree view. The
readMoreUrl attributes and the
TechnicalDescription elements are purely informational.
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.
canBeUninstalled attribute (true or false) indicates if the CMS Console should provide a UI to uninstall the package.
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.
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.
<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>
<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.