SashimiCMS Tutorial

In this tutorial we will build a basic content driven website using SashimiCMS.

Pre-Requisites

Your build environment should be setup according to the Using SashimiCMS page.

First thing to do is download SashimiCMS from the download page. Once you've got it, unzip the archive on your local disk. First let's make sure your build environment works by building the sample content.

The archive contains a parent folder (sashimi_x.x) which contains the documentation folder and the CMS folder. Open a command prompt and navigate to the CMS folder. Execute the default target using ANT.

ant

If you get any errors then your environment is probably not setup correctly. Analyse the error messages and diagnose the problem before continuing.

If all went well (which it should have) then the sample content will have been built into the site folder. Open the default.html page in your browser. You should be looking at something similar to figure 1.

SashimiCMS demo content home page

Figure 1: Sample content home page

Now that we know everything is working, it's time to trash the existing content and start with a blank CMS. Delete the following data files from the CMS.

Let's start now by tailoring the build file for the project. Open the build.xml file and change the project name attribute to something appropriate like "mySite". The default path properties should be fine.

Now we'll change the phrase that's displayed in the header to something more appropriate like "mySite Rocks!". Open the controls/phrase.html file and adjust the text between the span tags. The phrase control is an example of using the static_control_transform control to create a custom tag for some reusable content.

While we're on the topic, let's create an tag repalacement control to provide the webmasters email address. This email address will be placed on many pages and would cause quite a headache if it changed. You would have to go through the entire site finding occurances of the address and changing it. By using the static_control_transform control we can specify the email address only in one spot making management of it much easier.

In the controls folder create a file called email.html. Open the file in a text editor and enter the webmasters email address in a container tag. Remember, XSLT works on XML files, which XHTML files are. We can't have just plain text, so we need to wrap any plain text in a containing tag such as a div or a span. Next we add a task to build this static content into a tagged control. In the build file add the following task to the bottom of the setup target.

<xslt in="${project.path.controls}/email.html" out="${project.path.build}/email.xslt" style="${project.path.controls}/static_control_transform.xslt">
<param name="element_name" expression="email"/>
</xslt>

This provides us a new tag which we can use in anthing built after this control; the email tag <email/>.

SashimiCMS uses templates as a kind of page master. Temapltes are XHTML files (without the XHTML declaration) with extra tags. The tags are provided by the controls which we build. A template defines the overall page layout and binds the page content to place holders. Create a new template file at templates/main.xml. Open the file in a text editor and provide the basic layout for our pages as given below.

<?xml version="1.0" encoding="utf-8"?>
<html>
<head>
<title>mySite</title>
</head>
<body>
<header/>
<contentHolder contentId="top"/>
<breadcrumb/>
<nav id="main"/>
<contentHolder contentId="main"/>
<footer/>
</body>
</html>

You can see in the above template we have 2 content place holders. One for top and one for main. The content which gets bound to these place holders is defined in the page files. So let's create a page file. Create a new page file at pages/default.xml. Open the file in a text editor and provide the content for the place holders as given below.

<?xml version="1.0" encoding="utf-8"?>
<page id="home">
<content id="top">
This is some top content
</content>
<content id="main">
<div class="content">
  <h1>Welcome to mySite</h1>
  Welcome to mySite, the <b>SashimiCMS</b> tutorial site!
</div>
</content>
</page>

Make sure that content is either plain text or has a single containing element. SashimiCMS can't currently handle content nodes which are mixed text and elements. The easiest way to wrap content in a containing element is to wrap it in a div has we have above.

There is also another element of the page class we could use but haven't. The head node can be used directly below the page node. Items inside the head node are copied directly to the final page file. This allows for linking to additional CSS files for a single page, or perhaps setting an RSS feed for a single page.

This is enough to use the basics of SashimiCMS. However if you try and build the website right now it won't build. This is because the articles tasks are expecting certain articles data files to allow them to build.

Create a new articles file at data/articles.xml. We'll place an entry for our single content page in this file. Open the file in a text editor and enter the content given below.

<?xml version="1.0" encoding="utf-8"?>
<articles>
<article title="First Article" date="20061002" moreurl="default.html">
This is my first article.
</article>
</articles>

The articles data file is pretty self explanitory. The date attribute must be in ISO format of yyyyMMdd. You can provide a url to the article which gets rendered to the final page as a "more..." link. You can also provide a start time and end time for an article. This is for when using articles more as calendar items or events.

In addition to providing data for the article controls, we need to provide data to the navigational controls: menu and breadcrumb. The navigation data file specifies the heirarchy of the website. Create a new navigation data file at data/nav.xml. Open the file and enter the content below.

<?xml version="1.0" encoding="utf-8"?>
<navigation>
<navItem title="home" id="home" section="main" url="default.html"/>
</navigation>

navItems can also be nested within one another. The id attribute must be unique and must match the id given in the page file. This helps match items up and provides highlighting for the menu control as well as allowing the breadcrumb control to work.

The last data file we must provide is the navigation styles data file. It tells SashimiCMS which CSS style to apply to certain menu controls (in the event we have more than one). Create the file at data/nav_style.xml. Open the file in a text editor and enter the cotnent below.

<?xml version="1.0" encoding="utf-8"?>
<styles>
<style section="main" cssclass="mainmenu"/>
</styles>

The section attribute must match a unique name used in the nav.xml file for a particular section.

Now, let's make sure we've entered our data and page files correctly. SashimiCMS has a validation target for just this task. Unfortunatley the current ANT release has a bug which means we can only valid a single file at a time. Luckily for us right now we only have single files for each file type. Invoke the ant target validate.

ant validate

We're finally there! We can now build SashimiCMS. During the build process you will notice 2 folders being created in the project. These are build and site. Build is used to build the files required for the final site and the site folder is where these files get copied once they have been built (provided there were no errors). If we check the site folder we'll see 2 files: default.html which is our homepage, and articles.xml which is an RSS feed of the articles on the site. The RSS file is generated from the articles data file. As we haven't done any CSS yet, we end up with the rather bland page we see below.

Unstyled home page

Figure 2: Unstyled home page.

Adding article summaries

Before we jump in and start styling the site, let's add an article summary control. Open the home page file pages/default.xml and somewhere in the main content area add the articles tag. While you're at it, we may as well also add the email tag which we created earlier.

<content id="main">
<div class="content">
<h1>Welcome to mySite</h1>
Welcome to mySite, the <b>SashimiCMS</b> tutorial site!
<articles/>
Got something to say? Then say it to <email/>>
</div>
</content>

Now if we build we'll get a list of the articles and the email address substituted into the two custom tags we used above. Remeber, you can create as many custom tags as you like for static replacement as has been done with the email control. One thing to note here though is you still have to abide by the rules of XML, so you can't use tag replacement for attributes.

Add styles and images

Let's make it look a bit nicer. First of all, we'll create a CSS file at resources/css/main.css. Now open the file and provide some basic styles.

body
{
font-family: Tahoma, Arial, Sans-serif;
font-size: 10pt;
}

#header
{
font-size: 2em;
font-weight: bold;
border: solid 2px #854814;
background-color: #dd7722;
padding: 10px;
}

.subtext
{
font-size: 0.4em;
font-style: italic;
}

#footer
{
border-top: solid 2px #854814;
font-size: 0.8em;
margin-top: 20px;
text-align: right;
width: 100%;
float: left;
}

OK, that's looking a little better. Now let's give some style to the infobox element. The infobox is used in the articles control so we need to style it to bring it out.

.infobox
{
border: solid 2px #854814;
padding: 5px;
margin: 10px 0px 10px 0px;
}

.infoboxTitle
{
background-color: #dd7722;
border-bottom: solid 2px #854814;
font-weight: bold;
margin: -5px -5px 0px -5px;
padding: 5px;
}

Now let's adjust that breadcrumb so it looks a little nicer.

#breadcrumb
{
border: solid 1px #666666;
margin: 5px 0px 5px 0px;
}

#breadcrumb ul
{	
padding: 2px;
margin: 0px;
}

#breadcrumb li
{
list-style: none;
display: inline;
}

Almost there for styles...just gotta style the menu so it looks like a menu. The menu also uses CSS to highlight which node the user is on. We'll put the menu down the left side of the page, so we'll also have to style the content div.

.mainmenu
{
float: left;
}

.mainmenu ul
{
padding: 0px;
margin: 0px;
}

.mainmenu li
{
list-style: none;
margin: 2px 0px 2px 0px;
}

.mainmenu li li
{
margin: 2px 0px 2px 5px;
}

.mainmenu a
{
display: block;
width: 150px;
border: solid 1px #854814;
background-color: #dd7722;
text-decoration: none;
color: black;
padding: 2px;
}

.mainmenu a:hover
{
background-color: #854814;
}

.mainmenu .highlight
{
background-color: #dda270;
}

.content
{
margin-left: 180px;
}

You may have noticed we're missing the feed image. By default SashimiCMS outputs the RSS feed for the articles and puts a link for the feed in the footer. The feed image is included with SashimiCMS. Create a new folder under resources called img. Next, from the SashimiCMS.zip file, extract the resources/img/feed.png to the folder you just created.

Now the last thing to do is link the CSS file to the main template. Open the templates/main.xml file and add the following element to the head element, just under the existing title element.

<link rel="stylesheet" type="text/css" href="css/main.css"/>

Now built the site and see the glory of CSS!

Styled home page

Figure 3: Styled home page.

Now might be a good time to point out that SashimiCMS outputs valid XHTML 1.0 strict markup. However, this depends on how you've written your templates, pages and content. If you have followed this tutorial to the letter, the page that has been built is valid. Submit it to the W3C validator at http://validator.w3.org and check for yourself.

Add more content

The breadcrumb and nav controls aren't really doing much at the moment. Not much to do when there's only a single content item, so let's add a few more articles to make them work a bit more. First we'll create an additional content page. Copy the existing home page pages/default.xml and paste it, making a copy to pages/art1.xml. Now open the file and adjust the content so we can tell that this is actually a different page to the home page. Make sure you change the ID of the page.

<?xml version="1.0" encoding="utf-8"?>
<page id="art1">
<content id="top">
Articles top content
</content>
<content id="main">
<div class="content">
  <h1>Art1</h1>
  This is art1 content.
  Got something to say? Then say it to <email/>.
</div>
</content>
</page>

Open the data/nav.xml file and add the new page at the same level as the home page. The final nav.xml file should look like that below. Make sure you match the ID of the page to the navItem.

<?xml version="1.0" encoding="utf-8"?>
<navigation>
<navItem title="home" id="home" section="main" url="default.html"/>
<navItem title="Article 1" id="art1" section="main" url="art1.html"/>
</navigation>

If you build the site now and navigate to the new page you will notice the root of the breadcrumb changes to the new article. This is actually correct for our current content heirarchy as given by the nav.xml file. But we want the home page to always be the root. Open the template file templates/main.xml and add the following attribute to the breadcrumb control.

alwaysInclude=".home."

The alwaysInclude attribute lists navItems to always show in the breadcrumb. Items are seperated by decimal points and the list must start and end with decimal points.

Continue to add more articles. Include some nested articles so you can see how the menu and breadcrumb behave with nested items. Try and create a structure as shown below in the nav.xml file.

<?xml version="1.0" encoding="utf-8"?>
<navigation>
<navItem title="home" id="home" section="main" url="default.html"/>
<navItem title="Article 1" id="art1" section="main" url="art1.html"/>
<navItem title="Article 2" id="art2" section="main" url="art2.html">
<navItem title="Article 2.1" id="art2.1" section="main" url="art2.1.html"/>
<navItem title="Article 2.2" id="art2.2" section="main" url="art2.2.html"/>
<navItem title="Article 2.3" id="art2.3" section="main" url="art2.3.html"/>
</navItem>
<navItem title="Article 3" id="art3" section="main" url="art3.html"/>
</navigation>

Make sure you create the content files for the above items as well. Built the site and have a click around the new items. Notice the breadcrumb follows your trail and the menu expands when child items are present and also highlights your current location.

We have a nested set of articles hanging off the article 2 page. Let move these articles to a new section to remove them from the main menu and we'll provide another menu on the relevant pages to display them instead. First thing to do is specify a new section for the articles. Open the nav.xml file and change the section for article2.1, article 2.2 and article2.3 to subart. If you Build the website at this point you'll notice the articles are no longer visible in the main menu.

Open each of article2, article2.1, article2.2 and article2.3 and place the following menu control at the bottom of the content.

<nav id="subart"/>

The resulting menu is unstyled as we haven't specified the style for it in the nav_style.xml data file. Open the data/nav_style.xml file and add the following item below the existing style element for the main menu.

<style section="subart" cssclass="mainmenu"/>

This will give the menu the same style as our main menu. If this isn't appropriate, we can change the style applied to the resulting menu by changing the cssclass attribute.

The last thing to do now is to alter the nav.xml data file to indicate that article2 is a section parent, and it should be highlighted when any children are selected. Open the data/nav.xml file and add this attrbute to the article2 navItem.

<navItem title="Article 2" id="art2" section="main" url="art2.html" sectionParent="true">

Built the site and bask in the warm glow of your first SashimiCMS website.

Completed site

Figure 4: The completed site.