site.xml

Overview

site.xml is an XML document which contains the structure of the site (ie. which page goes where and what Java class should be used to process the data/content of the page).

Important: Eclipse uses the file site.xml for Plugin projects, so when you double-click on the icon, you will get a special page where you can comfortably edit this file for Plugins.

While this is a neat demonstration for how the SiteEditor will do it eventually, it makes things a little cumbersome for now. To edit the file in the text editor, you must open the context menu of the file and select "Open With" and then "Text Editor".

To solve this problem for the near future, select the checkbox next to the item "Text Editor" and Eclipse will remember this.

Code

<?xml version="1.0" encoding="UTF-8"?>
<site id="UYDojo">
    <title>Usagi Yojimbo Dojo</title>
    <page id="index" />
    <page id="news">
        <page id="events" />
        <page id="lmod" />
    </page>
</site>

Explanation

<?xml version="1.0" encoding="ISO-8859-1"?>

This tells the SiteEditor that this is an XML document which uses internation ISO Latin-1 characters (ie. US ASCII with Umlauts like ö, ä, ü).

This defines a site with the ID UYDojo. Note that there can be only one site definition in each site.xml file.

<title>Usagi Yojimbo Dojo</title>

Specifies the title of the site. Unless the custom code for the site does something special, this text will be prepended to the title of every page.

    <page id="index" />
    <page id="news">
        <page id="events" />
        <page id="lmod" />
    </page>

This defines a page with the ID "index". You can now use this ID in automatic links (see below), like this: [index] is replaced by the SiteEditor with UYD Home. When an ID is unique (and many are), you never need to worry where in the site a specific page is; just use the ID and the editor will figure out a relative URL for you. When you move the page, just cut&page in this file and move the data files to the new place. The SiteEditor will fix all the links for you.

The ID is also very important when the SiteEditor looks for its files. When you tell the editor to process this page, it will look into /UYDojo/content/index.page for additional data (like the text of the page).

The " />" tell the editor that this is an empty element (ie. this page has no child pages).

The page with the ID "news", on the other hand, has two children "events" and "lmod". The "</page>" marks the end of the news page. The next page element will create a new sibling of the news page.

</site>

And don't forget the closing site element.

Example Source of a Page

Code

<?xml version="1.0" encoding="ISO-8859-1"?>

<page id="demo" class="site.DefaultPage">
    <head>
        <title>Demo/Documentation Page</title>
    <menu>Text which is added to the link menu.</menu>
    <copyright>Additional copyright text</copyright>
    </head>
    <images>
        <img name="img1.jpg">The first image</img>
        <img name="img2.jpg">The second image</img>
        <img name="img3.png">The third image</img>
    </images>
    <content>
Content.
    </content>
</page>

Explanation

<?xml version="1.0" encoding="ISO-8859-1"?>

This tells the SiteEditor that this is an XML document which uses internation ISO Latin-1 characters (ie. US ASCII with Umlauts like ö, ä, ü).

This starts the actual page. The text id="demo" gives this page an id by which it can be referended in links. This is also the name under which the page will be saved on disk. The id can contain only lowercase characters (no umlauts), numbers and '-' (minus).

The attribute class defines which Java class to use to process the contents of this page. Possible classes are "site.DefaultPage" for normal pages with HTML content, "site.CharacterPage" for a person in UY's world or "site.CharacterIndexPage" which is a special page which can have only CharacterPage's as children. The CharacterIndexPage will create a nice, sorted menu for all child pages to make it easier to find a specific character.

The CharacterPage contains additional information about a person (name, the proper kanji for the name, some background info and pictures of the character). All this information will be formatted in a similar way for all characters to make it easier to find the information you want.

You need not worry too much about this. Later, you will be able to create new pages with a comfortable menu which will give you nice names and this attribute will be filled for you.

The attribute design is special for the UYDojo and specifies the design to use for this page. If you don't specify a design, then the design of the parent page is used. If none of the parent pages has a design, either, the default design is used.

<head>

This starts the header of the page which contains the title, for example.

<title>Demo/Documentation Page</title>

The text between the title elements will be used as the title of the page (which will show up in the title of the browser window, for example).

<menu>Text which is added to the link menu.</menu>

You can use the menu element to add additional text to the link menu.

<copyright>Additional copyright text</copyright>

Use the copyright element to add additional copyright notices to this page.

</head>

This concludes the elements which are valid in the head.

Pages can contain images. The images elements contains a list of img elements which declare all images which are known to this page. You can still use other images but these images here are most simple to use (as we'll see later).

<img name="img1.jpg">The first image</img>

This declares an image. Note that you must specify the file extension but that the name of the image is actually "img1". You can also add descriptive text to the image which will be used in the image gallery.

<img name="img2.jpg">The second image</img>
<img name="img3.png">The third image</img>

To show off some more features, two more images.

</images>

This concludes the list of images.

<content>
Content.
</content>

Everything in the content element will be used as the content of the page. Some pages, like the NEWS or Sitemap page, have automatic content. If you specify content for them, your content will be inserted above the automatic content.

</page>

That concludes the page.

Content

Overview

You can use a subset of HTML in the content or special markup. The available special markup is explained below.

Valid HTML elements are: h1, h2, h3, p, div, center, b, i, a, img, table, tr, th, td

Automatic Links

The main feature of the SiteEditor is the easy generation of links to other pages of the site. When the site is generated, the editor makes sure that these links work. To specify a link, use this code:

[usagi]

In the browser, this will look like this: Miyamoto Usagi

Sometimes, you will want to supply other than the default text (which is the title of the page you link to). To do this, use this code:

[usagi:My own text]

In the browser, this will look like this: My own text

If you use a name which doesn't exist, the editor will warn you about this. Writing [This link doesn't exist] gives FIXME Link: Unknown ref="This link doesn't exist" and an error is logged in the logs. This makes sure that broken links can be found easily.

Images

The SiteEditor allows the automatic generation of thumbnails.

[thumbnail img1]

In the browser, this will look like this:

You can scale the image to any size by either specifying the maximum width or height or both. The editor will make sure that the aspect of the image will be left intact. The default width and height is 150 pixels.

[thumbnail width=50 img1] [thumbnail height=50 img1] [thumbnail width=50 height=50 img1]

In the browser, this will look like this:

Now, this looks pretty ugly. To make it more pretty with little effort, you can "float" the image to a side. The text will the run around it.

The last paragraph started with this code: [thumbnail width=50 float=right img1]Now, this looks... As you can see, this paragraph also flows around the image.

Image Galleries

You can also present your images in so called galleries:


The first image (Size: 465x713, 3 KB)	The second image (Size: 465x713, 11 KB)	The third image (Size: 150x185, 3 KB)

This gallery was creates with this code:

The default gallery uses four columns and thumbnails with the default size of 150x150 pixels. You can specify other values as attributes in the gallery element. This code:

creates this gallery:


The first image (Size: 465x713, 3 KB)	The second image (Size: 465x713, 11 KB)

The third image (Size: 150x185, 3 KB)

Note that the third image is shown at its original site because it is smaller than the max. width specified.

Here is a complete list of all options for the gallery element:

Option	Default	Description
columns	4	The number of columns of this gallery
width	150	Max. width of thumbnails
height	150	Max. height of thumbnails
sort	itemorder	The sort order of the elements. Possible values are: itemorder Keep the order in which the items were specified in the gallery. date Order the items by date, newest first

Things to Fix Later

Sometimes, you will want to keep note of things which are not perfect, yet but you're unable to fix them right now. To mark those (so you don't forget about them), you can use the [FIXME] element: FIXME Remind me!

Later versions of the editor will show these in a list in the Tasks view of Eclipse.

Special Characters

Since the editor uses some characters for its own purposes, you can't use them directly anymore. Here is a table of all characters and what you need to type to get them in the final result:

Character	Escape Sequence
[	[
]	]
&	&
<	<
>	>