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. h3: 1. Setup or copy your existing content as/to an ewok staging directory =#stage Na. Copy existing content to a suitable directory (optional but recommended) e.g. /home/http/stage/ Na. Add this new staging directory to your ewok.conf file in EWOK_HOME/conf/ewok.conf (or your apache conf directory). Copy and modify the example staging directory entry. Note that you only need an Alias directive if your directory is *outside* of the apache document root directory. Na. Modify Config.pm in EWOK_HOME/conf/Config.pm, adding the path to your staging directory to @EWOK_STAGE_DIRS. If you added an Alias to ewok.conf in the previous step, also add the alias name (not the full path e.g. 'stage') to @EWOK_TOP_DIRS_ADD. Na. Restart your apache and check that your new staging directory shows up in 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. h3: 2. Move look-and-feel elements of the site into ewok templates =#template Na. Create a templates directory at the top-level of your staging directory (e.g. /home/http/stage/templates), and check that this directory is included in EMBPERL_OBJECT_ADDPATH in the ewok.conf entry for this directory. Na. 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') Na. Choose a leaf 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') Na. Move constant presentation elements (stylesheets, headers, footers, etc.) from your content pages into the appropriate template component (see "How do templates work?":templates.html#how in deciding where elements should live) Na. 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). Na. 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. h3: 3. Setup site-specific metadata and use it in your templates where appropriate =#metadata Na. Copy the /ewok/metadata.map file to the top of your site tree and modify it there. See "Configuring metadata":config.html#metadata for details. Na. 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.