Naming conventions

Collection IDs can be any alphanumeric character and hyphen in the ASCII char set. That is, it should satisfy the following regular expression:

[a-zA-Z0-9-]+

It should be stressed that the ID can NOT contain an underscore character '_', neither can it contain spaces. The ID is only used internally for processing purposes, and does not need to resemble a real name. It is practical with a mnemonic ID, though. See existing IDs for examples.

Collection IDs are used in the following places in the file system or eXist collection structure (SD-terms used as example):

• in the document meta.xml in each dictionary or terminology collection in the eXist db — this is the principal location, and changes to the ID here should be reflected elsewhere. Example:

  <termmeta>
      ...
      <id>SD-terms</id>
      ...
  </termmeta>

• as the name of the xmldb collection in eXist containing the dictionary and terminology files. Example:

  /db/ordbase/terms/SD-terms/

• as the name of the folder containing XQuery, XSL and other files for processing content files of the collection with the corresponding ID. Example:

  risten/query/terms/SD-terms/
  
  risten/edit/terms/SD-terms/

• as part of CSS filenames for CSS files specific to a certain collection. Example:

  risten_edit_terms_SD-terms.css

The ID is used to tie these files and locations together.

asdløfj

asdf

The file naming convention for CSS files is:

risten.css
   risten_edit.css
      risten_edit_terms.css
         ...
   risten_query.css

Or generalised:

risten.css
   risten_MODULE.css
      risten_MODULE_COLLTYPE.css
         risten_MODULE_COLLTYPE_COLLID.css
            risten_MODULE_COLLTYPE_COLLID_XQUERYFILE.css

where

• MODULE is edit or query (the editing interface, or the regular end-user search interface)
• COLLTYPE is terms, dicts or classes
• COLLID is the collection ID for the collection being searched or edited
• XQUERYFILE is the filename of the XQuery targeted by the request (without the extension .xq)

As a concrete example, the following is a valid CSS file name according to the convention:

risten_edit_dicts_komi-JR_search-entries.css

It will be resolved to the following pathname:

risten/edit/dicts/komi-JR/css/risten_edit_dicts_komi-JR_search-entries.css

The CSS file contains styling rules specific to the XQuery search-entries.xq, and will import all styles above in the file hierarchy. Thus all styles defined in all CSS files along the path will be used, with rules in the more specific location overriding the more general ones.

It should be stressed that the import, and thus the whole inheritance functionality, does not happen by itself. The CSS file needs to include an @import directive as its first rule. This import statement should import the file just above it in the inheritance hierarchy, which will then import the next, and so on. See examples in the edit/dicts/komi-JR/ folder, and all css/ subfolders at each level in that path.

When importing a stylesheet, it is enough to reference the filename. Cocoon will resolve the filename to the proper location. Actually, specifying any other relative URL than the filename won't work.

Debugging CSS

For debugging and finetuning CSS, use the tool Xyle Scope, which is by far the most advanced CSS analysis, debugging and fine-tuning tool I've seen. The only drawback is that it doesn't yet support frames, which makes it a little cumbersome to work with the risten.no site. One has to open one frame at a time in a separate window.

We have two licenses for the application, more can be bought upon request.

The i18n and l10n features of Cocoon provides for a rich and flexible system of translating strings of text (and also for number formatting etc). In the present risten.no system, i18n is used for three different purposes:

file selection:

select a file corresponding to a locale (e.g. intro text at the front page)

string translation:

replace strings with other strings according to locale (all metatext, titles, etc in the search interface)

date formatting:

present a date-string in a proper format

Here we only consider string translation.

Translation files are placed in the translations/ subdir of every dir, and have the following name structure:

<filename>_<locale>.xml

where <locale> corresponds to the request locale the file is targeted at. The <filename> part is what we want a naming convention for.

The following scheme should be followed for organising the content of translation files:

• all common strings (or strings used by most collections/dictionaries) should be stored in the uppermost translation dir (risten/translations/)
• the strings should be put in as few files as possible, and the grouping of strings should done within the files (ie visually separating strings for the hitlist and strings for dictionary entries)
• edit vs. query-specific strings, as well as collection-specific strings should be placed in one file in the corresponding translations/ dir, and should be referenced with an explicit catalogue reference; the common translation file should be the default at all levels (but this can be changed in special cases, if it turns out to be more efficient)

The file naming convention is as follows (the translations/ dir is assumed and not shown for clarity):

risten/
       messages.xml   <---------------- main/common translation files
       SD-class.xml   <--------------- translations for the SD-class classification
       edit/
            messages.xml   <---------- translation overrides specific to the editors
            SD-terms/
                     messages.xml  <-- translation override for editing SD-terms
       query/
             messages.xml <----------- translation overrides specific
                                                     to the search mode

That is, the topmost translation files get names according to content, whereas the override translation files will be named just messages_LOCALE.xml, assuming that in most cases there is no need for more than one set of string translations in each location. Their content and function is clear from their position in the directory hierarchy. We'll just use the default name used by the Cocoon i18n examples.

What is important, is the ID assigned to each translation catalogue in the relevant sitemap, since this ID is the one used in the <i18n:text> elements to identify which translation to use. The ID is bound to a specific file, and this binding is done in the sitemap. Example:

<!-- Configure i18n transformer -->
<map:transformer name="i18n" logger="sitemap.transformer.i18n"
     src="org.apache.cocoon.transformation.I18nTransformer">
  <catalogues default="messages">
    <catalogue id="messages"   name="messages"    location="translations"/>
    <catalogue id="SD-class"   name="class-lbl"   location="../translations"/>
    <catalogue id="hitlist"    name="hitlist-lbl" location="../translations"/>
    <catalogue id="coll-long"  name="collections-long"  location="../translations"/>
    <catalogue id="coll-short" name="collections-short" location="../translations"/>
  </catalogues>
  <cache-at-startup>false</cache-at-startup>
</map:transformer>

The attributes of the <catalogue> element have the following meaning:

id

This is the id used to identify translations with a non-default catalogue (translation file) — the default is identified by an attribute on the parent element, see example above. That attribute holds the ID of the default catalogue.

name

The filename of the translations file, without the _LOCALE and .xml parts.

location

Path to the location of the file.