How to Work With Packages

This section describes how to use the following in CQ:

• Package Manager, which you use to manage the packages in your local CQ installation. including how to upload, create, and download packages. It also explains what packages are and how to provide permissions to them.
  
• Package Share, which lets you find, share, and download packages, components, and hotfixes from the Day server. You can also upload packages for internal company use.
  

Packages can include content and project-related data. A package is a zip file that contains the content in the form of a file-system serialization (called "vault" serialization) that represents the content from the repository as an easy-to-use-and-edit representation of files and folders.

Additionally, it contains vault meta information, including a filter definition, and import configuration information. Additional content properties can be included in the package, such as a description, a visual image, or an icon that are not used for package extraction; these properties are for the content package consumer for informational purposes only.

You can perform the following actions with packages:

• Create new packages
• Modify existing packages
• Build packages
• Upload packages (CQ does not automatically install packages after uploading)
• Install packages
• Download packages, such as hotfixes, from the Package Share library
• Upload packages to the internal company section of the Package Share library
• Download packages from CQ to a local machine
• Apply package filters
• View package information

As a package can contain an icon, Day uses the following conventions for official packages:

The Package Manager manages the packages on your local CQ installation.

To grant users the right to create, modify, upload, and install packages, you need to give them the appropriate permissions at the following locations:

• /etc/packages (full rights except delete)

Users must have rights to the package (/etc/packages) as well as the node that contains whatever is inside the package.

See Setting permissions for instructions on changing permissions.

To create a new package:

1. On the CQ5 Welcome screen, click Packages and then Package Manager.

2. Click New Package.

3. Enter the name of your new package and the group (folder) you would like it to belong to and click OK.  If you leave the group name blank, it will install the package in the main package list. Use groups to organize your packages.

4. CQ lists the package in the appropriate folder. Click the package icon to open the package.

5. Click Edit to open the package editor. Here, you can add a description, change the icon, and add filter definitions. Click OK after you are finished editing.

6. Add a package screenshot by double-clicking the image component in the Screenshots area, adding an image, and clicking OK. You add additional screenshots by dragging the Package Screenshots component from the sidekick into the Screenshots area.

7. Drag the Filter Definition icon from the sidekick to the Package Filters area. Double-click to open it and enter the path for the content you want to package. You can add exclude and include filters as described in Applying package filters. Click OK when finished.

For simple package definitions, there is no need to specify include or exclude rules. The following example is for informational purposes only and would better be served by a root path pointing to /content/en.

8. Click Build to build your package. CQ adds package information to the package list.

CQ allows you to add the include and exclude filters to the path so that you can include or exclude certain content. The following table describes these filters and provides examples.

To apply package filters:

1. On the CQ5 Welcome screen, click Packages and then Package Manager.

2. Navigate to the package that you want to apply package filters to and click the package icon to open it.

3. Double-click the path you want to add filters for. (Or if necessary, create a new path by dragging the Filter Definition icon from the sidekick to a blank component in the Filters area.)

4. If necessary, select the root path.

5. Enter include and exclude rules. Add more rules by clicking the Plus symbol + button. Remove rules by clicking the Minus symbol - button. The order of how the rules appear does matter. Order the rules with the Up or Down button.

6. When finished entering rules, click OK.

Downloading packages means doing one of the the following:

• Downloading packages from the Package Share site at dev.day.com where the packages are installed into your repository. These packages include hotfixes and other shared packages.
  
• Downloading a package from CQ to your computer.

This section describes how to download a package from CQ to your computer. See Using Package Share for information on downloading hotfixes, feature packs, and packages from your company's package share.

To download a package from CQ to your computer:

1. On the CQ5 Welcome screen, click Packages and then Package Manager.

2. Navigate to the package you want to download.

3. Click the blue, underlined zip file link in the package you want to download. CQ downloads the package to your computer.

A package upload refers to uploading a package from your local drive into the CQ Package Manager.

To upload a package:

1. On the CQ5 Welcome screen, click Packages and then Package Manager.

2. Click Upload Package and browse to the package that you want to upload and click OK. The new package is listed in the Package Manager list. To make the content available to CQ, be sure to install the package.

You can edit a variety of package settings, including the package description, icon, and screenshots, as well as package filters and advanced settings regarding dependencies and provider information. This procedure describes how to edit package settings. Adding screenshots gives users an idea of what the content looks like before installing. For more information on filters, see Applying Filter Definitions.

To edit the contents of a package:

1. In the Package Manager, navigate to the package you want to edit and click the package icon to open it.

2. Click Edit. By default, the Settings tab opens. Enter a description, if desired, and any fixed bug or issues (one per line).

3. Click Advanced. Here you enter additional information that you want to display, including any dependencies, replaced packages, and provider and tester information.

4. To change the package icon, click Thumbnail Image. Either drag an image from the Content Finder or upload an image. Crop or rotate the image, as necessary.

6. Click OK when finished making changes.

7. To add screenshots pertaining to your package, double-click the image icon in the Screenshots area and add an image. To add multiple screenshots, drag the Package Screenshot component from the sidekick to the Screenshots area. Screenshots provide a visual cue of what the content looks like before installing.

8. To modify the path and the package filters, either double-click an existing path to modify it or add another path by dragging the Package Filter definition to the Package Filters area. For information on applying filters, see Applying package filters.

9. If necessary, re-build the package by clicking Build.

You build packages that you can later install into a CQ instance.

To build a package:

1. On the CQ5 Welcome screen, click Packages and then Package Manager.

2. Navigate to the package you want to build and open it by clicking the package icon.

3. Click Build. CQ displays a confirmation that the package was built and updates the package list information.

After you upload a package, you need to install the content. To have a package installed and functional, it needs to be both uploaded to CQ (either from your local drive or from the package share) and be installed.

To install a package:

1. On the CQ5 Welcome screen, click Packages and then Package Manager.

2. Navigate to the package you want to install. Packages that have not yet been installed have the Install button next to it. (Alternatively, you can open the package by clicking on its icon to access the Install, Test Install, and Contents commands.)

3. Click Install. The word Installed appears next to the package after it has been installed.

CQ lets you uninstall packages by reverting to the latest snapshot.

To uninstall the contents of a package:

1. On the CQ5 Welcome screen, click Packages and then Package Manager.

2. Navigate to the package you want to uninstall and click the package icon of the package you want to remove.

3. Click Uninstall to remove the contents.

To view package information:

1. On the CQ5 Welcome screen, click Packages and then Package Manager.

2. Navigate to the package you want to view information for and click the package icon. CQ displays package information.

To delete a package:

1. In the Tools menu, click the Packages folder so the packages are listed in the right-hand pane.

2. Click the package you want to delete so that it is highlighted and do one of the following:

• Click Delete in the menu.
• Right-click and select Delete.

 3. CQ confirms that you want to delete the package. Click OK to confirm the deletion.

The Package Share is a publicly available server to share Content-Packages, powered by Day. Packages can include official hotfixes, feature sets, and CQ-updates or CQ-user generated content to share with other users. Access to the Package Share is available for partners and customers of Day. A registration form in the Package Share must be filled out for access.

With Package Share, you can download Day content packages and also upload and share packages within your company.

There is no anonymous access to the Package Share; that is, only registered users are allowed to view and download packages.

The following describes the Package Share structure.

The following groups are available for package share:

• Company-internal sharing
  
• Packages provided by Day (updates, feature packs, and hotfixes)

A packageshare user is a member of his or her respective company group. A user of a partner can be a member of his or her customer groups.

If you need access to Day's Package Share, please fill out the registration form.

Day will check with the appropriate departments for required/allowed permissions and add you to your company's group.

In Day's Package Share library, each package has a status indicator to let you know whether you have already downloaded or installed the package. The indicator appears to the right of the package name as in the following example:

Before downloading and installing packages from Day's Package Share, be sure you have access to the library. See Requesting access to the Package Share library.

To download and install packages from Package Share:

1. On the CQ main page, click Packages and then select Package Share. The Package Share page opens.

2. Log into Package Share. A list of folders and packages displays. You see a Public folder and one specific to your company.

3. Navigate to the package you want to download and click Download.

4. Once downloaded, the word Downloaded appears next to the package.

5. Navigate back to Packages and then navigate to the package you just downloaded.

6. Click Install to install the package to your local CQ installation.

With Day's Package Share, you can upload and share packages within your company. These packages are not available to the general CQ community, but are available to all users registered with your company.

To upload packages to the company-internal Package Share:

1. In CQ, open the package manager by clicking the Packages link on the main page and then clicking Package Manager.

2. Navigate to the package you want to upload and click the package icon to open it.

3. Click Share to upload the package to Package Share.

5. In the Share Package window, click Share to upload it to your internal company's Package Share. CQ shows you the status and indicates when the package has finished uploading. After uploading, you can click the x from the window to exit the Share Package window.

After upload, navigate to your company's internal folder to see the package you just shared.

To make a package available to the general CQ community in the public Package Share:

1. Upload your package to your company's internal Package Share site as described in Uploading packages to the company-internal Package Share.
2. After it is uploaded, click Sign Up in the Public Sharing area of the page. Someone from Day will evaluate the package and post it to the public folder, if appropriate.