Chapter 2. Usage
Prev     Next

Chapter 2. Usage

Table of Contents

1. Site Creation
1.1. Create Site Scratch
1.2. Create Site Layout
1.3. Create Site Pages
2. Site Content Management
2.1. Main Elements
2.2. Examples
3. Site Publishing
4. Advanced Features
4.1. Site Customization
4.2. XML Feed Integration
4.3. RDF Integration
4.4. Auto Sitemap Generation

This chapter contains step-by-step instructions for getting started with SilkPage. The following steps summarize the overall process of creating and publishing a Website using SilkPage.

  1. Section 1.1, “Create Site Scratch” Create a brand new site from scratch

  2. Section 1.2, “Create Site Layout” Structure your Website by organizing your XML content

  3. Section 1.3, “Create Site Pages” Create XML source pages and content

  4. Section 3, “Site Publishing” Publish your Website

  5. Section 4.1, “Site Customization” Customize your Website elements and appearance to fit your specific needs

1. Site Creation

A website is a collection of XML pages organized, for the purposes of navigation, into one or more hierarchies. That is the Website blueprint. This section describes the process of making a blueprint for your Website.

1.1. Create Site Scratch

To begin, you need to have your Website basic skeleton. To create the skeleton of your Website, you need to run the SilkPage with the scratch target. When running the SilkPage with the scratch target, you also need to provide a site.id as shown in Example 2.1, “Create Site Scratch”.

Example 2.1. Create Site Scratch

cd silkpage-VERSION

ant -f src/xml/build/tasks.xml -Dsite.id="coolsite" scratch

1.1.1. Scratch Website Directory Structure

This section gives an overview of your scratch Website directories that are generated by SilkPage using the scratch target. Assuming that coolsite has been provided as the value of the site.id, here is the directory structure that is generated by SilkPage.



                    [coolsite] - $SITE_HOME
                         |
          +--------------+-------------+------------+----------------+
          |              |             |            |                |
   build.properties   build.xml      [src]        [img]            [cfg]
                                       |                           catalog.xml
                      +----------------+----------------+        
                      |                |                |
                    [css]            [xml]            [xsl]
                    coolsite.css       |              config.xsl
                                     [en]             param.xsl
                                     index.xml        rdf.xsl
                                     about.xml
                                     layout.xml
                                     sitemap.xml
                                     glossary.xml
                                     contact.xml
                                     contact-send.php
                                     contact-sent.xml
                                     search.xml
                                     feeds.xml
                                     projects.xml
                                     docs.xml

Scratch Website Directories

$SITE_HOME

is the root directory of the generated directory structure. This directory is refered to as $SITE_HOME here after.

and your Website themes in terms of CSS and XSL stylesheets.

build.properties

Contains build properties of your Website such as your Website URL and your website themes in terms of CSS and XSL stylesheets.

build.xml

Contains build instructions used by Ant to build your Website. It contains the required targets that let you preview, publish and upload your Website.

src/

The root directory for your Website content where all source files are kept.

  • css/

    • siteid.css for your main Website CSS stylesheet to control your Website style.

  • xml/ The root directory for your Website XML content.

    • en/ The root directory for your Website XML content in English. Of course, you could translate your Website content in other languages. For example, to add the French translation, you need to translate your XML content in French and put it under the fr/ ditrctory.

      • index.xml your Website main index page.

      • layout.xml describes the layout and structure of your Website as well as your Website navigation.

      • sitemap.xml contains instructions to generate your Website sitemap based on the layout.xml.

      • glossary.xml contains a collection of your web site terms and brief descriptions or definitions of those terms. Once you refer to a term in your site content, SilkPage transforms it to an HTML acronym. For example to refere to XML as an acronym, you write acronym XML /acronym. Also see silkpage.acronyms.database.document configuration parameter.

      • search.xml, contact.xml, feeds.xml, etc. also exist in this directory, serving as webpage examples.

  • xsl/

    • config.xsl contains XSL based customization templates.

    • param.xsl contains XSL based configuration parameters.

    • rdf.xsl is used as a driver stylesheet to generate RDF metadata for each XML source.

cfg/

The directory for build configuration files

img/

The directory graphical images of the website

1.2. Create Site Layout

After generating the scratch version of your Website, you need to layout your Website and define your required structure. The site layout feature provides a mapping between the XML source files and the generated HTML files. The XML source files can be stored in multiple directories. Note that, the physical location of the XML source files do not reflect the site logical hierarchy. The dir attribute of the tocentry element can be used to create any set of directory structure for the HTML output. As shown in Section 1.1.1, “Scratch Website Directory Structure”, there is a scratch layout file (layout.xml) generated for your Website that can be used as the basis to define the structure of your Website.

1.2.1. Main Elements

  • layout: the root element of the site table of content.

  • config: optional elements specifying global configuration information for the whole site. A config element is defined by a pair of param and value. This is a global element. That is it applies to every page of the Website.

  • copyright: defines copyright information in the footer of each page. This is a global element. That is it applies to every page of the Website.

  • style: specifies a CSS stylesheet used by all HTML pages of the site. This is a global element. That is it applies to every page of the Website.

  • toc: the site layout top level element. It specifies the site home page.

  • tocentry: the hierarchy of tocentry elements in a toc describes the logical navigation hierarchy of the Website. Each entry must identify the XML document (containing a webpage) that it represents and may identify the directory and filename where the file will appear in the HTML Website.

    • page: attribute specifies the XML source file used to generate the corresponding HTML file.

    • filename: specifies the HTML output filename. If a filename is not specified, index.html will be used.

    • dir: specifies the output directory where the HTML output is generated. if dir is not specified, the files will appear in the currently inherited directory (or in the root, if no directory is specified anywhere in the tocentry ancestry).

  • notoc: pages identified with notoc elements instead of tocentry will be in the Website but will not appear in any hierarchy.

output-root

dir attribute can be specified using relative or absolute paths. If relative path is used, it's taken as relative to the dir value of any ancestor tocentry elements. However, if the absolute path is chosen, it's taken as relative to the output-root parameter whose value is set to "." by default.

1.2.2. Examples

Example 2.2. Site Layout



<!DOCTYPE layout PUBLIC "-//Norman Walsh//DTD Website Layout V2.4.0//EN"
"http://docbook.sourceforge.net/release/Website/2.4.0/schema/dtd/layout.dtd">
<layout>
<config param="footlink" value="sitemap" altval="Sitemap"/>
<config param="footlink" value="aboutContact" altval="Contact"/>
<config param="title" value="SilkPage"/>

<copyright>
<year>2004</year>
<holder role="aboutLicense">SilkPage</holder>
</copyright>

<headlink rel="icon" href="graphics/gif/silkpage_icon.gif" type="image/gif"/>
<style src="css/silkpage.css" type="text/css"/>

<toc page="index.xml" filename="index.html">
<tocentry page="about/index.xml" dir="about" filename="index.html">
<tocentry page="about/colophon.xml" filename="colophon.html"/>
<tocentry page="about/contact.xml" filename="contact.html"/>
</tocentry>
<tocentry page="docs/index.xml" dir="docs" filename="index.html"/>
<tocentry page="downloads/index.xml" dir="downloads" filename="index.html"/>
</toc>

<notoc page="sitemap.xml" filename="sitemap.html"/>
</layout>

The above layout.xml file, specifies seven pages for its Website. Using this layout file, the hierarchical structure of the Website is a main page index.html with three subordinate (about, docs and downloads) pages that are:



      
                                   [root_dir]
                                       |
          +--------------+-------------+---------------+---------------+
          |              |             |               |               |
      index.html     sitemap.xml    [about]          [docs]        [downloads]
                                    index.html       index.html    index.html
                                    colophon.html
                                    contact.html

  1. index.html generated from index.xml content.

  2. about/index.html generated from about/index.xml content.

  3. about/colophon.html generated from about/colophon.xml content.

  4. about/contact.html generated from about/contact.xml content.

  5. docs/index.html generated from docs/index.xml conent.

  6. downloads/index.html generated from downloads/index.xml conent.

  7. sitemap.html generated from sitemap.xml.

1.3. Create Site Pages

Once your Website structure and layout is defined, you need to create the corresponding pages in XML. That is your Website content. A SilkPage page is written using DocBook and Website elements. For each Web page there is a corresponding XML file. Each page consists primarily of three sections:

  1. Root: must start with webpage and followed by any optional config elements.

  2. Head: header information.

  3. Body: page content marked up with DocBook and Website elements.

1.3.1. Create the Page Head

1.3.1.1. Main Elements

  • webpage: specifies the page root element; its id must be unique in the scope of the site.

  • config: specifies metadata information in the generated HTML output.

  • head: contains the page head information:

    • title: specifies the title of the generated HTML page.

    • summary: used in the title attribute of the generated HTML page with the exception of the home page.

    • keyword: specifies metadata information for the page.

1.3.1.2. Examples

Example 2.3. Page Head


<?xml version="1.0">
<!DOCTYPE  webpage ...>
<webpage id="home">
  <config param="rcsdate" value="$Date: 2006/04/17 16:26:47 $"/>
  <head>
    <title>SilkPage</title>
    <summary>An XML based Publishing Framework for Web</summary>
    <keywords>Markup, web standards, W3C, XML, XSL, CSS, XHTML</keywords>
  </head>
</webpage>

In the above example, the header information of the SilkPage Website is specified as follows:

  • home is the unique identifier of the home page.

  • rcsdate specifies the last modification date of the page. The value of this parameter is set to $Date: 2006/04/17 16:26:47 $ that is a CVS substitution keyword. Using this approach, SilkPage generates the last modification timestamp of the home page at the bottom of the XHTML output page.

  • title specifies the page main title.

  • summary provides a short description for the SilkPage framework.

  • keyword provides some metadata information used by some search engines.

In addition to what's specified in the above example, SilkPage generates several other optional links in the XHTML output page as follows:

  • XML Source.  Links to the XML source of the page. The lable of this link can be changed by setting the value of the configuration parameter sources.xml.

  • RDF metadata.  Links to the RDF metadata of the page. The lable of this link can be changed by setting the value of the configuration parameter sources.rdf.

  • RSS Feed.  Links to the RSS feed of the page. The lable of this link can be changed by setting the value of the configuration parameter sources.rss10.

  • Atom Feed.  Links to the Atom feed(s) of the page. The lable of this link can be changed by setting the value of the configuration parameter sources.atom.

  • DOAP Source.  Links to the DOAP source, included in the XML source. The lable of this link can be changed by setting the value of the configuration parameter sources.doap.

  • URFM.  Links to the URFM file included in the XML source. The lable of this link can be changed by setting the value of the configuration parameter sources.urfm.

  • FOAF.  Links to the FOAF file included in the XML source. The lable of this link can be changed by setting the value of the configuration parameter sources.foaf.

1.3.2. Create the Page Body

1.3.2.1. Main Elements

The page content is marked up using DocBook Website elements defined in website.dtd. Refer to the online documentation of Simplified DocBook DTD for avilable elements and their syntax.

1.3.2.2. Examples

Example 2.4. Page Body


<?xml version="1.0">
<!DOCTYPE  webpage ...>
<webpage id="home">
  <config param="desc" value="The home index page"/>
  <config param="rcsdate" value="$Date: 2006/04/17 16:26:47 $"/>
  <head>
    <title>SilkPage</title>
    <summary>An XML based Publishing Framework for Web</summary>
    <keywords>Markup, web standards, W3C, XML, XSL, CSS, XHTML</keywords>
  </head>
  <para>
    SilkPage is an XML based Web publishing framework that has evolved from
    the Docbook Website. With strong foundations in XML, it is a publishing 
    framework with a focus on web standards and usability. 
    SilkPage provides a framework for publishing structured and standrad 
    compliant websites in XML. It is particularly suited to publish personal
    websites, though it is by no means limited to them.
  </para>
  <sidebar>
  <variablelist>
    <title>Key Features</title>
    <varlistentry>
      <term>Conent Management</term>
      <listitem>
        <para>
          XML based content management.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>WaSP Compliant</term>
      <listitem>
        <para>
           Web Standards (WaSP) compliant XHTML output in addition to XML and
           PDF outputs.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Content Feeds Support</term>
      <listitem>
        <para>
          Integrated XML and RSS feed generation.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Separate Presentation Model</term>
      <listitem>
        <para>
          Customization via XSL and CSS customization layers.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Cross Platform Support</term>
      <listitem>
        <para>
          Cross platform support via industry standards.
        </para>
      </listitem>
    </varlistentry>
  </variablelist>
  </sidebar>
</webpage>

In the above example the para element is used to describe the SilkPage framework briefly. In addition, the sidebar element is used to list the key features of the SilkPage framework.

Prev     Next
3.3. SilkPage Directory Structure  Home  2. Site Content Management