By template we mean HTML and FreeMarker code processed by SiteStudio to generate SiteStudio layouts.
SiteStudio templates have no relation to vendor website templates.
In order to create a SiteStudio template based on a vendor template, you will need additional work to integrate it to SiteStudio.
At the moment, ready-made SiteStudio templates are not sold anywhere, but distributed with SiteStudio.
SiteStudio uses a combination of page tamplates and layout templates to produce a professionally looking web site.
The fact that the layout and content are separated greatly helps to acheive flexible yet
great-looking pages. The creation of layout templates, or templates that define the look
of SiteStudio's pages is covered in
Adding new designs to SiteStudio.
Here, we will focus on creating content templates.
These are files that define what kind of information a user can place on a page, as well as
how this information will be displayed.
First we must fully understand the structure of the websites' hierarchy tree. At the root
of this tree is the "super-website" entity. This is the "parent" of all the other website entities,
and traditionally has the name "simple". You will not need to change this unless
you are rebuilding the whole website tree from scratch. The children of the super-website
are regular websites, which can be selected by the user at the time they (re)start building
their site. These usually define the type of site that a user wants to build (i.e. personal, corporate, etc.)
Each website contains a number of pages that can be added to that website. For example, a
personal website can contain a genealogy tree page which would not be approriate for a business
website. Each page entity can in turn be a root for it's own hierarch of sub-pages, or it may
simply be a plain page with no further children. If sub-pages DO exist, they can have sub-pages
of their own, ad infinitum.
Pages and subpages can be both visible and invisible. A visible page can be edited, viewed and
published, and is represented in the finished site by a physical HTML file. An invisible page can be
edited, and stores some data, but is not physically represented, and therefore cannot be viewed or
published. Rather the information it contains is inserted into another page, usually its partent which
IS visible. For example, a generic page contains an infinite number of invisible sub-pages each of
which represent a paragraph. Each of these paragraphs can be edited separately, but their contents
is displayed on the parent page in a list. Equally these pages have no individual HTML files once the
site is published, but rather, are included in the HTML of the generic page.
While most top-level pages would have to be visible pages, often their sub-pages will be
invisible, as in the example of the generic page.
Each page on the website must have a corresponding java object that stores its information.
There are a few predefined classes that can be used for this purpose, and if a completely
new functionality is needed, any of these can be extended. The following are Factory Supplied
Page classes that you can use for your pages with no Java programming:
This is a "vanilla" page. It is visible and contains no children.
use it for such things as a simple "About" page.
This is an extension of psoft.masonry.Page that allows the
addition of child sub-pages.
This class should be used for invisible (or "transparent") pages.
Since it is an extention of psoft.masonry.HierarchicalPage, it can
include children sub-pages as well.
The type of java class that you want to associate with a given page depends on what that page's
function, and can be specified in the page declaration file. This is a large XML file that
contains the definitions of all pages that are used in the sites available under the
super-website. (The super-website itself must be declared in the XML file as well. It should
be the root node of this file)
The root path for all the template files will be referred to as "template_path/". This is the
directory in which all the generic template files will be stored. In this same directory,
the directory for the super-website will be kept. If the name of the super-website is "simple",
then the path of it's files will be "template_path/simple/", and the XML desctription file will
be stored as "template_path/simple/simple.xml". The tag for the super-website entity is
"<website>" and should encompass all other tags in the file.
The entry for each individual site type is marked by a "<page>" tag, which
can contain children page declarations and definitions.
The main focus of this tutorial is adding new pages to existing website types. If you wish to
create a new website type entirely, you should use the existing code in the XML file and work from that.
To add a page to a particular website (for example personal) you will need to declare it and
define it. The declaration is done using the <child> tag, and the definition is done using the
Let us start from the definition. The basic <page> tag contains two parameters:
"name" is a name under which the page is to be identified. It should be unique in its
own scope. (The scope means that no other children of its parent shold have the same name.)
"class" is a string containing the full java class name of the class to be used to
represent this page. (i.e. "psoft.masonry.Page". See above for factory-packaged classes)
So a simple <page> tag is opened like this:
<page name="about" class="psoft.masonry.Page">
What this means is that the page will use the vanilla Page object to represent itself, and will
be referred to in the scope of this level of website's hierarchy by the name "about".
A <page> can contain any combination of the following three tags:
this tag has a name and a value parameter, and assigns a property of a page
(usually this is a default property that will later bechangable. for example
<param name="title" value="About"/> assigns the page a default title "About".
this tag allows you to declare pages that are only available within the scope
of the parent page. These page tags can have the same parameters and the same
child tags as the original <page> tag.
(The <page> tags can be nested to a depth limited only by the system resources.)
the child tag is used for page declaration, and will be defined in detail next.
Defining a page is not in itself sufficient to allow you to add it to the parent. You must also
declare it as the parent's <child>. The structure of SiteStudio is such that one defined <page>
can serve as a base for two different children. A <child> tag must have two parameters:
"name", the name under which this child will be known to its parent. The name must be unique among the parent's children.
"page", the name of the page on which this child is based.
The simplest use of the <child> tag would be <child name="about" page="about"/>
which states that the parent page can have a child based on the "about" page that will be known to it as "about".
A <child> tag can also have <param> tags inside of it that would supply properties in addition to
those defined in the <page> tag of the page that the child is based on.
If you wished to have two about pages, one of which would be titled "About You" by default and the
other -- "About me", you could use your one definition of the "about" page to achieve both:
<page name="about" class="psoft.masonry.Page"/>
<child name="about_me" page="about">
<param name="title" value="About Me"/>
<child name="about_you" page="about">
<param name="title" value="About You"/>
This way, it would later be possible to add functionality and properties to the core "about"
<page> and have these changes automatically translate into both of the children.
You will want to insert both the definition (<page>) and the declaration (<child>) tags into
the <page> tag of the entity under which you wish the given page to be located. If you want
that page to be a direct child of a website (for example the personal type), you will
need to insert these tags into the <page name="personal" ...> tag.
Now that the page is completely defined, you will need to create physical files that define
its look and its content. Let us assume that the templates for SiteStudio are located in
some directory at template_path, and that the super-website entity is known as "simple".
Then the files for defining an entity of the website should be located in the directory template_path/simple/hierarchy_path
where hierarchy_path is the path obtained from putting together a page's name with the names
of all its "ansestors" (that is the <page> names, not the <child> names).
So for a page with the name "about" that is a child of a "personal" site, hierarchy_path becomes personal/about/ and
the complete path would then be template_path/simple/personal/about/
Similarly, if the about page had a child page named "about_address" (such a page could contain
the address information for the site's owner) then the path for that page would be
For most types of pages, it will be enough to only provide two files in order to fully describe
the new page: the layout file and the edit file.
The layout file should be called "html" and contain freemarker-enchanced html code for displaying
the content portion of the page. As this file will be <include>d into a file containing the
styling code, it should not have an <html> tah or a <body> tag, but simply begin displaying the
page's contents right from the start. An example of the simple version of the layout "html" file
for the aforementioned "about" page would be: template_path/simple/personal/about/html :
The above code simply shows the page's title and then its text. In addition to the layout file we also need to have
an edit file. Its name should be "edit.body", and it should be contained in the same directory as the "html" file.
The format for the file is as follows: