Converting existing content to ewok

Guidelines

The following are some guidelines for converting an existing site to use ewok. Note that you don't have to do these all at once - an incremental approach works fine.

1. Setup your existing content as an ewok staging directory

1. Copy existing content to a suitable directory e.g. /var/www/ewoktest
2. Create a new ewok staging directory pointing to this directory on the ewok Administration page (/ewok/admin). You should define an alias to your directory (e.g. /ewoktest) if it is outside of the apache document root directory.
3. Restart your apache and check that your new staging directory shows up in the top level of the ewok file manager at http://your.domain.com/ewok.

Benefits: This lets you use the ewok file manager to maintain content, user permissions, etc., lets you use embedded perl within your pages, and (if you setup publishing) gives you separate staging and publishing areas. The default template distributed with ewok is empty, so your current look and feel should not be affected.

2. Move look-and-feel elements of the site into ewok templates

1. Create a 'templates' directory at the top-level of your staging directory (e.g. /var/www/ewoktest/templates).
2. Choose a template name (e.g. 'test') and create empty template components in your templates directory (e.g. 'style-test.epl', 'header-test.epl', 'footer-test.epl')
3. Choose a directory in your staging tree with a small number of files as your first conversion target - set the 'template' directory metadata item to your new template name (e.g. 'test')
4. Move constant presentation elements (stylesheets, headers, footers, etc.) from your content pages into the appropriate template component (see How do templates work? in deciding where elements should live)
5. Determining how to handle presentation elements that change can be a challenge. Some page-specific elements, like the initial <h1> and <h2> headings, are cached by ewok specifically for use in templates; some elements are derivable from the environment using Perl (e.g. breadcrumb trails from the SCRIPT_NAME environment variable); and some elements are directory-specific - like sidebar content - and are often best handled by creating a separate 'sidebar.epl' component and including it in the template ( [- Execute 'sidebar.epl' -] ). For elements that are genuinely page-specific and not-derivable you should probably to use site-specific metadata (see next section).
6. Also see the templates in /ewok/templates for examples of what can be done

Benefits: moving your site look-and-feel into templates allows centralised single-point maintenance, instant sitewide changes, fewer errors, and scope for easy experimentation with alternative designs.

3. Setup site-specific metadata and use it in your templates where appropriate

1. Copy the /ewok/metadata.map file to the top of your site tree and modify it there. See Configuring metadata for details.
2. Metadata can be accessed in your templates using the $req->{meta} hash. See the /ewok/templates directory for examples.

Benefits: As touched on above, site-specific metadata is really for page-specific or directory-specific items that are not derivable from the environment or the page content e.g. the page owner, page keywords and descriptions, page ordering information, etc. Moving these kinds of elements out of the content page into metadata simplifies their maintenance and reduces errors, particularly for less-technical users.