Overview.

The Elements application makes building and managing any site easier and less error-prone by allowing site builders to define components of the site as elements. With site components defined as elements, each page and directory of a site can re-define any particular element, or use the element definition of the parent directory. This allows for rapid site development and fast updates. Using scripts as elements adds even more depth and flexibility in defining elements.

The other pages in this documentation site take pains to make each detail clear; however, if you're not the kind to read the README, you should be able to read this page and get going in under 10 minutes.

Here is a brief overview:
When the Elements application is initiated, it operates on all the files within a specified source directory. Elements processes the source directory and creates a destination directory that mirrors the source and contains the complete site. In the source directory and sub-directories, content files generally have an .html or .css extension. The full list of content file extensions is configurable: contentExtensions (see ElementsSettings). Element files (see Glossary) have a "`" as their first character. Files which are neither content nor element files are considered assets and simply copied to the destination.

After processing a source directory, all the content and asset files are mirrored in the destination directory, and all the elements (see Glossary) of element files are merged into the content where appropriate.

Element files specify elements. Elements are strings of text which may be content, code, scripts or some combination. Elements are found both in element files and at the top of content files. Elements may be single line or multiLine (see Glossary).

Single line elements begin with the elementMarker (see ElementsSettings)—by default "#", followed by a name, followed by a space, followed by any text representing the value of the element.

e.g.
#title Test Page
#date Feb 20, 2002
#indexLink <a href="index.html">Home</a>
#foo {bar}
#bar nested!
#x 1{y}
#y 2{z}
#z 3
#element{x} abc

Elements are placed in the contents wherever "{", followed by a valid element name, followed by "}" appears.

e.g. "The story on {date} is {title}"
results in: "The story on Feb 20, 2002 is Test Page"

Elements may call other elements.

e.g.
"Elements can be {foo}"
results in: "Elements can be nested!"

"{x}" results in "123"

Elements in element names are evaluated.

e.g.
"{element1}" results in "abc"

Multiline elements begin with the elementMarker, followed by the name of the element, and a second elementMarker. If there is conent on the same line as the element name, white space on the left side of the first line is trimmed. The element's value is all that follows until the next line beginning with an elementMarker. The multiLineElement ends when a new element begins. If a multiLineElement is the last element in a file, it must closed with a trailing elementMarker.

e.g.
#threeLineElement#
Line One<br>
Line Two<br>
Line Three<br>
#twoLineElement# Line One. This line begins on the same line as the element name<br>
Line Two. White space on the left side of Line One is trimmed.<br> #

The first line of the element may begin on the same line as the element name if desired.

multiLine elements can contain Python code for execution within the page. Such elements are called code blocks. Their element name must begin with the codeBlockMarker (see ElementsSettings)—by default ".".

e.g.
#.aShortCodeBlock#
def head(s):
    return "<span class=\"head\">"+ s + "</a>"
#

Code blocks contain Python method definitions and must return a value for the value to appear in the page.

Python methods are called from the page like elements, but with parens following, like a standard call to a Python method (fitting, since that is what it is).

e.g.
{head('This is a Headline.')}
results in "<span class="head">This is a Headline.</a>"

Elements may be specified anywhere in the site hierarchy. An element defined in an elementFile will be available to all content in the directory containing the elementFile. An element defined in a content file will only be available to that content. If the same element is specified in more than one place, the deeper level wins. If an element is specified more than once on a single level (content file or elementFile), the last occurence wins.

For every elementFile encountered in processing, the elements of the elementFile are parsed. Elements are only recognized at the top of the file. All text remaining in the file after the last element definition is considered a single element whose name is the file name minus the extension and without the initial elementFilePrefix (see ElementsSettings)—by default "`".

e.g. For an elementFile called "`myElementFile.txt" with this content:
+++++++ begin file +++++++
#color CCCCEE
#width 124
This is some text which is not delimited by an element declaration.
+++++++ end file +++++++

there are three elements defined:
color: CCCEE
width: 124
myElementFile: This is some text which is not delimited by an element declaration.

Content files are handled similarly but with the addition of three auto-generated elements. For every content file encountered in processing, the elements of the content file are parsed. Elements are only valid at the top of the file. All text remaining in the file after the last element definition is considered a single element whose name is the file name minus the extension.

e.g. For a file called "myContent.html" with this content:
+++++++ begin file +++++++
#title My Content
#date Mar 17, 2002
The page was edited on {date}, though not for the last time.
+++++++ end file +++++++

there are six elements defined:
title: My Content
date: Mar 17, 2002
myContent: The page was edited on {date}, though not for the last time.
fileName: myContent
fileExt: .html
filePath: Nomad:Users:mike:nthwave:elements:htmlSrc:overview.html
(note, this page was built on a Mac, the path separator on Mac is ":".)

The Elements application begins processing each page with the firstElement (see ElementsSettings) element. The firstElement can usually be thought of as a template, though the firstElement is not always or necessarily a template. A typical template will have a "{{fileName}}" line where the content should be inserted. (Note the double braces!!) But there are other ways to get content into the firstElement. See the example for ideas.

The default value of the firstElement is "{template}", so there should be a file at the top of the source directory named `template.txt. (Don't give it the .html extension. That would make it both an elementFile and a content file.) The template should contain the html that is common to all pages. Wherever possible, use elements or scripts in templates to avoid hand coding pages. The pathToTop (see Generated Elements) element is essential in a template which is used for a nested directory.

Starting with the firstElement, all elements are replaced by their values until no unprocessed element calls remain in the content. The text is written to a file in the destination directory in a mirror position to its position in the source directory. The source directory is left untouched and in its original state.

Much of the power of Elements comes from the automatically generated elements. See auto generated elements for more.

Do the Installation, try the demo site, then do the Small Site Tutorial.