Daisy Wiki Sites

What is a Daisy Wiki "site"?

A Daisy Wiki site is a specific view on a Daisy Repository. A site is configured with a default collection (the concept of document collections is explained on the documents page). Full text searches and recent changes are automatically limited to only show documents from that default collection. New documents created via the site are by default assigned to that collection. Each site can have its own navigation tree, and is configured with a specific document as the homepage of the site.

A site is configured with a certain branch and language: for any document consulted via that site, the shown document variant will depend on that branch and language.

The Repository Server isn't aware of the concept of sites, nor does the site concept partition the repository in any way.

Defining sites

Sites are defined by creating a directory for the site and putting a siteconf.xml file in it. This directory should be created in the "sites" directory. By default, this sites directory is located at:

<wikidata directory>/sites

The location of this directory can be changed in the cocoon.xconf.

The content of the siteconf.xml file should strictly adhere to a certain schema (thus no extra elements/attributes are allowed), otherwise the site will be ignored (in that case, an error will be logged in Cocoon's log files).

siteconf.xml syntax

An example siteconf.xml is displayed below.

<siteconf xmlns="http://outerx.org/daisy/1.0#siteconf">
  <title>foobar</title>
  <description>The "foobar" site</description>
  <skin>default</skin>
  <navigationDocId>1-DSY</navigationDocId>
  <homepageDocId>2-DSY</homepageDocId>
  <!-- homepage>....</homepage -->
  <collectionId>1</collectionId>
  <!-- collectionName>myCollection</collectionName -->
  <contextualizedTree>false</contextualizedTree>
  <!-- navigationDepth>4</navigationDepth -->
  <branch>main</branch>
  <language>default</language>
  <!-- defaultReferenceLanguage>default</defaultReferenceLanguage -->
  <defaultDocumentType>SimpleDocument</defaultDocumentType>
  <publisherRequestSet>default</publisherRequestSet>
  <siteSwitching mode="all"/>
  <newVersionStateDefault>publish</newVersionStateDefault>
  <locking>
    <automatic lockType='pessimistic' defaultTime='15' autoExtend='true'/>
  </locking>
  <!--
  <documentTypeFilter>
    <include name="foo*"/>
    <exclude name="bar*"/>
  </documentTypeFilter>
  -->
</siteconf>

Element	Required	Description
title	yes	a (typically short) title for the site
description	yes	a description for the site, shown on the sites overview page
skin	yes	the skin to use for this site
navigationDocId	yes	the ID of the navigation document
homepageDocId	one of these	the ID of the homepage
homepage	one of these	a path to the homepage, used instead of the homepageDocId. Usually this is a path to a Wiki extension (`ext/something`)
collectionId	one of these	the ID of the default collection for the site
collectionName	one of these	the name of the default collection of the site. Will only be used when collectionId is not set.
contextualizedTree	yes	true or false. Indicates whether the navigation tree should be shown in full (= when false), or if the navigation tree should only have open branches leading to the selected node (= when true)
navigationDepth		always displays the first n levels of the navigation tree. When using this with contextualizedTree=true then the first n levels will always be shown no matter what and more may be shown as you progress through the navigation. When using contrextualizedTree=false then only the first n levels will be shown no matter at what place the current document happens to be in the navigation.
branch	no, default main	default branch for the site (specify either the branch ID or name)
language	no, default "default"	default language for the site (specify either the language ID or name)
defaultReferenceLanguage	no	default language for new documents (specify either the language ID or name)
defaultDocumentType	no	the default document type for this site. The document type can be specified either by ID or by name.
publisherRequestSet	no	which publisher request set to be used for the p:preparedDocuments publisher request for pages rendered in this site.
siteSwitching	no	defines if the browser should be redirected to another site if a document is better suited for display in another site. Valid values for the mode attribute are: stay (never switch to another site), all (consider all available sites as sites to switch to), selected (consider only selected sites, listed in <site> child elements inside the <siteSwitching> element). For more information see URL space management.
newVersionStateDefault	yes	publish or draft. This indicates the default state of the "Publish changes immediately" flag on the edit screen.
locking		the locking strategy to use. To use no locking at all, remove the <automatic> element (but leave the empty <locking> element). To use warn-locking, i.e. only warning that someone else is editing the page but still allowing concurrent edits, change the lockType attribute to "warn".
documentTypeFilter	no	allows to specify a filter for the document types that should be visible when creating a new document within this site. Zero or more include and/or exclude patterns can be specified, the order of the patterns is of no importance. Document types will be shown if they match at least one include pattern and no exclude pattern. If there are only exclude patterns, an implicit `<include name=""/>` is assumed. The patterns can be literal strings, or can contain the wildcards and ?. The wildcard * matches zero or more characters. The wildcard ? matches exactly one character. To match one or more characters, you can use ?. While document type names can't contain these characters, for completes we mention that the wildcards can be escaped using \ and \?, and backslash when used in this context can be escaped using \\ (thus \\* and \\?). Note that this feature is not an access control, it forbids nothing, it just filters the document type list when shown.

Creating a site

Again, all you need to do to define a new site is creating a new subdirectory in the sites directory and putting a valid siteconf.xml in it.

Removing a site

To make a site unavailable, you can:

remove its directory from the sites directory
rename its siteconf.xml to something else
make its siteconf.xml invalid (not recommended, just mentioning this for completeness as a reason a site may not appear)

Runtime detection of new/updated/deleted siteconf's

Changes to the sites configurations are automatically picked up, it is not needed to restart the Daisy Wiki. It can take up to 10 seconds before Daisy notices your changes (this interval is configurable in the cocoon.xconf). If you don't see a site appearing, check the cocoon log files for errors.

Site filtering

The list of sites displayed to the user is filtered based on whether the user has access to the homepage document of the site. In case a custom homepage path is used (<homepage> instead of <homepageDocId>), you can still specify the homepageDocId to cause filtering. If this is not done, the site will always be displayed in the list.

Creating a new site using daisy-wiki-add-site

If you want to create a new site, including a new collection, a new navigation tree and a new homepage document, you can use the daisy-wiki-add-site program for this, which will automatically perform these steps for you and put a new siteconf.xml in the sites directory. To do this, open a command prompt, make sure DAISY_HOME is set, go to DAISY_HOME/install and execute:

daisy-wiki-add-site <location of wikidata directory>

Other site-features

skinconf.xml

Maintaining a custom skin can be more work then you'd like to put into it, therefore it is also possible to customise (or parameterise) existing skins. For example, for the default skin you can alter the logo in this way.

This is done by putting a file called skinconf.xml in the appropriate site directory. The contents of this file will be merged in the XML pipelines and hence be available to the XSL stylesheets. The required content and format of this file depends upon what the skin you use expects.

If a site-specific skinconf.xml is not provided, the system will use the skinconf.xml found in the root of the sites directory, if it exists.

For more information on skinconf.xml, see here.

Extension sitemaps

See Daisy Wiki Extensions.

Comments (0)