Step 1: creating a simple web site

In this tutorial we're going to create a very simple web site powered by NorthernWind. The site will have three pages:

1. a home page
2. an “about” page
3. a “license” page

We're going to use Twitter Bootstrap 2 for the page layout and provide support for Google Analytics and AddThis.

Booting the example

First, let's have a look at what we're going to build. It's possible to bootstrap with example with Maven:

fritz% mvn archetype:generate -DarchetypeGroupId=it.tidalwave.northernwind -DarchetypeArtifactId=simple-site1-step1-archetype -B
[INFO] Scanning for projects...
[INFO]                                                                         
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ------------------------------------------------------------------------
...
[INFO] project created from Archetype in dir: /Volumes/Users/fritz/Desktop/simple-site1-step1
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.967s
[INFO] Finished at: Mon Feb 20 22:50:26 CET 2012
[INFO] Final Memory: 7M/81M
[INFO] ------------------------------------------------------------------------

This procedure downloaded from the web all the required resources and laid them out in the simple-site1-step directory:

fritz% find simple-site1-step1 -type f
./content/document/Fragments/Copyright/fullText_en.xhtml
./content/document/License/fullText_en.xhtml
./content/document/License/Properties_en.xml
./content/document/Under+construction/fullText_en.xhtml
./content/library/css/layout.css
./content/library/css/typography.css
./content/library/robots.txt
./structure/About/Properties_en.xml
./structure/Components_en.xml
./structure/License/Properties_en.xml
./structure/Properties_en.xml
./filesystems/northernwind-social-1.0.jar
./filesystems/northernwind-twitter-bootstrap-2.0.1-1.jar

To start up a webserver and boot the website type the following commands (yes, mvn without arguments):

fritz% cd simple-site1-step1
fritz% mvn
[INFO] Scanning for projects...
[INFO]                                                                         
[INFO] ------------------------------------------------------------------------
[INFO] Building NorthernWind - website 1.0
[INFO] ------------------------------------------------------------------------
...
2012-02-20 22:52:01.181:INFO::Started SelectChannelConnector@0.0.0.0:8080
[INFO] Started Jetty Server
[INFO] Starting scanner at interval of 4 seconds.

At this point the website is up and running and can be browsed at http://localhost:8080.

Creating the logical page structure

The first thing to approach when you want to create a website with NorthernWind is to define the logical page structure. “Logical” means that this structure is not necessarily related to the layout that will be rendered on the screen, it rather affects the internal components (e.g. HTML <div>s). As the first example we are going to consider the structure of this very website.

First, the logical page structure is composed by a hierarchy of visual components. Each component:

• has got an unique id;
• is associated to a behaviour (or component type);
• has got some properties, which influence the behaviour;
  
• can contain sub-components, thus making up a tree.

NorthernWind doesn't mandate any specific set of component types, but provides a default one. Component types are identified with an URI which are looked up at runtime. Standard components have URIs in the form http://northernwind.tidalwave.it/type/#vversion. In the following text we will omit the leading part of the URI for simplicity, so when you read NodeContainer/#v2.0 it's really http://northernwind.tidalwave.it/NodeContainer/#v2.0.

Below you can find a recap of the page structure we're going to illustrate, together with its properties. Please refer to it to understand the text below.

The base component

The topmost component is always a NodeContainer, which represents the page container. Typically it is assigned the base id. The properties for this component that we're using in this example are:

1. inlinedScripts is similar to the previous property, but in this case scripts are inlined into the page <head> instead of being merely linked.
2. screenStyleSheets, which enumerates all the style sheets for rendering to the screen. In our simple site we're going to use the Twitter Bootstrap default CSS, a style sheet named left-sidebar-200px.css which lays out a fixed-width sidebar at the left side and two custom style sheets (it's a good advice to keep separate style sheets for the layout and the typography customization). It is also possible to use absolute URLs referring to web resources: this can be useful for instance to embed Google Fonts.
   
3. templatePath, which points to the HTML template for the component. To use Twitter Bootstrap, you need to set it to the value /Templates/Bootstrap/2.0.1. 
4. titlePrefix, which sets the prefix of all page titles.

base contains three sub-components:

1. navbar, which contains the top navigation bar;
   
2. addthis, which contains the AddThis widgets;
   
3. container, which contains the remainder of the page.

The navbar component

This component represents the main navigation bar. Its type is HorizontalMenu and has got two properties:

1. templatePath points to /Templates/Bootstrap/2.0.1/topbar-fixed which contains a default implementation of the Twitter Bootstrap navigation bar in a fixed layout (it stays anchored at the top of the screen even when the page is scrolled).
2. links enumerates all the menu items. We're going to put all the three pages in our simple website in the navigation menu.

This component also uses a global property named navbar.title, which sets up the “branding”, that is the name of the website that appears at the left of the navigation bar.

The addthis component

This is a simple HtmlFragment, that is a piece of HTML markup which is directly provided by means of the property contents. We're going to use a library component for AddThis located at /Fragments/Social/AddThis. A global property, addThis.id, should contain a valid AddThis user name.

The container component

This component represent the main part of the page and it usually contains a single sub-component named row, which defines a block of HTML markup with the same layout (of course, multiple rows can be provided in case of need). This component, as well as a few further ones, is of type Container, which means that it only exists to contain other stuff.

Typically this component is responsible for defining the main layout of the page, via its class property. By default, each component generates a <div> whose stile is nw-id; it's possible to specify an explicit value when a known name from a CSS framework must be matched. For instance, in our case we're assigning the container component the class container-fluid, which in Twitter Bootstrap means a layout which expands to all the available horizontal room in the browser for rendering contents.

The row component

This component merely contains two sub-components:

1. sidebar, which contains the sidebar;
   
2. contents, which contains the main contents of the page.
   

The class property set to row-fluid to allocate all the needed vertical room.

The sidebar component

In this simple example we just want to create an empty sidebar. On this purpose, we put a sub-component into it, named well, whose class is well too. A well in Twitter Bootstrap is a visual section with a border and an engraved border. In a real-world case we would put other components into the well, but we'll deal with them in a further step of this tutorial.

The contents component

This is the last Container in the layout and contains the two final sub-components: main and copyright.

The main component

This component has type HtmlTextWithTitle, which means that it contains a portion of HTML markup and its title property will be rendered as the title. By default the contents property points to a resource named /Under construction which contains a short warning. Since the logical page layout is inherited, this means that by default all the pages in the web site will render with the same content, unless the contents property is overridden.

The copyright component

This last component is a simple HtmlFragment whose property contents point to a small piece of markup which renders the copyright which will appear as the footer of all the pages in this site.

Setting up the pages

todo