Configuring ewok

ewok admin area

As of version 0.5.0, ewok features a dedicated admin area, /ewok/admin/ where ewok configuration settings and site/directory mappings can be maintained. This area is initially only available to the 'admin' user, whose default password is 'ew0k'.

The "ewok Administration" page is divided into two sections, one for maintaining ewok site/directory configurations, and one for general ewok configuration settings.

ewok site/directory configuration

ewok sites are content directories that have their own set of templates, and therefore their own look and feel. Sites can be 'staging' areas, where you create content using dynamic page components, or 'publish' areas, where you publish staged content, typically as static or near-static html pages.

You will probably want to set up at least one staging and one publishing site to get started with ewok. If your actual hosted content is not going to be on the machine on which you have ewok installed it often makes sense just to have a single publish directory (e.g. 'publish') and use it for all your staging directories, and mirror from there. If you are hosting your content on the same machine as ewok, then you may want to set up your publish sites to be to your actual apache content directories.

New sites can be created using the "New site" button and providing a site label (an arbitrary unique site identifier) and the type of site (staging/publishing), and then the apache alias to use and the actual directory path for the site. Because apache aliases are used for each site, apache must be restarted to pick up a new site.

ewok publishing targets for staging directories

Staging directories need to be configured with a publishing 'target' to enable publishing. This is done via the Publishing 'new' link on the staging directory table entry. Each staging directory can have multiple targets, allowing the same content to be published to different endpoints, using different templates, etc.

Publishing targets are defined using the following fields:

• Label: an arbitrary label to distinguish targets. It's fine to use a staging directory label for the directories default target.
• Publish URL: this is the (possibly remote) URL to the top of the tree under which this directories content will be published. The path portion of the publish URL is used for link rewriting at publish time e.g. if your staging content is at /foo and your publish URL is http://www.foo.com/, ewok will rewrite all absolute /foo links to / ones i.e. /foo/xyz.html -> /xyz.html.
• Local Publish Directory: this is the local directory to which published content will be written
• Local Publish Alias (optional): if your published content is also available on the local webserver (perhaps via an ewok publish directory), then you can define the alias path to that content here. ewok uses this path to make the publish directory available from the ewok file manager, allowing some limited operations (primarily rename and delete) on published files.
• Template (optional): if this publishing target should use a different template than the staging directory, this can be specified here. This allows the same content to be repurposed for a different endpoint e.g. both intranet and extranet sites.
• Default target: if you define more than one target for a directory, you can define which target is to be the default target for publishing. Other targets then need to be selected explicitly.

ewok settings

ewok authentication

If you have a user repository you would like to use for ewok authentication (htpasswd file, LDAP directory, etc.), you can update the APACHE_AUTH variable to the apache directives required. You should probably also update the EWOK_ADMINS variable to usernames in your existing repository.

If you do not have an existing user repository, you can add users to the htpasswd.ewok user database in your apache config directory using the standard apache tools e.g.:

  # htpasswd htpasswd.ewok 
  New password: 
  Re-type new password: 

You should at a minimum change the password on the 'admin' user from the default.

Configuring metadata

Note: the metadata map format is likely to change in the near future. Be aware that you will probably have to redo any customisations you make in that event.

The metadata that can be set for various ewok entities (files, directories, etc.) is defined in the metadata.map file. This map is inherited in the same way as templates, so that for site-specific customisation it often makes sense to make a copy of the system-wide /ewok/metadata.map at the top of your site tree, and modify the copy.

To add your own metadata:

1. Open the appropriate metadata.map for editing. Metadata maps are made up of multiple entries corresponding to an object type (file, directory, user, etc.), with each entry containing definitions of the individual metadata items for that object type.
2. Locate the map entry you want to modify. Entries are either literals (ewok currently understands 'user', 'dir', and 'file') - or regular expressions on filenames. For files, ewok uses the map entry with the longest regular expression matching the current filename, and falls back to the 'file' entry if there are no matches.

   The map that ships with ewok has a regex entry of 'html?|xml', allowing additional metadata to be stored for HTML and XML files.

3. Add or remove metadata item definitions. Definitions can be commented out by using a '#' at the beginning of the line.

   Metadata item definitions have the following form:

           metadata_item => {
               datatype   =>    <datatype> ,
               fieldtype  =>    OPTIONAL|MANDATORY ,
               [priv      =>    <privilege> ,]
               [inherit   =>    0|1 ,]
               [omit      =>    0|1 ,]
               [hidden    =>    0|1 ,]
           },
   
   Attributes are defined as:
   
   datatype:
   
   
   BOOLEAN
   TEXT ('text' html field)
   TEXTLONG ('textarea' html field)
   PASSWORD ('password' html field)
   INTEGER
   FLOAT
   an enumerated list, defined as a text string enclosed in quotes 
   with entries separated by vertical bars (|) e.g. 'male | female' or 
   'under 20 | 20-30 | 31-40 | over 40'
   SYSTEM - metadata created and maintained by ewok itself (currently 
   'create_dtm' and 'creator')
   
   
   fieldtype: whether the field is optional or mandatory 
   (NOT YET IMPLEMENTED)
   privilege: (optional) the minimum user privilege level for whom
   the item should be visible/editable ('admin', 'templates', 'permissions',
   'publish', 'edit' - see The ewok user model)
   inherit: (directory metadata only) whether this item should be
   inherited by subdirectories
   omit: whether this field should be omitted from the default
   metadata listing, and shown only when the user chooses "Show all
   fields"
   hidden: specifies that this item should never be displayed
   (mostly useful with SYSTEM metadata)
    
   Save your changes. ewok should notice the changes immediately and
   reload its metadata maps.