collective.cover is a package that allows the creation of elaborate covers for website homepages, especially for news portals, government sites and intranets that require more resources than a simple page or collection can offer. However, despite offering rich resources to build a cover, collective.cover also provides a very easy mechanism for managing its contents, built around a drag-and-drop interface.

collective.cover is based on Blocks and Tiles, like Deco, the new layout composition system for Plone.

Suppose you are running The Planet, a news site that has a bunch of editors focused on getting news on different topics, like Economy, Health or Sports.

If you are the main publisher of the site, you may want to delegate the construction of the cover page of the Economy section to the people working on that content area, but you might not want them messing around the Sports section as well.

Also, suppose you have the final game of the World Cup and the match is going to be defined on penalties: you may want to prepare a couple of cover pages and publish the right one focused on the team that won in the end.

These are the kind of issues we want to solve with this package; we are still far from it, but that is the idea.

Got an idea? Found a bug? Let us know by opening a support ticket.

To enable this package in a buildout-based installation:

1. Edit your buildout.cfg and add add the following to it:

   [buildout]
   ...
   eggs =
       collective.cover
   
   [versions]
   ...
   plone.app.blocks = 1.1.1
   plone.app.drafts = 1.0a2
   plone.app.jquery = 1.7.2
   plone.app.tiles = 1.0.1
   plone.tiles = 1.2
   

2. If you are using Plone 4.2.x you need to add the following also:

   [versions]
   ...
   collective.js.jqueryui = 1.8.16.9
   plone.app.jquerytools = 1.5.6
   

After updating the configuration you need to run ''bin/buildout'', which will take care of updating your system.

Go to the 'Site Setup' page in a Plone site and click on the 'Add-ons' link.

Check the box next to collective.cover and click the 'Activate' button.

You add a cover like you would any type of content in Plone:

1. Navigate to the folder where you want to create a cover;

2. Open the "Add Item..." menu and choose "Cover";

3. Fill in the required fields:

   "Title" and "Description"

   Same as with other Plone content, like Page.

   "Layout"

   Choose one of the predefined cover layouts (you will see a preview of the selected layout).

4. "Save".

Your cover is now created based on the information provided.

After the cover is created, you'll notice it comes with some predefined blocks (according to the selected layout), but it still has no content associated. To define the content that will appear on the cover, perform the following steps:

1. Select the "Compose" tab.
2. Open the "Add Content" tab to the right of the green bar. A small window will appear showing the most recent items added in the portal.
3. Select the title of any item in the list and drag it to one of the tiles (dotted boxes) in the content area.
4. Hover the item over one of the Tile boxes. Each Tile allows only certain types of content to be added. If the content you selected is allowed on that Tile, the box will turn green. If not, it will remain gray.
5. Release the item. Information from that content will be automatically applied to the chosen tile and will be visible on the cover.
6. Repeat the process to add content to each one of the other tiles.
7. To visualize the final result, select the "View" tab.

There are also two other navigation options to find content.

You can use the search field in the content selection window to locate the content you want:

1. Type the term you want to find.
2. Push the "Search" button.

The items related to the term you search will be displayed and can be used according to the steps above.

Inside the content selection window you can also navigate through your site to locate existing content.

1. Select the "Content Tree" tab.
2. Select the links to browse through the structure of your site until you find the desired content. All items listed are available to be used according to the steps above.

After content is added to a cover tile, a copy of some of its information will be stored in the cover and will appear to the end user. If necessary, you can change some of the information related to the content exclusively for the cover, without changing the information in the original item. This feature is very useful to adjust the content for the cover. For example, you can shorten a title to better fit it into a homepage layout.

To change the information on the cover, follow these steps:

1. Select the "Compose" tab.
2. Click the "Edit" link on the tile you want to change.
3. Select the portion of text you want to change, like the title, the description or any other text element.
4. Change the text and "Save".

The changes will be applied to your cover immediately.

If you have created a blank cover or if want to change the structure of your current cover, you can add or delete tiles, change the position of an existing tile, or even change the rows and columns structure of the cover. These operations can be performed from the "Layout" tab.

A cover is a combination of three basic elements:

• Rows (which may contain one or more columns, arranged horizontally)
• Columns (which may contain one or more tiles arranged vertically)
• Tiles

To add a new row, follow these steps:

1. In the Layout tab, click the Row icon and drag it to your page. Then you need to add one or more columns to this row so you can add tiles later.
2. Click on the Column icon and drag it into a row.

You can repeat this operation as often as you need. collective.cover will divide the space between the rows and columns automatically.

You can control the width of each column individually:

1. Push the configuration icon of the desired column.
2. Drag the slider sideways, adjusting the desired number of column widths. The higher the number, the larger the column width.
3. "Save".

By default, collective.cover uses a grid of 16 units. Therefore, the sum of the all widths in a column must not exceed 16. To make it easier to edit the width of all columns, first adjust the width of the smallest column.

Now that you have created columns, you can add tiles to it:

1. In the Layout tab, select one of the available Tile icons and drag it to the column where you want to place it.
2. Change the configuration as desired.
3. Push "Save".

The new tile can be used in the Compose tab to select/add content.

You can change the settings of previously added tiles at any time:

1. In the Layout tab, select the Setup icon of the respective tile.
2. Modify the information.
3. "Save".

On a page that has more than one column, you can conveniently move your tiles around:

1. Select the "Layout" tab.
2. Click on a tile and drag it over another column in any of the rows.
3. When you release, the tile it will be positioned in the new column.
4. Repeat as often as necessary.
5. When finished, push "Save" and the new configuration will be applied.

You can save one of your covers as a template for creating other covers on your website:

1. Select the Layout tab.
2. Click the "Export layout" button.
3. Enter a name for your model.
4. Click "Export layout"".

Now this layout can be used as a model to create new covers, as explained in the section "Adding a cover".

Tiles for the collective.cover package provide 3 different views:

This is the view that will be rendered for anyone that has View permission. It will render all fields defined in the schema of the tile, based on their configuration, as set in the configuration view.

This view is a common edit view, where all fields from the schema definition of the tile will be rendered in an "edit" mode. Data entered here will persist in the tile itself.

All fields from the schema will get rendered, irrespective of their setting in the configuration view.

This view is accessed through the "Compose" view of the cover. You should see an "edit" button for each tile.

If you don't want your tile to be editable, you should override the is_editable attribute of your tile base class and set it to False

This view is similar to the edit one, except it is intended for configuring different aspects of the tile. From here you can specify which fields get rendered when viewing the tile, or the order in which they show up.

In addition, each field widget can provide specific configuration options. For instance, an ITextLinesWidget will provide an extra configuration option, "HTML tag", which allows to specify the HTML tag to be used when rendering data saved in this field.

This view is accessed through the "Layout" view of the cover. You should see a "configuration" button for each tile.

If you don't want your tile to be configurable, you should override the is_configurable attribute of your tile base class and set it to False

The configuration view uses z3c.form to automatically render a form based on the tile's schema definition. For that, it renders widgets in a "configure" mode. You can see how existing ones are defined, checking the configure.zcml file under tiles/configuration_widgets

Follow instructions in David Glick's Using tiles to provide more flexible Plone layouts to understand how to develop tiles, and how they work.

Instead of inheriting from plone.tiles.PersistentTile, inherit from collective.cover.tile.base.PersistentCoverTile.

Register your tile on the registry using the "plone.app.tiles" record:

<record name="plone.app.tiles">
  <value purge="false">
    <element>my.package.mytile</element>
  </value>
</record>

There are a couple of methods defined in this base class that provide additional functionality expected by the cover object, that you should override in your class:

populate_with_object(obj)

It takes a Plone content object as parameter, and it will store the content information into the tile. Make sure to call this method to check for permissions before adding content to the tile. Check the code of existing tiles for examples of use.

delete()

It removes the persistent data created for the tile.

accepted_ct()

It returns a list of valid content types that this tile will accept, or None in case it doesn't accept any.

get_tile_configuration()

It returns the stored configuration options for this tile.

Data and configuration for tiles are stored in an annotation of the context where the tile is being shown.

You can see how this works by looking into data.py and configuration.py under the tiles directory.

In order to visualize the tile's content, you need to write a view that will render it. For that, you need to take a few things into consideration.

1. The view will always be rendered, so you need to add conditions to show specific content based on what information the tile has, if any.

2. You need to render content based on the configuration of the tile fields. For that, there's a helper method provided with every tile called get_configured_fields. This will iterate over all fields, and will get the configuration and data for each, in the order that they should be rendered. If the field has no data stored, then it will not be included among the returned values.

   You can override this, in case you need a different behavior, check collection.py under the tiles directory and collection.pt under the tiles/templates directory for an example.

For additional hints on how to create a template for your tile and make it work, check all tiles provided by this package, under the tiles directory.

To add an image field to your tile:

image = NamedImage(
    title=_(u'Image'),
    required=False,
)

Then, you have several ways of using image scales in your tile templates.

1. You can pass width and height to the scale method explicitly:

   <img tal:define="scales view/@@images;
                    thumbnail python: scales.scale('image', width=64, height=64);"
      tal:condition="thumbnail"
      tal:attributes="src thumbnail/url;
                      width thumbnail/width;
                      height thumbnail/height;
                      class position;
                      alt view/data/title" />
   

2. Or you can use Plone predefined scales:

   <img tal:define="scales view/@@images;
                    thumbnail python: scales.scale('image', scale=scale);"
        tal:condition="thumbnail"
        tal:attributes="src thumbnail/url;
                        width thumbnail/width;
                        height thumbnail/height;
                        class position;
                        alt view/data/title" />
   

Cover tiles supports external images too, that means than if you drop a content with an image into a cover tile than implements an image field, cover will honor the image and scales in the original object. This way the image data isn't duplicated and products than allow scales modifications are supported.

Over the years there have been some packages designed to solve the problem of creating section covers in Plone. We have used and have taken ideas from the following:

CompositePack

Very old; the legacy code is so complex that is not maintainable anymore. It has (arguably) the best user interface of all. Layouts can not be created TTW. Viewlets are just page templates associated with content types; you can drag&drop viewlets around the layout. Publishers love it.

CMFContentPanels

Code is very old, but still maintained (at least works in Plone 4). Allows to create complex layouts TTW and use any layout as a template. Easy to extend and edit (but is terrible to find a content to use). Needs a lot of memory to work and aggressive cache settings.

Collage

Allows the creation of layouts TTW but it has (arguably) the worst user interface of all. It is easily extended and there are several add-ons available that provide new functionality for it.

Home Page Editor of the Brazilian Chamber of Deputies Site

Strongly based on Collage, this package was presented at the World Plone Day 2012 Brasilia. It allows editing of home pages and the definition of permissions on blocks of content. Available only for Plone 3 and not openly published… yet.

collective.panels

A new package that lets site editors add portlets to a set of new locations: above and below page contents, portal top and footer. The package comes with a number of flexible layouts that are used to position the portlets, and locations can be fixed to the nearest site object, to facilitate inheritance. In collective.cover (this package), we don't want to use portlets at all.