1. Structure of SS catalogues

This article explains the part of SS catalogue structure that a designer needs to know.

.\psoft_config\
		masonry.properties    - main SS configuration file
		customform.properties -
		lang.properties       - lang file (multilanguage support)
.\public_html\  root of the website (for test installation)
		\masonry\widgets\simple\personal\preview*.jpg - design previews 
			
.\masks\personal\
		\l1     masks for designs 1 to 11
		...
		\l11

		\splash - masks for splash

.\templates\  - directory with templates
		last.html     \
		list.html     | these templates are not connected to designs
		login.html    | and are global for all categories
		logout.html   /
		\simple\
			 simple.xml - stores category and site settings
			 personal\  - stores all pages and settings for the "personal" category
				 layout\ - stores design layouts
				 other\  - stores "settings" pages for every design
				 splash\
				         all other catalogues have templates for user pages; 
					 they must be defined in "simple.xml"
					 personal.edit - page for selecting a design
					 personal.layout.list - color schemes (default color settings)
					 personal.settings.edit - "settings" template
					 personal1.edit - template for selecting site's design
					 personal2.edit - global user site parameters
					 personal3.edit - special effects configuration page
			                 (Settings->Select site theme/effects)

			 generic\ - global functions that are used in most templates
				 functions
				 images - describes functions for generating images (all images 
					  from images.xml must be defined here)
				 navbar
				 other
				 paragraph
				 show

2. Adding new designs to SiteStudio

This article explains how to add a new design to SiteStudio.
We will be looking at the situation when SiteStudio already has ten templates and we are going to add eleventh template called "test_design".

//**************************************************************
//**************************************************************

Step 1. Define Color Schemes

//**************************************************************

Open file templates\simple\personal\personal.layout.list .  This file begins with a list of color schemes for existing ten designs.  At the end of the list, add the name of your new design following general pattern:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

var layouts = new Array("${lang.personal.layout.list.simple_rombus}", 
			"${lang.personal.layout.list.shaded_petals}", 
			"${lang.personal.layout.list.angled_header}", 
			"${lang.personal.layout.list.simple_logo}", 
			"${lang.personal.layout.list.simple_labels}", 
			"${lang.personal.layout.list.stylish_professional}", 
			"${lang.personal.layout.list.stylish_header}", 
			"${lang.personal.layout.list.floating_sidebar}", 
			"${lang.personal.layout.list.stylish_duo}", 
			"${lang.personal.layout.list.stylish_mono}",
			"${lang.personal.layout.list.test_design}");

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the name of the new design was included into the lang file (psoft_config/lang.properties), we should use the "long" name, as in the last line above:
			"${lang.personal.layout.list.test_design}");  
However, if translating the interface into another language will not be necessary, this name can be entered directly in the template, in which case it is enough to use the short name:
			"test_design");


The rest of the file contains settings for every color scheme: 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

var colors = new Array(
/* 1 */ 
new Array(

.........................................................
.........................................................
.........................................................

"${lang.personal.layout.list.yellow}",
new Array("toolbox.title.color", "#000000", "toolbox.heading.color", "#000000", "toolbox.text.color", "#000000",
 "toolbox.bg_color", "#E1E15D", "toolbox.l_color", "#000000", "toolbox.al_color", "#000000", "toolbox.vl_color",
 "#000000", "toolbox.color1", "#FFFFCC", "toolbox.color2", "#000000","toolbox.textcolor", "#000000")),

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

At the end add the following code:  Mind the brackets:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/* 11 */
new Array(
"test_design",
new Array("toolbox.title.color", "#000000", "toolbox.heading.color", "#000000", "toolbox.text.color", "#000000",
 "toolbox.bg_color", "#FFFFFF", "toolbox.l_color", "#000000", "toolbox.al_color", "#000000", "toolbox.vl_color",
 "#000000", "toolbox.color1", "#669ACC","toolbox.color2", "#D0E2F3", "toolbox.textcolor", "#396C9F"))
);

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Values for this design do not need to be initialized.  They will be initilaized when the site is created or when the design is changed.

The above changes will include our new design into the design list.


//**************************************************************
//**************************************************************

Step 2. Add preview images

//**************************************************************

Now let us add 2 images to preview website's layout:

preview_11_0.jpg - greyscale image 
preview_11_1.jpg - image for current color scheme

This will show our design in the list of designs and the preview.
Dobavte eti images v dir: public_html/masonry/widgets/simple/personal/


//**************************************************************
//**************************************************************

Step 3. Create three l11 files

//**************************************************************

Go to ..\simple\personal\layout 
and create three files: 
"l11.wait", 
"l11.layout", and 
"l11.layout.init".

The l11.wait file visualizes the functions generating images for our design.
Include the following lines into this file:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<include global.path+"/generic/images">

<if wait><if !publish><include global.path+"wait"></if>

<if !publish><include global.path+"reload"></if>
</if>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The l11.layout file is easy to create using an .html pre-built for your design.  Copy the .html source into this file, removing the <html> and </htlm> tags, the whole header including the <head> and </head> tags, and the <body> and </body> tags.

Next, add the following lines in the appropriate places:

<include path+"/html"> - this includes the code generated by SiteStudio based on information specified by the user.

<call bottomLinks(global.thepage)> - links to navigate the site
<call copyright(this)> - SiteStudio logo with PSoft copyright.


l11.layout.init is the file where you initialize template-specific variables.


//**************************************************************
//**************************************************************

Step 4. Add image description

//**************************************************************

In the image.xml file add your image description.  
It must look similar to the following:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<image name="l11_logo" bgcolor="$bgcolor">
	<imgop type="maskedfill">
		<imgop type="file" src="personal/l11/logo_mask.png" base="$img_path" />
		<imgop type="overlay">
			<rectangle x="0" y="0" w="156" h="225" color="$bgcolor" fill="true" />
			<imgop type="maskedfill" resize="true">
				<rectangle x="0" y="31" w="122" h="122" color="$bgcolor" fill="true" />
				<imgop type="file" src="$uimg"/>
			</imgop>
			<imgop type="maskedfill">
				<imgop type="file" src="personal/l11/logo_mask3.png" base="$img_path" />
				<param name="color">$color3</param>
			</imgop>
			<imgop type="maskedfill">
				<imgop type="file" src="personal/l11/logo_mask2.png" base="$img_path" />
				<param name="color">$color2</param>
			</imgop>
			<imgop type="maskedfill">
				<imgop type="file" src="personal/l11/logo_mask1.png" base="$img_path" />
				<param name="color">$color1</param>
			</imgop>					
		</imgop>
	</imgop>
	<param name="arguments">bgcolor,color1,color2,color3,uimg</param>
 </image>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

where:
	l11_logo - image name; 
	bgcolor - background color;
	color1,color2,color3 - mask colors;
	uimg - mask or image identified (uploaded) by the user.

//**************************************************************
//**************************************************************

Step 5. Add function to generate the image

//**************************************************************

In \simple\generic\images add lines:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<function l11_logo_gen(alias,bgcolor,color1,color2,color3,uimg)><compress>
 ${global.thepage.igen.gen.paramNames("name","bgcolor","color1","color2","color3","uimg").paramValues("l11_logo",bgcolor,color1,color2,color3,uimg)}
 <call setIAlias(alias)> 
</compress></function>

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Make sure variable names in this text are the same as in the XML file.  This error is quite hard to trace.  Next, clean \var\imaker and \var\websites for imaker to generate all graphics anew.  Then restart imaker.

//**************************************************************
//**************************************************************

Step 6. Change l11.wait

//**************************************************************

Open \simple\personal\layout\l11.wait and add the following lines:

<call l11_logo_gen("logo",toolbox.bg_color,toolbox.color2,toolbox.textcolor,toolbox.color1,image.logo.absurl)>
<call checkFile(logo)>

and

<if logo.url></if>

so it looks as follows:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<include global.path+"/generic/images">

<call l11_logo_gen("logo",toolbox.bg_color,toolbox.color2,toolbox.textcolor,toolbox.color1,image.logo.absurl)>
<call checkFile(logo)>


<if wait><if !publish><include global.path+"wait"></if>
<if logo.url></if>

<if !publish><include global.path+"reload"></if>
</if>

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

//**************************************************************
//**************************************************************

Step 7. Change l11.layout

//**************************************************************

To see our image, open \simple\personal\layout\l11.layout 
and add the following line:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
${logo.show}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Or, if you don't want to accept the defaults, add:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<IMG SRC="${logo.src}" WIDTH="156" HEIGHT="225" BORDER="0">
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Repeat steps 4 to 7 for every image.


//**************************************************************
//**************************************************************

Step 8. Add rollovers

//**************************************************************

8.1 Similarly to common images, we need to describe every rollover in image.xml, for example:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<image name="l11_button" bgcolor="$bgcolor">
	<imgop type="overlay">
		<imgop type="greymask">
	                <imgop type="file" src="personal/l11/B11.png" base="$img_path"/>
			<param name="color">$color</param>			
		</imgop>
 		<label color="$textcolor" w="82" h="23" center="true">
		<font face="Verdana" size="9" fill="true" bold="true" italic="true"/> 
		<text>$text</text> 
		</label>
	</imgop>
	<param name="arguments">bgcolor,color,textcolor,text</param>
</image>

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In this example we modify button appearance by changing color and textcolor variables. 

8.2 In l11.wait add code to generate buttons.  This file gains the following look:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<include global.path+"/generic/images">

<call l11_logo_gen("logo",toolbox.bg_color,toolbox.color2,toolbox.textcolor,toolbox.color1,image.logo.absurl)>
<call checkFile(logo)>

<function setButton(alias, on, text)><compress>
<if on>
<call l11_button_gen(alias,toolbox.bg_color,toolbox.color2,toolbox.textcolor,text)>
~~~~~~~~~~~~~~\button is on
<else>
<call l11_button_gen(alias,toolbox.bg_color,toolbox.textcolor,toolbox.color2,text)>
~~~~~~~~~~~~~~\button is off
</if></compress></function>

<function mkButtons(text, id)><compress>
<call setButton("button_on_"+id, "true", text)>
<call checkFile(local("button_on_"+id))>
<call setButton("button_"+id, "", text)>
<call checkFile(local("button_"+id))>
</compress></function>


<function genButtons(id)><compress>
<if local("button_"+id).url></if>
<if local("button_on_"+id).url></if>
</compress></function>


<list global.thepage.pages as page>
<if page.visible> <call mkButtons(page.alt,page.page_id)> </if>
</list>
<if global.thepage.email><call mkButtons("E-Mail","email")></if>
~~~~~~~~~~~~~~\there is no e-mail page, so this button should be made separately

<if wait><if !publish><include global.path+"wait"></if>

<if logo.url></if>

<list global.thepage.pages as page>
<if page.visible> <call genButtons(page.page_id)> </if>
</list>
<if global.thepage.email><call genButtons("email")></if>

<if !publish><include global.path+"reload"></if>
</if>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

8.3 In l11.layout add the following:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<list global.thepage.pages as page>
<if page.visible>
<call imgLink(page.url, local("button_"+page.page_id), local("button_on_"+page.page_id), page.alt, "img"+page.page_id)>
</if>
</list>
<if global.thepage.email>
<call imgLinkOther("mailto:"+global.thepage.email, button_email, button_on_email, "Email Me", "img_email")>
</if>

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This should be written in one line with no spaces or "enters" between the tags.


8.4 Now we have a new template integrated into SiteStudio.  However, we still cannot change default parameters, i.e. modify the color scheme, because the "Settings" tab does not have the necessary fields.  To add new fields and their headers, you need to create one more file
  ...\simple\personal\other\l11.settings
Including the following lines will allow users to change 3 basic colors and add logo or a picture: 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<tr><td>Style Color1</td><td> <call colorPicker("toolbox.color1", toolbox.color1)></td></tr>
<tr><td>Style Color2</td><td> <call colorPicker("toolbox.color2", toolbox.color2)></td></tr>
<tr><td>Style Color3</td><td> <call colorPicker("toolbox.textcolor", toolbox.textcolor)></td></tr>
<tr><td>Logo Image:</td><td> ${image.logo.edit} </td></tr> 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This will add new toolboxes to the "Settings" tab.