Related Guides:

• Modifying Files via Packages

How to create packages with Package Creator

In the "Package Creator" perspective, you can either create a new package ("Create package") or upload an existing package's configuration file ("Upload config").

To create a new package:

1. In the "Package Creator" perspective, select "Packages" and click "Create Package" on the toolbar.
2.  Set the following values in the window that appears:
   • Name: The package name (normally 3-part name separated by periods, for example, "Composite.Tools.PackageCreator", where Part 1 (Composite) stands for the name of the company or an individual who creates the package, Part 2 (Tools) stands for the group the package belongs to, Part 3 (PackageCreator) - the short package name.
   • Group Name: The package's group name (or namespace)
   • Version: The package's current version
   • Author: The package author
   • Website: The package's or the author's package website
   • Read more URL: The URL of a page with more information on the package
   • Description: The general description of the package
   • Technical details: Detailed technical information on the package
3. Click Next.

The new package appears under "Packages".

Editing the package properties

If you want to edit its advanced properties or change the basic properties you've set above:

1. Expand "Packages", select the package and click "Edit" on the toolbar.
2. On the Basic tab of the package properties, change the values you need (see above).
3. On the Advanced tab of the package properties, set the one or more of the following values if necessary:
   • Id: The identifier of the package. You can generate your own GUID in Visual Studio (Tools > Generate GUID), use an online GUID generator (e.g. http://www.famkruithof.net/uuid/uuidgen) or accept the default value suggested by Package Creator.
   • Flush on completion: Use this if you are adding CMS Functions to the package while the System Locking is set to "none" (see below)
   • Can be uninstalled: Specify if the package can be uninstalled after its installation.
   • System locking: You can use one of three types of locking: None (no locking), Soft, Hard (your Orckestra CMS Website will be restarted after package installation complete).
   • Reload console on completion: Use this option to indicate whether to reload the Orckestra CMS administration console after the package's installation.
   • Minimum version and Maximum version: The minimum and maximum versions of Orckestra CMS required by the package to work.
4. Save the change ("Save").

Uploading the package configuration

Rather than create a package from scratch, you can base your package on an existing one, provided that you have the existing package's configuration saved as an XML file. To create a package from the configuration of an existing one, you should upload the configuration file to Package Creator.

When you upload the configuration, all the necessary fields will be filled for you and items preselected as added to the package.

1. In the "Package Creator" perspective, right-click "Packages".
2. Click "Upload Config".
3. Locate and select the package configuration file.

Once uploaded, a package defined in this configuration will appear below "Packages" Here, you can add or remove items as well as edit the package properties ("Edit").

How to make a package active

When you create a new package in the Package Creator perspective, it gets selected as a currently active one, indicated by a green "check" graphic over the package.

When you add something to a package, it will be added to the currently active package only.

If you want to make another existing package active:

1. Expand "Packages" and select the package.
2. Click "Set Active" on the toolbar.

Now everything you add will be added to this package.

How to add various items to the package

Normally you add items to the currently active package from the perspective where these items are, for example, Razor functions in the Functions perspective:

1. Make sure the package you want items to is currently set as active.
2. In a corresponding perspective (for example, "Content"), locate and right-click an item you want to add to the package (for example, a page).
3. Click Add to Package Creator or Add {item}to Package Creator.

The item will appear below the corresponding section (folder) of the package in the "Package Creator" perspective.

In this manner you can add page trees (a page with all its sub pages), media folders, functions, files or data types and data to the currently "active" package.

Please note that you add data types and their data separately (see below).

Adding global data to packages

1. In the "Data" perspective, expand Global Datatypes.
2. Right-click the global data type you need.
3. Click Add data to Package Creator.

Adding page data folder data to packages

Normally, you should add all page data folder data together with the page they are associated with:

1. In the "Content" perspective, expand "Websites".
2. Locate and right-click the page that has the page data folder attached to it.
3. Click "Add This Page Tree to Package Creator".

Adding meta type data to packages

You can also add all meta type data to the package from the context menu of the package:

1. Expand "Packages" and right-click the package you need.
2. Click Add metatypes data to Package Creator.

Adding binaries to packages

In some cases, you may need binaries - DLLs installed into /Bin - in your packages to be already loaded and used while installing the package. For these cases, you can add them to the package as binaries:

1. In the "System" perspective, expand /Bin and add required files to the package.
2. In the "Package Creator" perspective, expand the package, then "Files".
3. Locate and right-click the binary file you've just added and click Add to the Installer Binaries.

The file will also appear under "Installer Binaries" now.

Adding Orckestra CMS and Web configuration settings

You can also add configuration settings from ~/Web.config and ~/App_Data/Composite/Composite.config to packages:

1. In the "Package Creator" perspective, expand Web.config or Composite.config as well as needed sections underneath.
2. Right-click the needed parameter and click Add to the package.

How to exclude items from packages

When bulk-adding multiple items like page trees or data items, you may need to exclude some of them from the package:

1. In a corresponding perspective, (for example, "Content"), locate and right-click an item you want to add to the package (for example, a page).
2. Click Exclude from Package Creator or Exclude This {item} from Package Creator.

Excluding items makes sense especially when you want to export an individual item like a page without its child items like sub pages.

Adding a page tree as a root

You can add a page tree to the package as a root. Normally, when you export a page tree whose uppermost page is a sub page rather than the sub site's root page, you have to make sure that when the package installed on other Orckestra CMS Websites, its parent page identified by its page ID exists there. Otherwise, the page tree will not be added to the existing page tree on that website.

You can however add the page tree from the package as a root on the target Orckestra CMS installation, which will add the entire page tree as another sub site along with the existing one.

This requires a manual change of a specific parameter in the package configuration file after you've added the page tree to the package but before you download the package and/or its configuration.

1. Make sure you've added a page tree to the package. It will appear in the package under "Page trees" section in the "Package Creator" perspective.
2. In the "System" perspective, expand /App_Data/PackageCreator.
3. Locate and edit the corresponding package's configuration file: {Full.Package.Name}.xml
4. In the file, within the <pc:PageTrees> section, locate the <Add/> element with the ID of the page tree you've added to the package (the name attribute).
5. Change the value of its root attribute from "false" to "true".
6. Save the file.

Now if you check the page tree entry below the "Page trees" section of the package in the "Package Creator" perspective, you'll see that it has "(new)" attached to it, which indicates that this page tree will be added on the target system as a root page tree (a sub site).

How to download the created package

Once you've finished your package, you can download it and start using it.

1. In the "Package Creator" perspective, expand "Packages".
2. Select the package and click Download package on the toolbar.

Once you have downloaded your package (a ZIP file), you can:

• install it locally on a different Orckestra CMS Website as a regular CMS Package
• submit it to our Add-On Market
• or make it available on your own package server.

How to get the package configuration

You can save the configuration of the package, which includes added or excluded items as an XML file and then reuse it instead of creating a package anew.

1. In the "Package Creator" perspective, expand "Packages".
2. Right click your package and click Download config.

Later, you can upload the configuration in the "Package Creator" perspective rather than create a package from scratch.

How to export a GUI localization to a package

You can export the CMS Console GUI localization other than default to a package like existing localization packages.

Please see Exporting Localization.

How to replace existing entities when installing a package

By default, a package will not install data items, files, and other entities if they already exist.

To allow overwriting all the installed entities:

1. In the "Package Creator" perspective, expand "Packages".
   
2. Right-click a package
3. Select "Overwrite on Install" from the context menu.

You can disable overwriting by selecting this menu item again. A check mark next to the command will indicate if the entity is currently set to be overwritten or not.

Currently the following entities will be overwritten if you enable this option:

• Pages / page trees
  
• Data (below both "Datatype items" and "Data items")
• Page templates
  
• Functions (except for SQL Functions)
• Files and directories

Enabling overwriting will add allowOverwrite="true" on the respective entry in install.xml in the package.