Using SashimiCMS

Sashimi is very easy to use. After all, it's just a bunch of templates, xml data and build files.

Requirements

Technical Requirements

SashimiCMS uses Apache Ant which runs on Java. That is the only technical requirement for running SashimiCMS.

You need to make sure you have a capable XSLT processor. I have found the default processor in java 1.4 is not capable of properly handling xsl:namespace-alias. Upgrading to java 1.5 fixed this, but it's not java's fault. It's the XSLT processor (such as TRAX or ...) which is responsible for executing your XSLT transformations. I have no doubt you could get SashimiCMS to work under java 1.4 if you adjusted the processor appropriatley. The tools which SashimiCMS uses are cross platform. Whatever you can run java on, you can use SashimiCMS on. You are also not tied to any specific IDE. You can use whatever you like. You can even get away with a text editor and the command line!

Skill Requirements

SashimiCMS is developer oriented. It uses:

• XML
• XSLT
• HTML / XHTML
• Other web technologies such as css and javascript (dependant on your content)
• Apache Ant

It is preferable to be comfortable with all these technologies. However, because SashimiCMS lets you use the tools you want to for editing your content, you could get away with as little as being comfortable editing a single XML file. Please note though, that SashimiCMS is also totally extensible, so if you want to extend the base system in any way, you will require more skills.

To skill up in the above web technologies (Ant excluded), head over to W3 Schools. They have some excellent tutorials on all things web related. For skilling up in Apache Ant, head over to the Apache Ant website.

Setting up

You must make sure you first have a Java runtime environment installed and working, and Apache Ant installed and working aswell.

Inital setup is very easy. Just download the latest release, and unzip the archive to your working folder. That's it.

SashimiCMS comes with some sample content so you can verify the CMS is working, as well as see some of it's capabilities immediatley. I highly recommend removing this sample content before you start using SashimiCMS. Remember, the sample content is in the download file. By all means use it as a reference, just don't leave it on your live site.

Remove sample content

To remove the sample content follow these steps:

• Delete all files under the pages folder
• Adjust the data/nav.xml file to reflect your new content heirarchy.

Building your site

You can build your site using the site target in the build file. The site target is also the default target so you can execute it using either of the following commands:

ant
ant site

Watch the output to make sure you don't have any errors.

When building element of the site, you can preprocess controls using the currently available controls. This allows for using controls inside other controls, like the articles control does with the infobox control and the header does with the phrase control. The biggest concern here is to make sure your build order is correct; make sure if a particular control depends on another, the other control is built first.

You can invoke a preprocess at any time. The default preprocess target works on html files in the build folder, using any available xslts in the build folder. To invoke the preprocess target just call the target through the antcall task.

<antcall target="preprocess"/>

The processed files will have _pre appended to the filename. So an input file of header.html becomes header_pre.html after preprocessing.

Adding a page

To add a page to sashimiCMS use the following steps:

• Add an xml file to the pages folder which conforms to the page file schema (or copy an existing page file)
• Adjust the data/nav.xml file to reflect your new content heirarchy, and to make sure people can navigate to your new page.

The page file schema is extremely simple. The root node is which holds your content. Content is bound to the contentHolder tags in the template file. The ID tag of the content in the page file must match the contentId of the contentHolder tag in the template file. The page file schema is as follows:

<?xml version="1.0" encoding="utf-8"?>
<page id="pageid" title=" - page title">
	<head>
		<!-- Page specific elements to add to head of output page -->
	</head>
	<content id="contentid">
		<!-- Page HTML goes here -->
	</content>
</page>

Remember, the layout of the page is determined by the template you use. When the <contentHolder> tag is hit in the template, the content is read from the page file and replaces that element.

Although you can arrange pages in the page folder into sub-folders, these sub-folders are not preserved when the site is built. Every page, regardless of the sub-folder it resides in, must have a globally unique name.

Removing a page

To remove a page from sashimiCMS use the following steps:

• Delete the page file you wish to delete from the pages folder
• Adjust the data/nav.xml file to reflect your new content heirarchy

Modifying the header

To modify the header of your page, edit the controls/header.html file.

Modifying the CSS / images / site resources

The resouces for the built site are kept under the resources folder. This folder is copied when the site is built. The files contained therein are not processed in any other way.

Articles

SashimiCMS has the concept of articles. An article can be any single content item such as an article, news release, story or calendar entry. The article controls in SashimiCMS help display lists of existing articles and content items. The data for the articles is stored in the data/article.xml file by default. An article has a list of attributes as follows:

The transforms in SashimiCMS can render articles in 2 different ways, either as a short list or a full rendering of the content. When articles are rendered they are sorted in chronological order, based on the date of the article. By default, articles with dates in the past are not shown. To display all articles, regardless of what the date is, set the remove_previous parameter to false in the article compilation task as shown below:

<xslt in="${project.path.data}/articles.xml" out="${project.path.build}/articles.html"
		style="${project.path.controls}/article.xslt">
	<param name="numGenDate" expression="${project.numGenerationDate}"/>
	<param name="remove_previous" expression="false"/>
</xslt>

You can control the maximum number of characters to display in the article summaries of the article list control by setting the max_char_count parameter. By default it is set to 200 characters.

Adding an Article

Make sure your target article page exists, then just add an article element to the data/articles.xml file, following the schema of the other article elements.

Removing an Article

Remove the article element for the article you want to remove from the data/articles.xml file.

Multiple Article Types

You may want to use articles for a number of different content item types, but not lump them all together in the same article data file. For example, you may have an opinion pieces section and a calendar section. It makes no sense to have to mix these 2 different content item types in the same data file.

You can add a new article data file by creating a file with the same schema as the data/articles.xml file (or just copy that file and remove the existing articles). In the build file you can then add targets to compile the articles present in the new file by copying the existing targets for articles and modifying them to use the new data file. Bind the article lists in the same way as is already done with the existing articles.

RSS output

SashimiCMS provides support for outputing any of the articles files as an RSS feed. The control responsible is the article_rss.xslt control. Make sure you configure the parameters for the RSS control appropriatley.

Modifying the Menu

The menu and the breadcrumb are both driven out of the data/nav.xml file. To correlate a page to a navigational element, you must make sure the id of the page element in the page file is the same as the id of the navItem element to which you want to associate the page to. As long as these elements are the same the navigational controls will work as expected.

The following is an explanation of the attributes used in a navItem node.

Sections

You may have many different nested logical groupings to your content heirarchy. For example, you have the main site heirarchy, and a different heirarchy for an articles section. SashimiCMS let's you keep these heirarchies somewhat seperate so you can have different menus appearing on different pages. This is controlled through the id attribute of the nav element (the section to render) and the section attribute of the navItem element (the section the article belongs to)..

Moving the built site

The site is built to the site folder, which by default is site. This folder contains the entire site and can be copied or moved as required. SashimiCMS provides 2 targets in the build file to package your site. The Zip and BZip tasks apply compression algorithms to your compiled site folder and produces either a zip or bzip2 file.