image

WebsiteExpress Tutorial

A comprehensive introduction to the WSX website template
The present document is a tutorial introduction to the structure and features of the WebsiteExpress template, and it constitutes an integral part of the WebsiteExpress kit. The tutorial starts with presenting the basic concepts around which the WebsiteExpress template is designed, it continues with an incremental introduction to each of the features of the template, and ends with a detailed presentation of the individual steps required for creating a new website based on the WebsiteExpress template.

License

This document is copyrighted material, all rights reserved.

(c) Information Technology Group - www.itgroup.ro
(c) Virgil Mager

Permission is granted to copy, distribute and/or modify this document
under the terms of the
GNU Free Documentation License, Version 1.3
with no Invariant Sections, no Front-Cover Texts, no Back-Cover Texts

@toc@Table of Contents@

Getting started


The present tutorial, as well as the process of creating a new website based on the WSX template, both require downloading the WSX template on a computer and then opening the downloaded copy in a web browser on said computer; however, a number of modern browsers prevent the WSX template from operating properly, such that only a specific set of compatible browsers can be used for the development of a website based on the WSX template.

Specifically, the browser compatibility situation with the WSX template at the time of writing this document is as follows:

We will here-forth use the term 'WSX-compatible web browser' to designate a browser that is compatible with opening the WSX template locally on a computer and then using the template to create a new website.


What is the WSX template

The WebsiteExpress template, or simply 'WSX', is a small, fully-functional website which is meant to serve as a template for building new, full-fledged websites from the ground up. Throughout this tutorial we will refer to a website that is built based on the WSX template as a 'WSX-based website', or simply 'WSX website'.

From a website developer's perspective, the WSX template provides an easy and economical way of building, publishing, and maintaining a multi-lingual presentation-oriented website, specifically:

License

The WSX template is copyrighted software, @C@ Virgil Mager, @C@ Information Technology Group - www.itgroup.ro.
The WSX template is free software, released under the terms of the GNU General Public License, Version 2.

Obtaining the WSX template

The first step to obtaining the WSX template is to download the WebsiteExpress archive from here. For the sake of simplicity, let us consider that the archive file will be downloaded on the desktop, thus obtaining a zip file named 'wsx-*.*.*.zip' where *.*.* represents the version number (e.g. the archive file might be called 'wsx-0.9.2.zip').

Once the 'wsx-*.*.*.zip' archive has been downloaded on the desktop, the next step is to extract its contents using any available de-archiving method; for example, in Windows the archive file can be opened by double-clicking it, and then the 'WSX' folder can be dragged out from the archive window onto the desktop as illustrated in Fig.@count@images#wsx_extract@ below.

Fig.@count@images:wsx_extract@: Extracting the 'WSX' folder from the WSX archive on the desktop in Windows XP

The root folder of the WSX template

The 'WSX' folder extracted from the 'wsx-*.*.*.zip' archive (see Fig.@count@images#wsx_extract@ above) constitutes the 'root folder' of the WSX template, or the 'WSX root folder', and all the files and folders that are part of the WSX template are contained inside the 'WSX' root folder. The contents of the WSX root folder (after being extracted from the 'wsx-*.*.*.zip' archive and placed on the Desktop) is illustrated in Fig.@count@images#wsx_folder@ below:

Fig.@count@images:wsx_folder@: The contents of the 'WSX' root folder of the WSX template

The root file of the WSX template

The 'index.html' file contained inside the WSX root folder and illustrated on blue background in the right-hand side of Fig.@count@images#wsx_folder@ above is the 'root file' of the WSX template, or the 'WSX root file', and by opening the 'index.html' root file in a web browser the WSX template will be displayed in a browser window.
A snapshot of the WSX template as it is displayed in a Firefox 10 window is illustrated in Fig.@count@images#wsx_template_display@ below:
Fig.@count@images:wsx_template_display@: The WSX template website opened in a Firefox 10 browser on a local computer

A snapshot of the error message issued by the WSX template when opened in a Chrome browser is illustrated in Fig.@count@images#wsx_template_nodisplay@ below:
Fig.@count@images:wsx_template_nodisplay@: The WSX template website cannot be opened in a Chrome browser on the local file system

What is a WSX website

As it has been mentioned at the beginning of this tutorial, we'll use the terms 'WSX-based website', or simply 'WSX website', to refer to a website that is built based on the WSX template. While the detailed functionalities of, and the detailed procedure for creating, a WSX-based website will be presented in the following chapters of this tutorial, the following general characteristics hold true for any WSX-based website:
  1. from a functional perspective, a WSX-based website can be regarded as a browsable repository of content, with said content being made available in a web browser via a consistent visual interface that features a predetermined set of functionalities that are provided by the WSX template, e.g. a standardized multi-lingual content organization, a standardized set of browsing functions, a website-wide search function, etc
  2. the WSX template provides a predefined set of formatting options for the documents contained in a WSX website, such that all said documents can easily be authored and presented in a visually consistent way
  3. a WSX-based website consists exclusively of static content, i.e. the server on which a WSX website is hosted does not have to provide any server-side scripting, nor any form of data base management and/or code execution capabilities


Content organization on a WSX website


The language sections of a WSX website

The WSX template provides a framework for organizing the content of a WSX-based website into one or more 'language sections', where each such section should contain an autonomous version of the website authored in one given language; this is exemplified in Fig.@count@images#wsx_logical@ below:
Fig.@count@images:wsx_logical@: A WSX-based website is logically partitioned into autonomous language sections

The WSX documents

Most of the contents of a WSX-based website is meant to be published as [specially-crafted] HTML documents, with said documents logically residing in one of the website's language sections (depending on the language in which each document is authored). We will here-forth refer to the HTML documents contained in a WSX-based website as 'WSX documents'.
An example of how the WSX documents are logically organized into language sections is illustrated in Fig.@count@images#wsx_docs@ below:
Fig.@count@images:wsx_docs@: The WSX documents are logically clustered into language sections

Cover pages

A mandatory condition for each of the language sections of a WSX website is to be organized in such a way that one of its documents serves the role of a "entry page" for that language content: we will refer to these special-purpose documents as the 'WSX cover pages', or simply the 'cover pages', of the language sections of the website. The cover page document of a language section does not (have to) have any special structure, e.g. to be organized as a "main menu" containing links to the other pages in the website, etc; instead, the cover page of a language section only has an intended role of acting as a "welcome page" for the content published in that language, e.g. where a (brief) introduction to the website can be presented in the corresponding language.
The "logical position" of a WSX website's cover pages within the internal structure of a WSX website is illustrated in Fig.@count@images#wsx_cover_pages@ below:
Fig.@count@images:wsx_cover_pages@: Each language section must contain exactly one cover page

The WSX home page

The WSX template imposes a specific restriction as to which of its internal documents can be designated as the website's home page; specifically, the home page of a WSX website must always be one of the website's cover pages.
  • note: the concrete method for specifying the home page of a WSX website will be presented later in this tutorial

The WSX data files

Apart from containing WSX documents, a WSX-based website can also include other types of files which are not HTML documents, e.g. PDF files, zip archives, flash animations, stand-alone images, etc; we will here-forth refer to these files as the 'WSX data files', or simply the 'data files' contained in a WSX website. The most important characteristic that differentiates the WSX data files from the WSX documents is that a data file is not required to logically reside inside one of the language sections of a WSX website, i.e. the logical position of a data file within the internal structure of a WSX website can be either inside one of the language sections, or outside any-and-all of the language sections.

For example, consider the situation where a PDF document is authored in english and should thus be logically placed inside the english-language section of the website, while a ZIP archive file contains a collection of landscape images that are not related to any specific language and should thus be logically positioned outside all of the language sections of the website; this is illustrated in Fig.@count@images#wsx_data_files@ below:
 
Fig.@count@images:wsx_data_files@: The data files contained in a WSX website can logically reside both inside a language section, and outside all of the language sections
  • note: the presence of data files is not mandatory on a WSX website, e.g. a website may contain no data files at all, or it may contain data file(s) only in some of its language sections, etc


The user interface of a WSX website



The WSX display

We'll use the term 'WSX display' to refer to the visual representation of a WSX website in a web browser window. Specifically, the WSX documents contained in a WSX website are always displayed one document at a time in a browser window, with said document being displayed together with various other website components (e.g. navigation menus, emblems, controls, etc) as "embedded items" inside the WSX display; this is illustrated in the annotated screenshot in Fig.@count@images#wsx_display@ below, where the red-colored frame highlights the WSX display area:
Fig.@count@images:wsx_display@: The WSX display is the user interface of a WSX website

In other words, the WSX display acts as a "canvas" on which a WSX website's content is made available in a web browser window; the relationship between the content of a WSX website and the WSX display can be graphically illustrated as in Fig.@count@images#wsx_display_function@ below:
Fig.@count@images:wsx_display_function@: The WSX display is the "canvas" on which a WSX website's content is made accessible in a web browser winow

The layout elements of the WSX display

In order to simultaneously accommodate a WSX document together with various other website components as "embedded items" in a single browser window, the graphical layout of the WSX display is divided into several graphical parcels as illustrated in Fig.@count@images#wsx_layout@ below, with each of these parcels serving a specific role (e.g. the 'document viewer' parcel acts as a "viewport" through which a given WSX document is effectively displayed in the web browser, the 'page browser' parcel exposes a page navigation menu that controls which WSX document is displayed in the 'document viewer', etc); we will refer to these graphical parcels as the 'layout elements' of the WSX display.

The annotated screenshot in Fig.@count@images#wsx_layout@ below presents an overview of the layout elements of a typical WSX website:
Fig.@count@images:wsx_layout@: The layout elements of a typical WSX website's display

WSX states and selections

A very important notion that will be used throughout this tutorial is the 'WSX state': a WSX state "encapsulates" two correlated parameters which together describe the state of a WSX-based website at a given moment; specifically:
  1. we'll use the term 'selected document' to represent the WSX document that is being displayed on the WSX display at a given moment (i.e. inside the document viewer element)
  2. we'll use the term 'selected language' to represent the language section where the selected document resides (this should normally correspond to the language in which the selected document is written)
  • note: a WSX state will be occasionally be represented throughout this tutorial by using a curly braces notation: {selected_language, selected_document}; for example, the notation {English, Document#1} will represent the state of a WSX website when the selected language on the website is 'english', and the selected document is 'Document#1' of the english-language section of website.
The state of a WSX-based website at any given moment (i.e. the 'WSX state') can be identified on the WSX display in two special-purpose layout elements which always highlight the "currently" selected language and the "currently" selected document, namely the language selector element and the page browser element:
  • the language selector element displays the languages that are available on a WSX website, and highlights the "currently" selected language
  • the page browser element displays the documents that are available in the currently selected language, and highlights the document that is "currently" displayed in the document viewer
For example, Fig.@count@images#wsx_selected@ below illustrates the correspondence between a WSX state where the 'selected language' is 'English' and the 'selected document' is the [english-language] 'Welcome page' document, and the way this WSX state is "reflected" on the WSX display:
Fig.@count@images:wsx_selected@: The WSX state and the corresponding layout elements on the WSX display
  • note: the language selector element and the page browser element not only "reflect" the state of a WSX-based website at a given moment, but they can also be used to change the language selection on a WSX website and/or the document that is displayed on the WSX display, i.e. these layout elements also act as navigation elements on a WSX-based website; the functionality of these two elements will be detailed later in this tutorial.


The functional components of a WSX website


In terms of internal logical organization, a WSX-based website has a modular design consisting of a collection of autonomous 'functional components' that each serves a specific role, and each functional component logically resides either inside one of the language sections of the website, or outside any of the language sections; this is schematically illustrated in Fig.@count@images#wsx_internal_generic@ below:
Fig.@count@images:wsx_internal_generic@: The WSX functional components constitute the logical building blocks of a WSX website

The functionality of a WSX functional component is determined by its type, i.e. each WSX functional component is of a certain type, and there can be one or more functional components of a given type residing on a WSX website. For example, given the schematic illustration in Fig.@count@images#wsx_internal_generic@ above, two obvious types of WSX functional components are the WSX documents and the WSX data files, with each of these two types of functional components serving the role of "encapsulating" a certain kind of information (i.e. the WSX documents encapsulate an HTML document, and the WSX data files encapsulate various non-HTML data).

A key property that is common to (almost) all of the WSX functional components is that they can be "reflected" on the WSX display, thus providing a way for them to be accessed and/or "controlled" from within a browser window; specifically, each type of functional component has a dedicated layout element where it can be displayed on the WSX display, and each layout element can only "reflect" one given type of WSX functional component. For example, the WSX documents (which, as previously explained, are functional components on a WSX website) are always displayed inside the 'document viewer' element on the WSX display; this is illustrated in Fig.@count@images#wsx_reflection@ below:
Fig.@count@images:wsx_reflection@: Each WSX functional component has a corresponding "visual interface" on the WSX display, e.g. the visual interface of a WSX document is the 'document viewer' element

The following paragraphs in this chapter incrementally introduce all the individual functional components of a WSX-based website, and explain how, and in which conditions, these components are displayed inside the layout elements on the WSX display.

The WSX documents

As it was previously explained, the "logical position" of the WSX documents within the internal structure of a WSX website can be illustrated as in Fig.@count@images#wsx_docs2@ below:
Fig.@count@images:wsx_docs2@: The logical position of the WSX documents within the internal structure of a WSX website

The visual interface of a WSX document on the WSX display is the 'document viewer' element which, at any given moment, displays the document that is "currently" selected on the website.

For example, if at a given moment the selected language on a WSX website is 'english' and the selected document is the [english-language] 'Welcome page' document, then the 'Welcome page' document will be displayed inside the document viewer element on the WSX display; this is illustrated in Fig.@count@images#wsx_docs_display@ below:
Fig.@count@images:wsx_docs_display@: The selected document is displayed inside the document viewer element

The WSX data files

As it was previously explained, the "logical position" of the WSX data files within the internal structure of a WSX website can be illustrated as in Fig.@count@images#wsx_data_files2@ below:
Fig.@count@images:wsx_data_files2@: The logical position of the WSX data files within the internal structure of a WSX website


IMPORTANT: the WSX data files are an exception among the WSX functional components in terms of how they are displayed on a WSX website: specifically, whereas all the other functional components have a graphical representation on the WSX display, a data file is never displayed on the WSX display itself (as an embedded item); instead, when attempting to display a WSX data file, said data file is either displayed in a new browser window/tab if an appropriate plug-in is installed in the browser (e.g. a PDF reader plug-in will allow PDF files to be displayed by the browser in a new window/tab), or, if no appropriate plug-in is installed, then a "Save As..." pop-up dialog will be displayed by the browser allowing the data file to be saved on the computer (e.g. trying to open a ZIP archive will [typically] result in having the "Save As..." dialog displayed by the browser).

Fig.@count@images#wsx_data_file_open@ below illustrates the behavior of a WSX website when attempting to open a ZIP archive data file: specifically, the "Save As..." dialog is displayed by the web browser:
Fig.@count@images:wsx_data_file_open@: Attempting to open a ZIP archive will [typically] display the "Save As..." dialog

The page browser menus

A page browser menu is a functional component of a WSX website that is displayed inside the page browser layout element on the WSX display, and whose intended role is to provide the "table of contents" for the documents contained in a given language section of the website. In order to achieve this functionality, each language section of a WSX website has its own associated page browser menu component, which should list the documents contained in the corresponding language section.

The "logical position" of the page browser menus within the internal structure of a WSX website is illustrated in Fig.@count@images#wsx_page_browser@ below:
Fig.@count@images:wsx_page_browser@: Each language section has an associated page browser menu

Out of all the individual pager browser components (i.e. one page browser component for each language section of a WSX website) only one pager browser component is displayed on the WSX display at any given moment, namely the pager browser menu of the "currently" selected language.

For example, if at a given moment the selected language on a WSX website is 'English', then the page browser menu displayed on the WSX display will be the one associated with the english section of the website:
Fig.@count@images:wsx_page_browser_display@: The language selection determines which page browser menu is displayed


The page headers

A page header is a fuctional component of a WSX website that is displayed inside the page header layout element at the top of the WSX display, and it consists of a customizable image that may be either centered at the top of the WSX display or it may stretch on the entire width of the display.

In order to provide an increased level of flexibility, the page header image displayed at the top of the WSX display can be different depending on which language is selected on the website at a given moment; this feature is achieved by having a separate page header image for each language section of a WSX website.

The "logical position" of the page header functional components within the internal structure of a WSX website is illustrated in Fig.@count@images#wsx_page_headers@ below:
Fig.@count@images:wsx_page_headers@: Each language section of a WSX website has an associated page header

Out of all the individual page header components (i.e. one page header component for each language section of a WSX website) only one page header is displayed on the WSX display at any given moment, namely the page header of the "currently" selected language.

For example, if at a given moment the selected language in Fig.@count@images#wsx_page_headers_display@ below is 'English', then the page header component that is automatically displayed on the WSX display will be one associated with the english language section of the WSX website:
Fig.@count@images:wsx_page_headers_display@: The language selection determines which page header is displayed

The page footers

A page footer is a functional component of a WSX website that is displayed inside the page footer layout element at the bottom of the WSX display, and it consists of a (simple) customizable HTML page that can contain a combination of text, images, and/or links, possibly arranged inside a table.

In order to provide an increased level of flexibility, the page footer element on the WSX display can display a different content depending on which language is selected on the website at a given moment; this feature is achieved by having a separate page footer component for each language section of a WSX website.

The "logical position" of the page footers within the internal structure of a WSX website is illustrated in Fig. @count@images#wsx_page_footers@ below:
Fig.@count@images:wsx_page_footers@: Each language section of a WSX website has an associated page footer

Out of all the individual pager footer components (i.e. one page footer component for each language section of a WSX website) only one pager footeris displayed on the WSX display at any given moment, namely the pager footer of the "currently" selected language.

For example, if at a given moment the selected language in Fig.@count@images#wsx_page_footers_display@ below is 'English', then the pager footer component that is automatically displayed on the WSX display will be the one associated with the english language section of the WSX website:
Fig.@count@images:wsx_page_footers_display@: The language selection determines which page footer is displayed

The language selector

The language selector is a functional component of a WSX website that is displayed on the WSX display, and it provides a means to change the language selection on a WSX website.

The "logical position" of the language selector component within the internal structure of a WSX website is illustrated in Fig.@count@images#wsx_lang_selector@ below:
Fig.@count@images:wsx_lang_selector@: The logical position of the language selector within the internal structure of a WSX website

The visual interface (on the WSX display) for the language selector component is the language selector element, and at any given moment it highlights the "currently" selected language on the website.

For example, if at a given moment the selected language on the website is 'English', then the language selector displayed on the WSX display will highlight the 'English' item (i.e. the "currently" selected language):
Fig.@count@images:wsx_lang_selector_display@: The language selector is displayed inside the language selector element

The website icon

The website icon is a functional component of a WSX website that consists of an icon-sized image which is displayed in the URL bar of the web browser, and whose intended role is to serve as a quick visual identifier for the entire website.

The "logical position" of the website icon within the internal structure of a WSX website is illustrated in Fig.@count@images#wsx_icon@ below:
Fig.@count@images:wsx_icon@: The logical position of the website icon within the internal structure of a WSX website

The visual interface in a browser window for the website icon component is located in the browser's URL bar, as illustrated in Fig.@count@images#wsx_icon_display@ below.
Fig.@count@images:wsx_icon_display@: The website icon is displayed in the web browser's URL bar

The toolbox

The website toolbox is a functional component of a WSX website that allows the reader to perform various website-wide operations, e.g. to search through the WSX documents, to change the skin of the website, to print and/or save the selected document, etc.

The "logical position" of the website toolbox within the internal structure of a WSX website is illustrated in Fig.@count@images#wsx_toolbox@ below:
Fig.@count@images:wsx_toolbox@: The logical position of the toolbox component within the internal structure of a WSX website

The visual interface (on the WSX display) for the toolbox component is the toolbox layout element, as illustrated in Fig.@count@images#wsx_toolbox_display@ below:
Fig.@count@images:wsx_toolbox_display@: The toolbox component is displayed in the toolbox layout element on the WSX display

The full picture

The preceding paragraphs of this chapter have incrementally introduced the internal functional components of a WSX website, and explained how and when these components "get reflected" into the layout elements of the WSX display; a quick reference diagram of the internal structure of a generic three-language WSX website is summarized in Fig.@count@images#wsx_internal@ below:
Fig.@count@images:wsx_internal@: The complete diagram of the functional components of a WSX website



The file structure of a WSX website


The file structure of a generic WSX-based website is well illustrated by the file structure of the WSX template which, as it was briefly mentioned at the beginning of this tutorial, effectively consists of a small, fully functional website that has been specifically designed to illustrate (almost) all of the functionality that can be included in a WSX-based website. In this context, Fig.@count@images#wsx_template_internal@ below summarizes the functional components included in the WSX template, together with the way they are organized into the three language sections (namely english, french, and chinese):
Fig.@count@images:wsx_template_internal@: Overview of the functional components of the WSX template

The root folder

In terms of internal implementation, the entire file structure of a WSX-based website is contained inside the website's root folder which, in turn, is composed of two major groups of files and folders; specifically:
  1. a group of non-customizable files and folders that collectively reside directly inside the WSX root folder, and which together constitute the "backbone" of the website; this "backbone" group of files and folders is provided by the WSX template, and it must be part of (read: inherited by) any WSX-based website
  2. a group of customizable files and folders that represent the WSX template's functional components, and which all reside inside the 'wsx_content' sub-folder of the WSX root folder
For example, the correspondence between the logical organization and the top-level file structure of the WSX template is illustrated in Fig.@count@images#wsx_file_structure@ below:
Fig.@count@images:wsx_file_structure@: The file structure of the WSX root folder, partitioned into customizable and non-customizable content

The 'wsx_content' folder

The 'wsx_content' folder is the containing folder for all the content of a WSX-based website, and its file and sub-folder structure closely mirrors the logical organization of a WSX website.

An illustrative example of the correspondence between the logical organization and the file structure of a WSX-based website is offered by the WSX template, where:
  1. each language section of the WSX template is represented by a dedicated language sub-folder contained inside the 'wsx_content'  folder; this is illustrated in Fig.@count@images#wsx_template_langs@ below, where the 'en', 'fr', and 'cn' folders respectively represent the english, french, and chinese language sections:
    Fig.@count@images:wsx_template_langs@: Each language section is represented by a dedicated sub-folder inside the 'wsx_content' folder

  2. each WSX functional component that logically resides outside the WSX template's language sections is represented by a dedicated file placed directly inside the 'wsx_content' folder (i.e. outside any of the language sub-folders); this is illustrated in Fig.@count@images#wsx_template_external@ below where the website icon, the language selector, and the 'archive.zip' data file are each represented by a corresponding file inside the 'wsx_content' folder:
    Fig.@count@images:wsx_template_external@: Each functional component that is not part of a language section is represented by a dedicated file located inside the 'wsx_content' folder

  3. each WSX functional component that logically resides inside one of the WSX template's language sections is represented by a dedicated file placed inside the corresponding language sub-folder of the 'wsx_content' folder; this is exemplified in Fig.@count@images#wsx_template_internal_fr@ below which illustrates the file structure of the 'fr' french-lanaguge folder of the WSX template:
    Fig.@count@images:wsx_template_internal_fr@: Each functional component that is part of a given language section is represented by a dedicated file located inside the corresponding language folder

Apart from the file-structure characteristics described above, the WSX template also establishes several naming conventions for the constituent files and folders of a WSX-based website, specifically:
  1. all the files and folders that represent the various WSX functional components except the WSX documents and the WSX data files have predefined names (i.e. these names must be used on any WSX-based website) and they all start with an underscore '_' character; this naming convention can be observed in the diagrams above where e.g. the website icon file is named '_icon.png', the language selector file is named '_lang.htm', the footer file of the french language section is named '_footer.htm', etc
  2. all the WSX documents and WSX data files, as well as the language folders, can have arbitrarily names, but with the explicit restriction that the file extension of the WSX documents must be '.html' (note that although the '.html' and '.htm' file extensions both designate HTML file types, the file extension '.htm' is not allowed for the WSX documents)


The control elements of a WSX website



The WSX hyperlinks

We will use the term 'WSX hyperlinks' (or 'WSX links') to refer to any HTML hyperlink-like reference that is used throughout the file structure of a WSX-based website; specifically, WSX hyperlinks can appear inside WSX documents, and, as it will be shown later in this tutorial, inside the various WSX control files that together determine the behavior of a WSX website. The WSX hyperlinks form the basis for all the navigation functions of a WSX-based website, i.e. all the "clickable items" on a WSX-based website, whether they are contained in a WSX document, or in a page browser menu, or in a page footer, etc, are implemented as WSX hyperlinks.

Internet links

We will use the term 'Internet link' for any WSX link which references an address that is located on the internet. All internet links on a WSX website are always opened in a new browser window/tab.

In terms of syntax, an Internet link always starts with a protocol name, e.g. 'http:', or 'ftp:', etc

WSX local links

We will use the term 'WSX local links' for any WSX link which references a file that is part of the WSX website where the link resides; in this context, the WSX template defines two types of WSX local links, namely "WSX absolute links" and "WSX relative links"; these two types of WSX local links are presented in the following paragraphs.

WSX absolute links

As it has been previously explained, the entire content of a WSX-based website is contained inside the 'wsx_content' folder of the WSX website; in this context, a 'WSX absolute link' is a reference to a file that is part of a WSX website and which specifies the target file by means of its full path after the 'wsx_content' folder.

In terms of syntax, a WSX absolute link always starts with a '/' character.

For example, the link '/en/document.pdf' (without the quotes) placed in a WSX document that is part of the WSX template is a WSX absolute link that references the file 'document.pdf' contained in the english-language section of the WSX template, i.e. the full path of the file inside the WSX template's root folder is: 'wsx_content/en/document.pdf':

WSX relative links

The WSX relative links are references to files that are part of a WSX-based website and which use the standard notation for relative paths to files, e.g.:

For example, consider that a link should be placed in the english-language document 'en/doc1/doc1.html' of the WSX template such that it points to the french-language document 'fr/page1.html' of the WSX template; then, if using a WSX relative link, the link's sytnax should be: "../../fr/page1.html" (i.e. the leading '../' points to the 'en' folder, then '../../' points to the 'wsx_content' folder, then '../../fr' points to the 'fr' sub-folder of the 'wsx_content' folder, and finally '../../fr/page1.html' points to the intended document):


The behavior of the WSX local links

The WSX local links have a complex behavior, which is different from the typical behavior of an HTML hyperlink; specifically:


Example 1

The image in Fig.@count@images#wsx_links_corss_section@ below illustrates the WSX template and the logical position of a WSX local link which is located in the WSX template's french-language 'Page#2' and which points to the 'Welcome page' of the WSX template's english-language section (i.e. the WSX local link crosses the boundaries of the WSX template's language sections):

Fig.@count@images:wsx_links_corss_section@: Cross-language WSX local link
(from a french section document to an english section document)

Given the above, the way in which the link illustrated in Fig.@count@images#wsx_links_corss_section@ above is reflected on the WSX template's display, together with the effect of clicking this link, are illustrated in Fig.@count@images#wsx_links_corss_section_click@ below:

Fig.@count@images:wsx_links_corss_section_click@: Clicking a cross-language WSX local link displays the "target" document
and changes the language selection on the website

  • The green-text link to 'WELCOME PAGE (ENGLISH)' in the french language "Page #2" in Fig.@count@images#wsx_links_corss_section_click@ above is a WSX local link that "crosses the boundaries" of the WSX template's language sections; specifically, the link itself resides in french-language section's document 'Page #2', but it "points to" the english-language section's 'Welcome page' document
  • The effect of clicking the green-text link 'WELCOME PAGE (ENGLISH)' highlighted in Fig.@count@images#wsx_links_corss_section_click@ above is to both display the english-language "Welcome page' document inside the document viwer element, and also to change the WSX template's state from {French, Page #2} to {English, Welcome page} and update all the WSX display elements according to the new language selection

Example 2

The image in Fig.@count@images#wsx_links_same_section@ below illustrates the WSX template and the logical position of a WSX local link which is located on the WSX template's french-language page footer and which points to "Page #1" of the french-language section (i.e. the WSX local link is confined within the boundaries of the same language section of the WSX template):

Fig.@count@images:wsx_links_same_section@: Same-language WSX local link
(from the french section's page footer to a french section document)

Given the above, the way in which the link illustrated in Fig.@count@images#wsx_links_same_section@ above is reflected on the WSX template's display, together with the effect of clicking this link, are illustrated in Fig.@count@images#wsx_links_same_section_click@ below:

Fig.@count@images:wsx_links_same_section_click@: Clicking a same-language WSX local link displays the "target" document
and leaves the language selection unchanged

Example 3

Fig.@count@images#doc-not-in-menu@ below illustrates the behavior of a link to a WSX document which is not listed in the page browser menu and which is to be opened in the current window:
Fig.@count@images:doc-not-in-menu@: Clicking on a link to a WSX document which is not listed in the page browser menu will display said document on the entire width of the WSX display and the page browser menu will be hidden

The implementation of the language selector

As it was previously described, the language selector component is a functional component that provides a means to change the selected language on a WSX website. More specifically, the implementation of the language selector component contains a set of WSX local links which each point to one of the cover pages of the WSX website.

For example, the implementation of the language selector component on the WSX template contains a set of WSX local links to the cover pages of the WSX template; this is illustrated in Fig.@count@images#wsx_lang_selector_internal@ below:
Fig.@count@images:wsx_lang_selector_internal@: The language selector component of the WSX template
contains a set of WSX local links to the template's cover pages

Given the above, the action of clicking one of the items displayed in the language selector element on the WSX display actually translates in clicking one of the WSX local links that are part of the language selector component, which results in:
  1. "opening" the corresponding cover page document in the document viewer element, and
  2.  automatically updating the language selection on the website to the language of the newly-opened cover page
For example, Fig.@count@images#wsx_lang_selector_click@ below illustrates the situation where the eneglish language is initially selected on the WSX template and the english-language "Welcome page" document is displayed on the WSX display; then, the 'Français' item is clicked in the language selector, and as a result the WSX template's french-language section's cover page (namely, the WSX document "Page #1") gets displayed in the document viewer element, the fench language becomes the selected language, and all the other layout elements of the WSX display are automatically updated to "reflect" the contents of the french-language section (e.g. the page header is changed to the french-language section's page header image, the page browser menu will display the contents of the french-language section, etc):
Fig.@count@images:wsx_lang_selector_click@: Clicking the WSX template's language selector item 'Français' displays the WSX template's french-language cover page, and changes the language selection on the WSX template to 'french'
The role of the WSX cover pages
At this point in this presentation, the role of the WSX cover pages as "local home pages" for each language section of a WSX website should become evident: specifically, each time the language is changed by using the language selector element (i.e. by clicking on one of the language selector's links), the document that will be automatically "opened" on the WSX display (i.e. in the document viewer element) will always be the cover page of the newly-selected language section.
Fig.@count@images:wsx_lang_alt@: A language selector on the WSX template that would change the language in which the "currently" selected document is displayed is not feasible, because the WSX template's content is organized differently in each of the available languages

In conclusion, the choice to always display a language section's cover page whenever the language selection is changed on a WSX website provides a consistent behavior across the entire website, while minimizing the restrictions as to how the website's multi-lingual content has to be organized.

The implementation of the page browser menus

As it was previously described, a page browser menu component is a functional component of a WSX website that is intended to provide a "table of contents" for a given language section of the website. In terms of implementation, each page browser menu component contains of a collection of WSX local links that "point" to all, or part, of the documents contained in its corresponding language section.

For example, the WSX local links contained in the WSX template's english-language page browser menu can be illustrated as in Fig.@count@images#wsx_page_browser_internal@ below:
Fig.@count@images:wsx_page_browser_internal@: Each entry of the WSX template's page browser menus
consists of a WSX local link to a WSX document

Cross-language menu entries
Although the intended usage of a page browser menu is to contain links that point to documents in its corresponding language section, links to documents that belong to a different language section are also allowed.

For example, the WSX template's english-language menu entry "Page #3 in the French section" points to the french-language section document "Page #3"; this is illustrated in Fig.@count@images#wsx_page_browser_cross_section@ below:
Fig.@count@images:wsx_page_browser_cross_section@: The WSX local link "Page #3 in the French section", which is contained in the english-language page browser menu of the WSX template, points to the french-language document "Page #3"

As it was previously explained, if any WSX local link on a WSX website "crosses the boundary" of a language section, then clicking said link will not only display the "target" document inside the document viewer element, but also change the language selection on the website according to the language section where the link "points to"; thus, given the fact that the english-language section's page browser menu entry "Page #3 in the French section" points to the french-language section document "Page #3", the effect of clicking said menu entry is to both display the "Page #3" document in the document viewer element on the WSX display, and also to automatically change the language selection on the WSX template to french; this is illustrated in Fig.@count@images#wsx_page_browser_cross_section_click@ below:
Fig.@count@images:wsx_page_browser_cross_section_click@: Clicking the "Page #3 in the French section" cross-language entry in the WSX template's english-language section's page browser menu displays the french-lanuage section document "Page #3", and changes the language selection on the WSX template to french

Anchors

Standard HTML anchors (and references to anchors, i.e. #anchor) can be used inside WSX documents.


The WSX control files

As it has been previously explained, a WSX-based website can be regarded as a collection of functional components that each serves a specific role; in this context, the WSX control files determine the appearance and/or functionality of each individual functional component of a WSX-based website.

There are three important characteristics that together can help to easily identify the WSX control files within the file structure of a WSX website, namely:


General syntax of the HTML control files

In terms of internal syntax, an HTML control file consists of one or more sections enclosed in {} characters:

{section_data}
{section_data}
{section_data}
The data in each section is grouped into control items enclosed in () characters, with each such control item consisting of one or more control fields separated by a separator character:
{(control_field)
(control_field^control_field)
(control_field!control_field|control_field)
}
Additionally, a number of control items may be grouped into control blocks enclosed in [] characters:
{(control_field)
[(control_field|control_field)
(control_field)
(control_field|control_field|control_field)
]
}
Comment blocks are allowed anywhere between two control items, or between two sections, and they consist of an arbitrary string of text enclosed between two comment markers:
"*this is a comment between sections
and it spans over two lines*"
{(control_field)
(control_field|control_field) "*this is a omment between two control items*"
(control_field|control_field|control_field)
}

The following sections in this paragraph present each functional component included in the WSX template, and describe the details of how each WSX control file determines the functionality of its corresponding functional component.

IMPORTANT: understanding the role and syntax of each of the WSX control files included in the WSX template is critical to understanding the overall functioning of the WSX template, which in turn is the most important prerequisite for building a WSX-based website.

The website icon file

The website icon file of a WSX website is an image file with the predefined name '_icon.png' used to represent the website icon; specifically:

For example, the location of the WSX template's icon file '_icon.png' is illustrated in Fig.@count@images#ctrl_icon@ below:
Fig.@count@images:ctrl_icon@: The location of the '_icon.png' file

The home page selector file

The home page selector file of a WSX website specifies the website's home page, i.e. which WSX document will be displayed when the website is first opened in a browsing session, and:

For example, the home page selector of the WSX template specifies that the WSX template's home page is the english-language cover page "Welcome page"; the location of the WSX template's home page selector file '_startup.htm' is illustrated in Fig.@count@images#ctrl_startup@ below:
Fig.@count@images:ctrl_startup@: The location of the '_startup.htm' file

Syntax

The syntax of a WSX website's home page selector file is well illustrated by the WSX template's '_starup.htm' file (show in Fig.@count@images#ctrl_startup@ above), and it consists of a WSX absolute link to the website's home page (enclosed as a single section with a single control item); specifically:
{(/en/doc1/doc1.html)}
where the string "/en/doc1/doc1.html" is the WSX absolue link to the WSX template's home page (i.e. to the english-language document titled "Welcome page", which is also the cover page of the english-language section).

The webmaster notification file

The webmaster notification file is a standard HTML file that gets displayed in a web browser when a WSX website encounters certain kinds of configuration errors from which it cannot gracefully recover; the intended purpose of the webmaster notification file is to display the email address where the website's webmaster can be contacted in order to report the encountered problem.

The website notification file has the predefined name '_webmaster.htm' and, because a possible website misconfiguration is a website-wide problem, this file is located directly inside the 'wsx_content' folder.

For example, the location of the webmaster notification file '_webmaster.htm' of the WSX template is illustrated in Fig.@count@images#ctrl_wm@ below:

Fig.@count@images:ctrl_wm@: The location of the '_webmaster.htm' file


The language selector file

As it has been previously described, the language selector functional component provides a means for changing the "currently" selected language on a WSX website; specifically:

  1. the language selector component's representation is a single HTML file with the predefined name '_lang.htm', and it contains a set of references to the cover pages of each language section of the website
  2. because the language selector is a functional component that is unique to the entire website, the position of this file is directly inside the 'wsx_content' folder
For example, the location of the language selector file '_lang.htm' of the WSX template is illustrated in Fig.@count@images#ctrl_lang@ below:
Fig.@count@images:ctrl_lang@: The location of the '_lang.htm' file

Syntax

The syntax of the language selector file is well illustrated by the WSX template's '_lang.htm' file (shown in Fig.@count@images#ctrl_lang@ above); specifically:
1  {(WSX Template Website|a<bcde^fg^<hi>jkl~m)
2   (/en/doc1/doc1.html|English)
3   (/fr/page1.html|Français)
4   (/cn/custom_doc.html|chinese.png|Customized website title for the Chinese section)
5 }
where:

Hiding the language selector and/or the skin selector

For websites that are published in a single language (i.e. the website contains a single language section), the WSX website's internal mechanisms will hide the language selector menu if the '_lang.htm' file contains no references to any language section cover pages, and in this case the website will always be opened on its home page according to its home page selector file '_startup.htm'.

Similarly, if the skin options in the language selector file '_lang.htm' contains a single skin (with our without a modifier character) then the skin selector icon will not be displayed.

For example, by editing the WSX template's language selector file '_lang.htm' such as to eliminate all the references to the template's cover pages and leaving only one skin option, the language selector menu and the skin selector icon will no longer be displayed on the WSX display; this is illustrated below:
{(WSX Template Website|>a)}
 

Skin options

Several skin customization options can be specified for a WSX website without modifying the WSX template's internal skin definition files by placing a set of [one or more] cotrol characters in front of each skin letter in the language selector file, namely:
For example, the WSX template's skin options string "a<bcde^fg^<hi>jkl~m" specifies that for skins 'b' and 'h' the language selector menu will be placed on the left hand side of the website title bar, for skins 'f' and 'h' the page browser menu will use large fonts instead of the default small fonts, for skin 'j'  the page browser menu will be placed to the right of the document viewer element instead of the default left-hand side, and for skin 'm' the WSX display has a single-column layout with the page browser menu placed on top of the document viewer element. Fig.@count@images#right-side-menu@ below shows the effect of the control character '>' placed in front of the skin letter 'j' in the WSX template's language selector file:
Fig.@count@images:right-side-menu@: The page browser menu of skin '>j' is placed to the right of the document viewer

The page browser files

As it has been previously described, a page browser functional component provides a means for accessing the documents that are included in a given language section of a WSX website; specifically:
  1. each language section contains its own page browser component
  2. each page browser component's representation is a single file with the predefined name '_menu.htm', and it contains a set of references to the documents contained in its corresponding language section
  3. because each page browser component is specific to one language section of a WSX website, the individual '_menu.htm' files (each representing the page browser component of one of the website's language sections) are located in their corresponding language section sub-folder
For example, in the case of the WSX template, the position of the english-language page browser file '_menu.htm' within the file structure of the WSX template is illustrated in Fig.@count@images#ctrl_browser@ below:
Fig.@count@images:ctrl_browser@: The location of the english-language '_menu.htm' file

Syntax

The syntax of a page browser file is well illustrated by the WSX template's english-language page browser file '_menu.htm' (shown in Fig.@count@images#ctrl_browser@ above); specifically:
  1. the file starts with a multi-line comment block (enclosed in "*...*" delimiters) intended as a handy reminder of a page browser file's syntax
    • note: as it was previously explained, the horizontal lines inside the page browser file do not have any functional role, and they are only meant to graphically separate the file sections

  2. the next section in the page browser specifies the content of the WSX template's Help pop-up (the Help pop-up is displayed by clicking the Help icon in the WSX toolbox):
    • the Help pop-up text is grouped as a single control item (i.e. all the text contained in this section is enclosed in a single group of () characters)
      • in the specific case of the english-language page browser file of the WSX template, the Help pop-up section contains a description of the available toolbox controls
    • the | delimiter character inside the Help pop-up text is displayed as line breaks in the Help pop-up
    • if the Help pop-up section of a page browser file is omitted, then the Help icon in the WSX toolbox is not displayed when the corresponding language is the "currently" selected language on the website (i.e. there will be no Help pop-up icon for a language section who's page browser file does not contain a Help pop-up section)
      • for example, on the WSX template website only the english-language page browser file contains a Help pop-up section, and thus the Help icon will be displayed in the website toolbox only when the the english language is selected

  3. the remaining sections in the page browser file represent the successive page browser menu sections that are displayed by the english-language page browser menu:
The first section that refers to the page browser menu within the WSX template's english-language page browser menu (i.e. the first section after the Help pop-up section in the english-language section's 'menu.htm' file) has been specifically designed to illustrate the most commonly used syntactical elements in a page browser file; specifically:
 1  {(Pages)
2   (doc1/doc1.html|Welcome page)
3   (doc5/doc5.html|Special characters|Right-click this link and select 'Open
in new window' to see the HTML codes for
the special characters [offline mode only])
4   (doc7/doc7.html|Embedded objects|The objects embedded in a page may consist
of images, videos, music players, etc)
5 [(doc2/doc2.html|Chapter|A chapter can group pages, folders, or other chapters)
6 (doc3/doc3.html|Chapter page)
7 @[(doc8/doc8.html|Sub-chapter|Sub-chapter with automatically-linked pages)
8 (doc8/doc8-1.html|Sub-chapter page 1)
9 (doc8/doc8-2.html|Sub-chapter page 2)
10 ]
11 ]
12   [(|Folder|A folder can group pages, chapters, or other folders)
13      (doc4/doc4.html|Folder item)
14   ]
15 }
Listing @count@listings:page_browser_section@: A typical section inside a page browser file

The above listing translates in the following layout for the first menu section displayed in the english-language page browser element (i.e. when the english language is selected on the WSX template):
Fig.@count@images:english_section_menu@: The first section of the english-language page browser

Following is a one-by-one description of the various syntactical elements present in Listing @count@listings#page_browser_section@ above:
  1. the first control item (listed in the first line in Listing @count@listings#page_browser_section@ above) contains a single control field (namely the string "Pages"), and it determines the title of the page browser menu section as it is displayed in the page browser menu (i.e. "Pages" in Fig.@count@images#english_section_menu@ above)
    (Pages)
  2. the second control item (listed in the second line in Listing @count@listings#page_browser_section@ above) represents a reference to the WSX template's english-language page titled "Welcome page", and it contains two control fields:
    (doc1/doc1.html|Welcome page)
    • the first control field is the string "doc1/doc1.html", which is a WSX relative link to the 'doc1.html' file contained in the 'doc1' sub-folder of the english-language section folder (this document is the english-language page titled "Welcome page")
    • the second control field is the string "Welcome page", which is the page title as it is displayed in the page browser menu (in this specific case, the page title displayed in the page browser menu has been chosen the same as the title shown on the page itself, i.e. "Welcome page")
  3. the third control item in Listing @count@listings#page_browser_section@ above represents a reference to the english-language page titled "Special characters", and it contains three control fields:
    (doc5/doc5.html|Special characters|Right-click this link and select 'Open
    in new window' to see the HTML codes for
    the special characters [offline mode only])
    • the first control field is the string "doc5/doc5.html" which is a WSX relative link to the 'doc5.htm' file contained in the 'doc5' sub-folder of the english-language section folder (this document  is the english-language page titled "Special characters showcase")
    • the second control field is the string "Special characters" which is the page title as it is displayed in the page browser menu (as it can be seen when clicking this link on the WSX template, the page title displayed in the page browser menu "Special characters" is different from the title shown on the page itself which is "Special characters showcase")
    • the third control field is the string "Right-click this link and select 'Open in new window' to see the HTML codes for the special characters [offline mode only]", and it represents the tooltip that appears when holding the mouse pointer over the link in the page browser menu:

      • IMPORTANT: tooltips are not allowed to contain the characters '(' and ')' because the ')' character is reserved as the end-of-tooltip delimiter

  4. the fourth control item in Listing @count@listings#page_browser_section@ above contains a reference to the english-language page titled "Embedded objects", and its syntax is identical to the third control item described above (i.e. it contains a WSX relative link to the 'doc7/doc7.html' document, followed by the link title to be displayed in the page browser menu i.e. "Embedded objects", and followed by the page browser menu tooltip "The objects embedded in a page may consist of images, videos, music players, etc")
    (doc7/doc7.html|Embedded objects|The objects embedded in a page may consist
    of images, videos, music players, etc)
  5. the following lines numbered 5...11 in Listing @count@listings#page_browser_section@ above contain two nested control blocks:
     5  [(doc2/doc2.html|Chapter|A chapter can group pages, folders, or other chapters)
    6 (doc3/doc3.html|Chapter page)
    7 @[(doc8/doc8.html|Sub-chapter|Sub-chapter with automatically-linked pages)
    8 (doc8/doc8-1.html|Sub-chapter page 1)
    9 (doc8/doc8-2.html|Sub-chapter page 2)
    10 ]
    11 ]
    The purpose of a control block appearing inside a page browser file is to group together several logically related pages into a 'collection', where:
    • each collection consists of one or more pages, with the first page being the collection's "cover page", while the remaining pages being consider to reside "inside" the collection
    • from a syntax point of view, the first control item of a control block specifies the collection's "cover page" (e.g. the cover page of the control block in the listing above is the document 'doc2/doc2.html' specified in line 5), while the remaining items inside the control block specify the pages that are contained "inside" the collection

    As it can be seen in the listing above, a collection of items can contain not only individual pages (i.e. the 'doc3/doc3.html' page in line 6 above), but also other collections (i.e. lines 7...10 above), such that a hierarchy of collections can be created in a page browser menu as illustrated below:
    Fig.@count@images:collections@: Hierarchy of collections in the page browser menu

    Following is a detailed description of each item in the listing above:

    • as it was previously mentioned, the listing above specifies a hierarchy of two nested collections, with the control block in lines 5...11 representing the "top-level" collection, and the control block in lines 7...10 representing an "inner collection" contained inside the top-level collection

    • the first control item in line 5 in the listing above represents the collection's "cover page"; this page will be listed as "Chapter" in the page browser menu:
      (doc2/doc2.html|Chapter|A chapter can group pages, folders, or other chapters)
    • the next control item in line 6 in the listing above represents the first page contained inside the collection, and it will be listed as "Chapter page" in the page browser menu:
      (doc3/doc3.html|Chapter page)
    • the control block in lines 7...10 in the listing above specifies a collection of items grouped as a "sub-collection" contained inside the higher-level collection described above; this sub-collection will be shown in the page browser menu as a hierarchy of documents contained inside the hierarchy of its container collection:
      @[(doc8/doc8.html|Sub-chapter|Sub-chapter with automatically-linked pages)
      (doc8/doc8-1.html|Sub-chapter page 1)
      (doc8/doc8-2.html|Sub-chapter page 2)
      ]
      • this sub-collection's "cover page" is the document 'doc8/doc8.html' which is listed as "Sub-chapter" in the page browser menu
      • the pages contained in this sub-collection are the documents 'doc8/doc8-1.html' and 'doc8/doc8-2.html', listed as "Sub-chapter page 1" and "Sub-chapter page 2" in the page browser menu

    • a character '@' preceding a control block (as is the case with the sub-chapter listed above) specifies that all successive pages that appear inside that control block are automatically linked with each other by having at the end of said pages a link to the previous and/or next page contained in the control block:
      Fig.@count@images:booklet_page@: Pages in a sub-chapter with automatic previous/next links

      • a sub-collection hierarchy (i.e. a collection-in-collection-in-collection-etc structure) can only have one of the (sub-)collection preceded by a '@' character, and all the pages contained inside that (sub-)collection (i.e. including the pages contained in sub-sub-collections etc) are then linked with each other via previous/next links
      • each of the previous/next link displayed at the bottom of an automatically-linked page takes its title either from the linked page's title as displayed in the page browser menu (this is the case of the bottom-right link titled "Sub-chapter page 2" in Fig.@count@images#booklet_page@ above), or from the linked page's tooltip text if such a tooltip exists in the page browser file (this is the case of the bottom-left link titled "Sub-chapter with automatically-linked pages" in Fig.@count@images#booklet_page@ above)
  6. finally, the last control block spanning lines 12...14 in Listing @count@listings#page_browser_section@ above illustrates the syntax of a coverless collection:

    12     [(|Folder|A folder can group pages, chapters, or other folders)
    13      (doc4/doc4.html|Folder item)
    14   ]

    A coverless collection is similar to a "normal" collection (described in the previous paragraph), with the one difference that the control item that specifies the cover page of a coverless collection (i.e. line 12 above) does not contain a reference to any document; in other words, the control item that specifies the cover page of a coverless collection in line 12 above contains a page title for the collection as it will appear in the page browser menu (namely "Folder"), but clicking on the "Folder" title in the page browser menu will not display any page on the website.

Advanced options

The english-language page browser menu file '_menu.htm' of the WSX template contains, in its last section, a reference to [a local copy of] this WSX tutorial, which illustrates some additional configuration options that can be used throughout the page browser menu; specifically:
1   {(Tutorial|/info_icon.png|/wsx_logo.jpg)
2   (wsx_tutorial/wsx_tutorial.html^WSX Tutorial|The latest version of the
WebsiteExpress tutorial is
available at www.itgroup.ro)
3 }
The syntax of the menu section listed above determines that:
Specifically, the following differences can be observed in the listing above when compared to the general syntax described in the previous chapter, namely:
  1. the control item in the first line (which determines the section title to be displayed in the page browser menu) contains, apart from the section title string (i.e. "Tutorial"), a set of two WSX absolute links to two files, namely:
    • the first file reference '/info_icon.png' determines a "custom" icon to be displayed instead of the default icon next to the section title (i.e. the blue "i" icon)
    • the second file reference (i.e. '/wsx_logo.jpg') determines a "custom" page header image that will be displayed instead of the english language section's default page header at the top of the WSX website's display each time a page from this section will be displayed (i.e. in this specific case the WSX tutorial page, as this is the only page that is part of the "Tutorial" section)
      • note 1: WSX relative links are allowed for referencing the two above-mentioned files (i.e. there is no restriction on using the WSX-relative or WSX-absolute format of links)
      • note 2: in order to have a custom page header for a menu section's pages but no custom icon for the page browser menu section, then an empty string will have to be used for the custom icon file, e.g. one could specify the 'wsx_logo.jpg' custom page header without a custom icon usiong the following syntax for the section title:
        (Tutorial||/wsx_logo.jpg)
        similarly, one can specify a custom icon for a page browser menu section without specifying a custom page header by simply omitting the page header file:
        (Tutorial|/info_icon.png)
  2. the control item in the second line in the listing above specifies the [only] page contained in this section, namely the "WSX Tutorial" document that is included as part of the WSX template; as it can be seen, the control fields that specify the reference to the WSX tutorial documents and respectively the title to be displayed in the page browser menu are separated by a '^' character (instead of '|'): this indicates that this link will open the corresponding document in a new browser tab/window.
    • note: a WSX document that opens in a new tab/window from the page browser menu is displayed as a stand-alone document (i.e. the page browser menu is not displayed in the new tab/window where the document is opened)


The page header files

The page header files are image files with the predefined name '_header.jpg', and they are used to represent the page header functional components of each of the language sections of a WSX website; specifically:


The page footer files

The page footer files are HTML files with the predefined name '_footer.htm', and they are used to represent the page footer functional components of each of the language sections of a WSX website; specifically:



Creating and maintaining a WSX website



The process of creating and maintaining a WSX website essentially involves the following main aspects:
The following paragraphs in this chapter detail each of the aspects mentioned above.

Choosing a well-behaved HTML editor

All the HTML files that are part of a WSX-based website, (i.e. the website's WSX documents and WSX control files) share the common characteristic that they are each based on a specific file template which is provided as part of the WSX template kit; then, the process of creating a new WSX document or a new WSX control file consists of importing the corresponding file template in an HTML editor, editing the contents of the template file, and then saving the resulting file as a new WSX document or WSX control file.

Given the above, and for the scope of this tutorial, we will use the term "well-behaved HTML editor" for any HTML editor which does not automatically insert/delete/modify any HTML tags when it opens an HTML file for editing (e.g. <!DOCTYPE>, <META>, <STYLE>, etc), and which supports the HTML 4.01 Strict DTD or the HTML 5 specification. Any HTML editor which makes automatic (read: unsolicited) changes to the internal structure of the HTML file that it edits may, or may not, produce WSX template-compatible HTML files.
At the time of writing this document, the current versions of the SeaMonkey integrated HTML editor, and the derived KompoZer HTML editor, are both "well-behaved" HTML editors, and they both can be used to create and/or edit the HTML files of a WSX-based website.

Creating the skeleton file structure of a new WSX website

The recommended method for creating the skeleton files-and-folders structure for a new WSX-based consists of the following steps:

  1. one shall start with creating the root folder for the new WSX website, and give said root folder an appropriate name; for the purpose of this tutorial we shall create the new website's root folder on the Desktop, and we shall name it 'MyNewWebsite':

  2. the next step after creating the root folder of the new website is to copy all the files and folders contained in the root folder of the WSX template, except the 'wsx_content' folder, into the root folder of the new website (i.e. into the 'MyNewWebsite' folder):

  3. next, create the 'wsx_content' folder inside the new website's root folder:

  4. the last step in creating the basic folder structure of the new website is to create the language folders inside the website's 'wsx_content' folder. For the purpose of this tutorial we shall consider that the new WSX website ''MyNewWebsite' will be published in english and italian, and thus we shall create two language folders named 'en' and 'it' inside the 'wsx_content' folder:

  5. finally, the new website can now be fitted with the various mandatory WSX control files, namely the website-wide control files that must reside directly inside the 'wsx_content' folder (i.e. '_startup.htm', '_lang.htm', '_icon.png', '_webmaster.htm', '_sitemap.bat') and the language-specific control files that must reside inside each of the language folders of the website (i.e. '_menu.htm', '_header.jpg', '_footer.htm'); in order to assist this process, a template version of the above-mentioned control files has been included in the WSX template inside a dedicated folder 'file_templates', which is further divided into two sub-folders:
    • the 'WSX_ROOT_FOLDER/file_templates/wsx_content_templates' sub-folder contains a template version of the website-wide control files; these files have to be copied directly in the 'wsx_content' folder of the new website
    • the 'WSX_ROOT_FOLDER/file_templates/lang_templates' sub-folder contains a template version of the language-specific control files; these files have to be copied in each of the language folders of the new website:

    • note: the control file '_sitemap.bat' has not yet been introduced in this tutorial; its functionality is detailed later in this chapter

At this point, the general framework for a new WSX website has been created (i.e. the language folders and the website control files are now in place), and the process of including/editing the actual content can now be started; this is detailed in the next chapter.

Creating the WSX content

The process of creating the content of a WSX website essentially consists of:

The file structure of a WSX document

As it has been mentioned earlier in this tutorial, a WSX document is a specially-crafted HTML document, and its file structure is similar to that of any standard HTML document. Specifically, a WSX document consists of a mandatory 'skeleton file' of type '.html' which contains the document "body" (i.e. the document text together with any other native HTML elements such as push-buttons, forms, drop-down lists, etc), plus a number of optional 'embedded objects' (e.g. images, movie clips, <IFRAME>s, etc) which are each represented by a separate file; this is illustrated in Fig.@count@images#typical_wsx_document@ below:
Fig.@count@images:typical_wsx_document@: The file structure of a typical WSX document consists of a mandatory 'skeleton file' of type '.html', plus a number of optional 'embedded elements' that are each stored in a separate file

An illustrative example for the file structure of a typical WSX document is represented by the 'Page #3' document contained in the french-language section of the WSX template (see the annotated Fig.@count@images#wsx_document_compact2@ below), where:
Fig.@count@images:wsx_document_compact2@: The correspondence between the file structure and the layout of a WSX document

  • note: as it can be seen in Fig.@count@images#wsx_document_compact2@ above, the three files that together define the 'Page #3' french language document (i.e. the 'page3.html' skeleton file and the 'french_flag.jpg' and 'holding_the_sun.jpg' image files) are all placed together directly inside the french-language 'fr' sub-folder of the WSX template, and this "clustering together" of all the file components of a WSX document inside a laguage sub-folder is the simplest way of including a WSX document inside a language section of a WSX website. In other words, in order to include a WSX document inside a language section of a WSX website, the corresponding document's entire file structure can simply be placed inside the desired language sub-folder

Organizing the WSX documents' file components

The "clustered" file structure of a WSX document as presented in the above paragraph (i.e. where all the document's component files are contained directly inside a language folder) is not a strict requirement for having a WSX document logically reside inside a given language section; instead, a WSX document will be considered to logically reside inside a given language section of a WSX website if the document's HTML skeleton file is included directly, or indirectly (read: inside a sub-folder), in the corresponding language section folder. Apart from this condition, the files that represent the various embedded objects contained in a WSX document (e.g. embedded images, embedded videos, embedded <IFRAME>s, etc) can be spread anywhere inside the 'wsx_content' folder (including any of its sub-folders, or sub-sub-folders, etc) without restrictions.

An illustrative example of a "spread" WSX document file structure is represented by the 'Embedded objects' page contained in the english-language section of the WSX template, which is depicted in the annotated Fig.@count@images#doc7@ below:
Fig.@count@images:doc7@: The file structure of the english-section page titled "Embedded objects"

The individual elements of the english-language "Embedded objects" page can be identified as follows (see Fig.@count@images#doc7@ above):

Alternatively, an illustrative example of how multiple WSX documents' skeleton files can be placed together inside a single sub-folder of a language folder is represented by the 'doc8.html', 'doc8-1.html', and 'doc8-2.html' skeleton files, which are all contained inside the 'doc8' sub-folder of the english-language folder 'en' of the WSX template (these documents are listed under the "Sub-chapter" heading in the english-language page browser); this is illustrated in the annotated Fig.@count@images#docs-in-subfolder@ below:

Fig.@count@images:docs-in-subfolder@: Multiple WSX documents' skeleton files can be arbitrarily grouped in sub-folders

Creating a WSX document

As it has been described in "The file structure of a WSX document" paragraph above, a WSX document is a specially crafted HTML document, and, like any standard HTML document, it consists of an HTML skeleton file plus a number of [optional] embedded objects which are each represented by a separate file. In this context, the process of creating a WSX document consists of creating a working copy of, and then editing, the template document "wsx_document.html" found in the "WSX_ROOT_FOLDER/file_templates/document_templates" folder of the WSX template; namely:
A WSX document, while being a standard HTML document with respect to its file structure, imposes some restrictions, and provides some extra features, as compared to a standard HTML document; these restrictions and extra features are discussed in the following paragraphs in this chapter.

The document header

The WSX document template "wsx_document.html" found in the "WSX_ROOT_FOLDER/file_templates/document_templates" folder of the WSX template contins a pre-formatted document header which must be used as the basis for all the WSX documents on a WSX website.
The document header of the "wsx_document.html" document, as it is displayed in the KompoZer HTML editor, is illustrated in Fig.@count@images#doc_header@ below:
Fig.@count@images:doc_header@: the document header included in the "wsx_document.html" document

As it can be seen in Fig.@count@images#doc_header@ above, the document header contains three editable fields, namely the document title, the document subtitile, and the document icon, all contained inside a specially-formatted table and followed by a horizontal line. In this context, the process of customizing the document header of a WSX document must be limited strictly to editing the contents of each field, without making any modifications to any of the HTML properties of document's header table (e.g. the number of rows, the size of each table cell, the size of the table, etc, should not be altered in any way).

Basic formatting

The following formatting options can be used inside [the skeleton file of] a WSX document:

Headings

Like any HTML document, a WSX document can contain HTML headings, namely Heading-1 (<H1>) to Heading-5 (<H5>). The Heading-6 (<H6>) has a special role and it is intended to create a frame border around block elements, and in particular around images.
Headings can be inserted in the document via the appropriate HTML editor command, and their styling is predefined by the WSX template in order to give a consistent look to the entire WSX-based website.

Automatic table of contents

A WSX document can contain an automatic table of contents which will automatically collect, and indent, all the headings H1 to H5 which follow the position of the table of contents in the document. This table of contents will be displayed only when the document is displayed on the WSX display, i.e. the automatic table of contents will not be shown in the HTML editor during the process of editing the document.
The automatic table of contents is inserted in the WSX document by placing the following unformatted text on a separate line:

\@toc@<title_of_table_of_contents>@

where <title_of_table_of_contents> will be the title displayed at the top of the table of contents.
Imporant: the table of contents can be inserted anywhere, but only once (i.e. only in one place), inside a WSX document.

Automatic counters

In order to ease the authoring of a WSX document, the WSX template includes a mechanism which can provide automatic numbering of categories of items (e.g. a category of items in a document can be images, another category can be tables, yet another category can be notes, etc). By using the automatic counters mechanism, a WSX document can be edited and new items can be added and/or removed anywhere in the document, at any time, and the WSX internal mechanism will ensure that the items in the document are properly numbered (i.e. in sequence, from the first item to the last in each category) when the document is displayed on the WSX display.
Creating a new counted item
The following text string in a WSX document creates a new counted item in a category:

\@count@<category_name>:<item_name>@

where <category_name> is the category in which the item will be included, and <item_name> is a symbolic name given to the item.
If a new item is declared as part of a category, then:
Important: an item name cannot be re-defined inside the same category, but the same name can be used to represent different items when it is declared separately in different categories (e.g. the text strings \@count@images:relativity@ and \@count@references:relativity@, both placed inside the same WSX document, create two distinct and unrelated items, each with its own numbering, and the two numbers can be the same or different).
Referencing a counted item
A counted item (that has been created as described in the paragraph above) can be referenced (i.e. used) anywhere inside a WSX document, both before and after the position where it has been created in the document; specifically, the following text string can be used inside a WSX document to reference a counted item, and this string will be automatically replaced with the numeric value of the counted item when the document is displayed on the WSX display:

\@count@<category_name>#<item_name>@
Example:
Document view in the HTML editor
Document view on the WSX display
The image in Fig.\@count@img#hie_menu@ below illustrates a hierarchical menu:
Fig.\@count@img:hie_menu@: a hierarchical menu on a WSX website
The image in Fig.@count@img#hie_menu@ below illustrates a hierarchical menu:
Fig.@count@img:hie_menu@: a hierarchical menu on a WSX website

Special characters and control strings

The WSX template allows a WSX document to contain several control strings which get automatically translated into special characters when the document is displayed on the WSX display; specifically, each control string has the form \@<control_code>@, where the valid \@<control_code>@ strings are listed below (e.g. \@<<@, \@>>@, \@L@, etc):

Document view in the HTML editor
Document view on the WSX display
\@<<@ Left/right Quotes \@>>@
23\@L@ \@|@ 35\@E@ \@|@ $50 \@|@ 5000\@Y@
\@C@ Copyright symbol
\@R@ Registered trademark symbol
\@TM@ Trademark symbol
Section \@S@1
Note \@+@1
Ref \@++@1
Current year is \@year@
Current time is \@gmt@
\@.@ 10\@u@F \@+-@10%, i.e. 9\@u@F \@:@ 11\@u@F
\@#@ Version 1.0 \@B@2
\@~@(\@...@)

@<<@ Left/right Quotes @>>@
23@L@ @|@ 35@E@ @|@ $50 @|@ 5000@Y@
@C@ Copyright symbol
@R@ Registered trademark symbol
@TM@ Trademark symbol
Section @S@1
Note @+@1
Ref @++@1
Current year is @year@
Current time is @gmt@
@.@ 10@u@F @+-@10%, i.e. 9@u@F @:@ 11@u@F
@#@ Version 1.0 @B@2
@~@(@...@)

Caveats

TODO

Creating a WSX data file

The process of creating a WSX data file does not involve any special procedure specific to a WSX-based website; instead, the WSX data files are created with the appropriate tools according to the type of data (e.g. an image editor for image data files, or an archive manager for archive data files, etc), and the resulting data file must then be integrated (read: placed and linked) inside the file structure of the WSX website.

Creating the WSX control files

As it has been previously explained earlier in this document, the WSX control files determine the functionality and/or the appearance of the functional components of a WSX website, and all the WSX control files of a new WSX website are created as part of the process of creating the skeleton file structure of the website. Then, once the WSX control files have been created (read: cloned from the WSX template), each control file has to be edited and customized according the actual content of the new website.

Creating the site index for search engines

A WSX-based website makes heavy use of Ajax technologies for displaying its web pages, and said Ajax technologies hide the page addresses under complex JavaScript functions; in this context, a WSX website should contain a special stie map file which may be useful, or even necessary, for the search engines to properly index the entire content of the website.
In order to automate the creation of a search engines-friendly site index, a WSX website provides two script files named "_sitemap.bat" (for use on windows systems) and "_sitemap.run" (for use on linux-based systems), where said two script files can be found inside the "wsx_content" folder of any WSX website after the website's skeleton file structure is created. The result of running [any of] said two scripts is a file named "sitemap.htm" which will be generated inside the website's root folder, whereby the resulting "sitemap.htm" file contains a complete listing of all the WSX documents that are contained in the website (i.e. all the HTML files that have the extension ".html").

Maintaining a WSX website

The maintenance of a WSX website can be thought of as consisting of two types of actions, namely maintaining the website content (i.e. maintaining the WSX documents and/or the WSX data files), and maintaining the website integrity (i.e. keeping the website's WSX control files correctly synchronized with [any changes that are made to] the website content); these two types of actions are discussed in the following two paragraphs.

Maintaining the website content

The maintenance of a WSX website content (i.e. the website's WSX documents and WSX data files) involves the same procedures and precautions as for a typical static website, i.e. it consists of adding, moving, removing, renaming, and/or editing, the WSX documents and/or the WSX data files, and updating the hyperlinks contained in the WSX documents (i.e. the WSX hyperlinks to WSX documents and WSX data files, and the file paths of any embedded objects that are part of the WSX documents' file structure) following any changes that are made to the position, and/or to the names, of the website files.

Maintaining the website integrity

As it has been previously explained, the WSX control files contain information about the visual appearance and/or functionality of the functional components of a WSX website; in particular, the HTML-type WSX control files (with the file extension '.htm') [may] contain WSX hyperlinks to various files and/or folders on the website, and thus the content of the WSX control files has to be maintained according to the desired functionality of the website, and, additionally, all the WSX control files have to be kept synchronized with the file structure of the website after any change is made to the website's file structure.

Advanced options

TODO


Publishing a WSX website


The WSX template has been specifically designed such that a WSX-based website can be easily deployable on even the most simple, and often free, webhosting plans, by reducing the requirements on the webhosting server to the bare minimum of providing a simple HTTP web server, without requiring any of the more advanced assisting technologies such as server-side scripting or data bases. In this context, the process of publishing a WSX-based website consists solely of uploading the contents of the website's root folder to the webhosting server, with no server configuration being required.

Publishing multiple websites in the same webhosting account

It is possible to publish multiple WSX-based websites into a single webhosting account by uploading the entire root folder of each website (i.e. including the root folders themselves instead of the content of the root folders) into said webhosting account (the root folders of each website must have different names such that they can coexist inside the same user account folder)


Appendix


The KompoZer HTML editor

Hacking

The site skins

The WSX skins are each contained in a separate sub-folder of the "WSX_ROOT_FOLDER/skins" folder, where each such sub-folder must have a single-letter name. In terms of internal structure, each skin consists of three customizable layers which are overlaid on top of each other, namely:

  1. the window background layer (bottom layer)
  2. the page border layer (middle layer)
  3. the WSX display styling layer (front layer)
For example, the overlaid layout of the three layers of skin 'i' shipped with the WSX-2.0 template is illustrated in Fig.@count@images#wsx_skin_layers@ below:
Fig.@count@images:wsx_skin_layers@: the layout of the WSX-2.0 template's skin 'i' layers

The follwing paragraphs present the structure and customization options available for each of these layers.

The window background layer

The windows background layer is defined by a single background image which is tiled over the entire area of the browser window (i.e. the CSS style is "background-repeat: repeat-x repeat-y"). If the background image is smaller than 1024 pixels then the background image is scrolled on the Y direction together with the window contents, else the background image is held still when the window is scrolled.

The window background image of each skin is the file "background-outer.jpg" found inside each skin sub-folder.

The page border styling layer

As its name suggests, the page border styling layer mainly defines the shape (and colors) of the page border on a WSX website. The page borders are defined via a set of PNG images, with one such set of images found inside each skin sub-folder.

Fig.@count@images#wsx_skin_boders@ below illustrates the component images which together define the page border for skin 'i' of the WSX-2.0 template:

Fig.@count@images:wsx_skin_boders@: the page border components of skin 'i' of the WSX-2.0 template
Following is a detailed description of each of the components illustrated and labeled in Fig.@count@images#wsx_skin_boders@ above:
  1. the area surrounded by a dotted blue line and labeled "page box" contains the full content of the page; this is the area whose border is skinned by the page border layer

  2. the area surrounded by a dotted blue line and labeled "control box" consists of a row of text and icons which contain the language selector element and the toolbox element

  3. all component images "XXX.png" except "lang-bottom.png" are page-bordering images which have an "interior-facing" area that neighbors the page content and an "exterior-facing" area that neighbors the window background: the interior-facing side of a page-bordering image defines the color, and possibly a pattern, for the web page's border, and the exterior-facing area should be transparent such that it allows the window background layer to be visible around the web page borders
  4. as a general rule, the area of each page border image that must be covered by the border drawing/pattern (as opposed to the transparent area of each image) should be placed oriented towards the center of the web page, with the special note that, when applying this rule to the control box border images (see Fig.@count@images#wsx_skin_boders@ above), the control box must be thought of as being placed at the center-top of the web page; this is illustrated in Fig.@count@images#border-attraction@ below:
    Fig.@count@images:border-attraction@: the border layer images must have their border drawing/patern area oriented towards the center of the web page

    • for example, the border drawing of the "lang-bottom-left.png" image covers the bottom side, bottom-right corner, and right side of the image; similarly, the border drawing/pattern of the "right.png" image covers the left side of the image; the border drawing/pattern for these two border images of the WSX-2.0 template's skin 'i' (see Fig.@count@images#wsx_skin_boders@ above) are illustrated below:
      lang-bottom-left.png
      right.png



  5. the border drawing/pattern in each pair of adjacent images must "flow" from one image to the other such that said border drawings/patterns match at the junction between two adjacent images
    • for example, the design of the border images "left.png", bottom-left.png", and "bottom.png" of the WSX-2.0 template's skin 'i' is illustrated below:


  6. as a general rule, the dimensions of the images comprising the page border layer should be chosen just large enough to hold the [non-transparent] drawing/pattern of each image, with the following exceptions:

    • if a border image has a repetitive drawing/pattern along one direction, and the repeating pattern is relatively short, then the pattern should be repeated inside that image such that the image size along its repetitive direction is about 100 pixels
      • for example, the pattern of "top.png" included in skin 'i' of the WSX-2.0 template's is a 1 pixel-wide repetitive pattern, and thus the "top.png" image should contain the pattern repeated 100 times along its width; this is illustrated below:


    • the width of the transparent areas of the "left.png" and "right.png" images, and the height of the transparent area of the"bottom.png" image, determine the minimum margin that will always be preserved between the border drawing/pattern of a web page and the border of the web browser window on the left, bottom, and right side of the web page, i.e. if a web page is larger, on any dimension, than the display area of the browser window, then the browser window's scrollbar(s) will be displayed, the web page will be scrollable inside the browser window (on one or both directions), and between each of the web page's margins and the browser window there will be a distance as determined by the transparent areas of the above-mentioned page border images
      • for example, the [minimum] distance between the bottom-right corner of a web page and the bottom-right corner of the browser window is defined by the border images "bottom.png" and "right.png"; this is illustrated below:

    • the height of the "lang-bottom.png" image determines the vertical spacing between the top margin of the page header image and the bottom margin of the control box row (see Fig.@count@images#wsx_skin_boders@ above); this is illustrated below:

    • as it can be seen in Fig.@count@images#wsx_skin_boders@ above, the "lang-top-left.png" and "lang-bottom-left.png" images, and respectively the "lang-top-right.png" and "lang-bottom-right.png" images, are stacked on top of each other, and the border drawing/pattern areas must "flow" vertically inside each pair of stacked images. In this context, the dimensions of the "lang-top-left.png", "lang-bottom-left.png", "lang-top-right.png", and "lang-bottom-right.png" images must be chosen as follows:
      • the width of the "lang-top-left.png" and "lang-bottom-left.png" images on one hand, and respectively the width of the "lang-top-right.png" and "lang-bottom-right.png" images on the other hand, must the same for each pair of stacked images, and said widths must be exactly the total width required to hold the width of the compound border drawing/pattern area for each pair of stacked images:
      • the height of the "lang-top-left.png" and "lang-top-right.png" images must be the same, and it determines the distance between the top margin of the control box and the top margin of the browser window, i.e. they determine the height of the background area that will be visible at the top of the web page when the web page si scrolled all the way to the top:
      • the "lang-bottom-left.png" and "lang-bottom-right.png" images have a special design, namely they can be thought of as consisting of two zones on the vertical axis:
        • a bottom zone whose drawing/pattern must make the junction with the "top.png" image on one hand (on the-left hand side and respectively the right-hand side of the control box), and with the "lang-top-left.png" and respectively "lang-top-right.png" images on the other hand (at the top of the images), and
        • a top zone which must have a repetitive vertical pattern about 100 pixel-tall, which repeats the top-most line of the bottom zone: the purpose of the top zone is to allow a continuous adjustment of the control box border (on the vertical axis) if the user selects a larger font size in the browser (selecting larger fonts in the browser will translate in having taller fonts in the language selector, which, in turn, will translate in a taller control box)
        Fig.@count@images:lang-bottom-left-felx@: the design of "lang-bottom-left.png" of the WSX-2.0 template's skin 'i', and how "lang-top-left.png" glides over it depending on the height of the control box
The presentation in this paragraph, up to this point, illustrated the geometry and design of the border images that define the page border styling layer for skin 'i' of the WSX-2.0 template; the choice for presenting the WSX-2.0 skin 'i' was made because this skin is a good illustration for a rather complex design that [the top part of] the page border can have. However, simpler designs are possible, and they involve much simpler geometries for the images that define [the top part of] the page border skin;

The WSX display styling layer

The styling of WSX display is defined separately for each skin by a set of files located in each skin sub-folder of the skin folder "WSX_ROOT_FOLDER/skins", as follows:
  1. a set of styling image files: "menu-width.png", "page-width-and-header-underline.png", and "background-inner.png"; and
  2. a CSS text file: "skin.css"


The styling images

Fig.@count@images#skin-b-style-img@ and Fig.@count@images#skin-k-style-img@ below illustrate the WSX-2.0 template's skins 'b' and 'k', annotated with the position and size of the WSX display styling images (enumerated above):
Fig.@count@images:skin-b-style-img@: the WSX display styling images for the WSX-2.0 template's skin 'b'

Fig.@count@images:skin-k-style-img@: the WSX display styling images for the WSX-2.0 template's skin 'k'

The following rules apply for the "menu-width.png", "page-width-and-header-underline.png", and "background-inner.png" styling images:

The following rules apply for the "menu buttons" icons:


The "skin.css" styling file

This paragraph assumes the reader has (at least) some basic experience with applying CSS styling to HTML web pages. At the time of writing this document, a comprehensive description of CSS3 can be found here, and a concise presentation of the order in which the CSS styles are applied to an HTML element is available here.

The "skin.css" files present [one such file] in each skin sub-folder of the WSX template's skins folder "WSX_ROOT_FOLDER/skins" can control via CSS statements certain aspects of the visual appearance of various elements and areas of the WSX display; in this context, Fig.@count@images#wsx-display-css@ below illustrates the class names associated with the skinnable elements and areas of the WSX display (the illustration represents WSX-2.0's skin 'i'):
Fig.@count@images:wsx-display-css@: the WSX display elements and areas controlled by [each skin's] "skin.css" file
(illustration for the WSX-2.0 template's skin 'i')

Following is the complete list of CSS properties that can be set for each element/area annotated in Fig.@count@images#wsx-display-css@ above (all the elements/areas are class names):

IMPORTANT:
  1. when editing/defining the CSS file for a given skin, only change/define the CSS properties which are listed above for each CSS class; changing/defining a CSS property for a given CSS class which is not listed above inside that class is not recommended as it may result in layouts which are very hard to understand (and control) without a full understanding of the inner workings of the CSS skinning engine
  2. for all the CSS properties that define dimensions on the left- and right-hand side of elements (i.e. padding, border, margin) always use the same values for the ***-left and ***-right properties; this will allow the skinning engine to properly swap the the page browser element with the document viewer element when the '>' skin option is used

Gotchas

What's next



History


WSX-2.3.0

WSX-2.0.0

WSX-1.0.0