==========================
Frequently Asked Questions
==========================
Below, we will attempt to answer some frequently asked questions about Deco,
Blocks and Tiles.
How do I theme a site using Deco and Blocks?
--------------------------------------------
You may have realised that it is possible to "theme" a site using site
layouts, by placing global elements and branding on the site layout itself.
This may be appropriate for simple sites with minimal branding needs: as a
rule of thumb, if you think you could construct your branding with the Deco
visual editor only, using site layouts to contain your visual identity may
be appropriate.
There are some caveats, however:
* It is best to keep your site layouts focused on semantic layout, e.g. using
names such as "Article" or "Landing page". If content authors choose site
layouts for their pages and sections based mainly on visual identity, it
will be harder to reuse content or rebrand the site later.
* You may choose to let content authors or site administrators have the
permission to create new site layouts or edit the contents of site layouts
(e.g. to manage global elements such as advertisement or notifications). If
the site layout is complex, it may be difficult to maintain visual
consistency across multiple site layouts.
Hence, we would generally recommend that you keep your site layouts as
semantic and simple as possible, and apply a visual identity using `Diazo`_
and `plone.app.theming`_. Deco and Diazo are designed to work together, with
Deco focused on site layout as it pertains to content management and editing,
and Diazo focused on branding and theming.
What happens to viewlets?
-------------------------
In Plone 3 and 4, viewlets are used for two purposes:
1. As a means of breaking the main site layout templates up into smaller
chunks that can be independently managed.
2. As a means for third-party add-ons to inject bits of markup into the page
at predefined locations (e.g. "above content" or "below content") without
the need to customise global page templates.
The first of these is problematic in a some ways. For example, it relies on a
mixture of global registration (ZCML) and local, persistent configuration (the
``viewlets.xml`` GenericSetup import step) to control what is shown and in
what order. It also makes it difficult to understand how the final page will
look by inspecting ``main_template``.
Hence, this pattern of using viewlets is superseded by tiles. Tiles are simply
placed into the relevant site layout. The ordering of tiles is controlled by
the ordering of the relevant tile placeholders. As a bonus, tiles are easier
to write than viewlets and can have associated configuration.
The second use of viewlets is entirely legitimate, of course. Here, specific
ordering should matter less (a third-party add-on cannot know which other
third-party add-ons may be adding content in the same viewlet managers), and
the focus becomes on semantic or semi-semantic locations on the page in which
viewlets can be inserted. This is indeed closer to the original purpose of
viewlets.
For this pattern, there is a tile called
``@@plone.app.standardtiles.viewletmanager``, which looks up and renders a
viewlet manager. For example, the default sitelayout in Deco contains::
Note that the tile takes a parameter, ``manager``, giving the name of the
viewlet manager to look up and render. For viewlet managers rendered in the
head of the page, we use::
This ensures the contents of the viewlet manager are rendered in the
``