EXPORTING FROM CPSSKINS

Important notice: in the current state of the CPSSkins exporter, you will still need to keep CPSSkins and its themes in your portal so that the exported theme actually works. The reason becomes obvious if you read the section about URIs correction below.

Dependencies: CPSSkins >= 2.16.0

Tutorial within subversion

This procedure has been applied to export the default CPS theme, with one Subversion checkin per step, to provide some kind of tutorial of the process.

The checkins numbers are 54086 through 54090, available at http://svn.nuxeo.org/trac/pub/changeset/54086 and so on.

Preparations

You need to have the CPSDesignerThemes product in the Zope instance from which you plan to export the theme.

Create an External Method at the root of the portal.
id : cpsskins_export module: CPSDesignerThemes.cpsskins_export function: export

Retrieving the export

DO NOT use a browser to retrieve the export. You can test the external method with a browser if you like, but browsers tend to rewrite some elements in a way that will make the theme unusable (not XML valid, in particular)

To retrieve a page, call the external method with a tool like wget, from the directory that you have selected to store the theme. For the default theme and page:

wget -nH -p http://example.com/cpsskins_export

The CPSSkins page and theme negociaton applies. Therefore, to retrieve the 'Front' page of the default theme, you must execute:

wget -nH -p http://example.com/cpsskins_export?page=Front

For the "Foo" page of the "bar" theme, the call would be:

wget -nH -p http://example.com/cpsskins_export?theme=bar&page=Foo

The name of the directory from which you launch these commands should be equal to the targeted name for the theme within CPSDesignerThemes.

Correcting master html file names

With the examples above, the html pages that make your theme have been named cpsskins_export, or cpsskins_export?page=Front in your theme directory. Rename them according to the conventions of the them container you plan to use. With the default settings, that would be index.html and Front.html, respectively.

In situations where the exported portal isn't at the root of the host (for instance: http://localhost:8080/cps, or http://example.com/internal/portal), with the wget commands above, you'll find the exported pages deeper in the hierarchy. Namely, in './cps' or './internal/portal'. For simplicity and compatibility of theme negociation, you should move them to the top of your theme hierarchy, but don't move the exported resources around (you can do that latter, once the theme works).

Providing a proper extension to renderCSS

You have to find the renderCSS and rename it to renderCSS.css, and of course update the HTML files accordingly. Otherwise, this important stylesheet will be ignored by browsers.

Adding missing CSS resources

wget doesn't retrieve resources declared in CSS styles and stylesheets, such as:

So for example the cpsskins_common-css2.css as declared in the following code doesn't get retrieved:

<style type="text/css" media="all">@import url(/cps/cpsskins_common-css2.css);</style>

It isn't a problem with this directive per se, simply that wget will ignore it.

So in this part the task is to manually retrieve all those CSS resources and put them in your CPSDesignerThemes theme at the expected place. No need to modify the declaration.

A tool for automatic retrieval

You may use the script export_load_style_elements.py that you'll find in CPSDesignerThemes/bin.

Place yourself at the root of your theme directory on the client machine, and provide the base url of the host you retrieved the export from as a unique argument.

Whatever your virtual hosting conditions are, this url must be of the following form: <scheme>://<hostname>[:<port>]. No trailing slash, NO PATH, even if the portal sits at http://localhost:8080/cps or even http://example.com/foo/bar/mysite.

Checking and correcting URIs

The export process tries and rewrites URIs (for images, stylesheets) to remove the host part from them, since that would not make sense for the themes engine. Check that it got all of them, and correct the remaining ones, if any.

The correction is done with the cps:// URL scheme. This is a CPSDesignerThemes specificity that translates as the base portal URL at rendering time. You have to replace the base URL of your portal with cps://.

In case your portal is at http://example.com, you have to rewrite all URIs such as http://example.com/foo/bar/image.png like this:

cps://foo/bar/image.png

In case you portal is at http://example.com/cps, you have to rewrite http://example.com/cps/foo/bar/image.png as:

cps://foo/bar/image.png

In that example, assuming this image is purely static, you also have the possibility to download it, put it somewhere in the theme and issue a relative URI.

Caveats: Dynamic vs static

The cps:// URL scheme is also very useful to restore the dynamical behaviour of some resources.

This export process has simply saved what the page CPSSkins theme elements (Templets) would have produced in a normal rendering of the same context. This makes them essentially static.

An example that applies to the CPS 3.4 default theme: the Language Templet (country flags) has been rendered in the pages. Now, if you later on want to add a language to your CPS portal, the flags and switching links won't be updated, because they are now harcoded in your theme.

In this example, the easiest solution is of course to manually edit the theme pages to add new links, but some other Templets (Breadcrumb templet...) are much more problematic.

Most dynamical Templets have a counterpart Portlet, though. This duplication is due to the fact that CPSPortlets has been written some time after CPSSkins. You should replace very dynamic Templets (such as the Breadcrumb templet) with the corresponding Portlets in a slot, either before exporting (put a Portal Box Group Templet to define the new slot) or after exporting (cps:slot syntax).

In a more subtle way, it's part of CPSSkins' design to produce some dynamic CSS and JavaScript linked resources. These are called renderCSS and renderJS. Actually, only the latter is truly static.

Rewriting renderJS calls with the cps:// URL scheme must be done to prevent strange side effects.

Theme setting up

Finally, after you have successfully exported and corrected your theme, you can set up your new CPSDesignerThemes theme. This procedure is explained in the Theme Management specific documentation cf. themes_management.txt file.

Needless to say, it's a good idea to know how to do this before hand, so that you can check incrementally what happens during the export procedure.