# -*- coding: utf-8; mode: structured-text  -*-

= Page Layout & Style Sheet Customization =

This section explains how the final web page presentation may be customized.
It is primarily targeted at web designers who want to create style sheets for
Wiking applications (including Wiking CMS), but it is also good to understand
the basic concepts when developing Wiking applications or Wiking CMS
extensions.

Index: @TOC@

== The HTML Code ==

The HTML code of the final page is always generated by the exporter
(implemented by `wiking.Exporter' class).  The exporter basically converts all
page contents from its inner abstract representation into HTML code and wraps
various bits of this content (heading, navigation menus, main content, panels,
language selection menu, footer etc.) into the final page.

The produced HTML code was fine tuned for accessibility, conformance to
standards and universality.  Customizing the HTML code itself is possible by
customizing the exporter, but this requires coding and is beyond the scope of
this section.  The default exporter, however, was carefully designed to produce
HTML code fully customizable through style sheets.


== The Default Style Sheet ==

Wiking comes with the default style sheet, which was designed with the
following goals:

  * Pages use the full width of the browser window, so the main content area is
    stretchable.
  * All colors are substituted from the color theme.
  * All sizes are proportional to allow user font size selection.
  * The final presentation is consistent across browsers.
  * The style sheets are valid CSS.
  * Browser specific hacks are avoided whenever possible.

  
== Top Level Page Structure == structure

 * div#*wrap* /class="node-id-<id> parent-node-id-<pid> lang-<iso-code>"/ --
   All content is wrapped in this div, the only direct descendant of HTML body
   element.  /<id>/ is replaced by the identifier of the current node
   (page). One or more of the /parent-node-id-<pid>/ classes are present if the
   current node is subordinate to other nodes and then /<pid>/ is the
   identifier of each parent node. /iso-code/ is the two-letter ISO 639-1 code
   of the primary language for the current node. This makes it possible to
   style the different pages, parts and language versions of the site
   differently.

   * div#*top* -- The top of the page usually containing logos and page title
     (see also [#logo]).

     * div#*top-layer1* -- Nested divs allow construction of logos from
       multiple aligned images through CSS backgrounds.

       * div#*top-layer2*

         * div#*top-layer3*

           * div#*site-title* -- Displays the configured site title and
             subtitle.

   * div#*page* /class="with-menu with-submenu with-panels"/ --
     The classes /with-menu/, /with-submenu/ and /with-panels/ are only present if the
     corresponding parts exist.

     * div#*links* -- Page navigation links for text browsers (hidden in visual
       browsers by default).

     * div#*breadcrumbs* -- Breadcrumb navigation bar (also hidden by default).

     * div#*language-selection* -- Language selection menu (absolutely
       positioned to the top in the default style).  See also
       [#language-selection].

     * div#*menu* -- Top level navigation menu (horizontal bar with folders in
       the default style).

     * div#*submenu* -- Hierarchical submenu of the current main menu item
       (floated to the left in the default style).

     * div#*panels* -- Column of panels (floated to the right in the default
       style).

       * div#*panel-<id>* class="*panel*" -- One div for each panel.  <id> is
         replaced by current panel identifier.

         * h3 -- Panel heading.

         * div class="*panel-content*" -- Panel content.

       * ... 

     * div#*main* -- Main page content.

       * div#*content* -- This div more or less just allows the clearing div
         below.

         * h1 -- Main heading (related to the current content).  The heading
           text is further wrapped in an anchor named *main-heading*.

         * The actual content specific for the current page follows.

       * div#*clearing* -- Empty final div to allow floating content clearing.
         The default style uses this to span the minimal height of the #main
         content area to the width of the vertical #submenu (floated on the
         left side).

     * div#*page-clearing* -- Empty final div to allow floating content
       clearing at the level of the #page div.

   * div#*bottom*

     * div#*bottom-bar*

     * div#*footer*

== Typical Customizations ==
   
=== Custom Logo === logo

Setting up a custom logo at the top of the page is one of the most typical
customizations.  The *#top* div contains nested sub-divs (see also
[#structure]), to allow composition of logos from several pieces.

An example below shows a 120px high logo with left and right fixed parts and a
flexible middle part which automatically spans according to the current width
of the browser window.  Of course, the middle part must be designed to allow
repetition.

-----
#top-layer1 {
    background-image: url(/img/logo-center.png);
    background-repeat: repeat-x;
    background-position: 200px top;
}
#top-layer2 {
    background-image: url(/img/logo-right.png);
    background-repeat: no-repeat;
    background-position: right top;
}
#top-layer3 {
    background-image: url(/img/logo-left.png);
    background-repeat: no-repeat;
    background-position: left top;
    height: 120px;
}
-----

Of course, this requires that the images can be accessed through given URLs.

This can be achieved by:
  a) uploading the images as page attachments in Wiking CMS,
  b) making the images available as wiking resources (see
     [config#resource_path]),
  c) configuring your web server to serve those images outside Wiking (as
     described in [apache#non-wiking-urls]),
  d) programming Wiking to serve them in your own Wiking application.

It is recommended to style the site title text to be drawn across the logo
(text can be enlarged, copied, accessed by users of assistive technologies,
etc...), but if you believe you need a fancy graphical logo text embedded in
your background images, you may not want the textual representation to be
visible.  See http://www.w3.org/TR/WCAG20-TECHS/C7.html for an example of an
acceptable technique.


=== Customizing Language Selection === language-selection

Language selection menu is composed of textual links by default.

There are two ways to use images (typically national flags) in the menu:

 * The configuration variable [config#language_selection_image
   language_selection_image] may be used to replace the textual links by images
   (with language names in alt tags).

 * The flags may be assigned to each link through CSS, since the links have the
   CSS class "lang-<code>", where code is replaced by the actual language code
   of the target language.  Make sure to assign a flag for each language code
   used in your application.

The menu is horizontal by default (the links follow each other on one line
separated by a "|" character).  The following example turns this menu into a
vertical list with flag images preceding the language title text.

-----
#language-selection a:link, #language-selection a:visited {
    display: block;
    padding-left: 20px; /* make space for the flag image */
    background-repeat: no-repeat;
    background-position: left center;
}
#language-selection .sep {
    display: none; /* hide the separator in the vertical layout */
}
#language-selection a.lang-cs { background-image: url(/img/flags/cs.gif); }
#language-selection a.lang-en { background-image: url(/img/flags/en.gif); }
#language-selection a.lang-es { background-image: url(/img/flags/es.gif); }
-----


== Styling Inner Content ==

Inner page content is the content specific for each page and is placed within
the #content div of the top level page structure.  This content is supplied by
the application, so it can be anything, but since most applications (including
Wiking CMS) use LCG for content generation, this content will often include
markup to support styling.  The following sections describe the supported
styling information for typical generic content elements.

=== Sections ===

Each LCG section is wrapped in an HTML =div= with =id= set to "section-<id>",
where /<id>/ is replaced by the actual section identifier.

When the content is composed as LCG Structured Text, the section identifier can
be set as:
-----
 == Section Title == xyz
-----
This section will be exported with =id= set to "section-xyz".

When the LCG content is constructed directly in the code, the identifier can be
passed to 'lcg.Section' constructor.

This technique has a wide range of use cases from specific styling of inner
content in specific sections to creation of absolutely positioned or floated
frames rendered separately from the main content flow.

=== Images ===

Specific styling of any image is possible thanks to LCG adding a =class=
attribute to each =img= tag corresponding to the file name of the image.  For
example an image refering to file "\/img/rose.png" will have the =class= set to
"rose" -- the name of the file without path and extension.
