Creating Skins

You could theoretically offer as many skins as you wanted to your visitors -- there is no limit to the number. The creation of skins is fairly simple, but requires some attention to certain details when working on some of the template files. This document is intended to serve as a guide for those looking to create new skins for their site -- please read it carefully as you create them.

You may see examples of some sample skins that are included with the ___ download (in the skins folder). To create a new skin, simply copy one of the skin folders, and give it a new name that reflects the style of your skin. Then begin modifying the following template files:

categories.tpl
default.tpl
index.tpl
newsbox.tpl
reviews.tpl
search.tpl
storyblock.tpl
storyindex.tpl
user.tpl
viewstory.tpl
style.css

Three important things to pay attention to when modifying the template files:

1) Attributes: Items in curly brackets are attributes, i.e. {output} or {authors}. This contains the actual content that will be printed out on the page. You can surround these attributes with any kind of html that you want -- font tags, tables, whatever. Some attributes are required on some of the template pages, and some are optional.

2) Blocks: These are items that generate multiple instances of content in a loop -- for example, in your index.tpl template file, you only need to indicate where the news items should display on the page with the following:

This line is telling the script to include the newsbox.tpl file, and the template files will understand that it should print out several news stories in a loop, with just that one line of code. Another kind of block you may see is the following:

Content goes here, which will also include attributes, such as {category} or {description}

This is similar to the included block, except that rather than pulling in the block from another file, as in the case of the newsbox.tpl, this one is just defining the block at this very moment. As you read through the individual template file instructions below and look at the actual templates, all of this will make more sense. Text in purple is the actual attribute or block code you need to use -- green text is used for explanation.

3) The .tpl files do not have some of the usual tags at the beginning, such as <head> or <title>. That is because those tags are included in the header files (header.php or adminheader.php). Most of the template files begin with the <body> tag, except for a couple of the blocks (newsblock.tpl and storyblock.tpl)

A.categories.tpl -- This template file is used when people are viewing the category pages.

Required Blocks & Attributes:

 The start of the categories block, that outputs the categories.

{categorytitle} Outputs the category name
{categorydescription} Outputs the category description
{categoryimage} Outputs the category image, if it has one (must be put in img tag)
{numstories} Outputs the number of stories within that category (only shows if there are stories within)

 The end of the categories block.

 The storyblock (storyblock.tpl) which outputs the title, summary, etc.

{sortbegin} This begins the sorting dropdown form on the categories page
{charactermenu1} The first character dropdown menu
{charactermenu2} The second character dropdown menu
{genremenu} The genres dropdown menu
{ratingmenu} The ratings dropdown menu
{warningmenu} The warnings dropdown menu
{chaptersmenu} The chapters to search dropdown menu
{sortend} The end of the sorting dropdown form

{output} This outputs the page number links, so people can page through the category results
{pagelinks} Pages through results
{topcategorytitle} Displays the category name that you are currently viewing

Optional Attributes:

{categorycolumn} This is used by the script to know where to place the </tr><tr> tags that indicate a new row for the columns of categories. You must be using tables to display your categories for this to work, and each category should be placed within an individual cell. Example:

<table>


<td>
<img src="{categoryimage}" align="left">
{categorytitle} ({numstories})<br>
{categorydescription}<br><br>
</td>
{categorycolumn}


</table>

{home} A link that takes you back to the main index
{catslink} A link that takes you to the categories page - really only necessary if you have more than one category
{recent} A link that goes to a page that displays the most recent additions to the archive
{authors} A link that goes to a membership/authors list
{help} A link that goes to the help page
{search} A link that goes to a search page
{login} A link that shows either "Log in" or "My account" (if someone is logged in)
{logout} The logout link
{titles} A link to the titles page
{adminarea} Link to the admin area, if the admin is logged in
{footer} Text of the footer message

B. default.tpl This is a generic template this is used in several places by the script.

Required Attributes:

{output} Prints out the output required for that page. Depending on the page in question, it could be just about anything.

Optional Attributes:

{home} A link that takes you back to the main index
{catslink} A link that takes you to the categories page - really only necessary if you have more than one category
{recent} A link that goes to a page that displays the most recent additions to the archive
{authors} A link that goes to a membership/authors list
{help} A link that goes to the help page
{search} A link that goes to a search page
{login} A link that shows either "Log in" or "My account" (if someone is logged in)
{adminarea} Link to the admin area, if the admin is logged in
{logout} The logout link
{titles} A link to the titles page
{footer} Text of the footer message

C. index.tpl The main page of the site, that can include news, featured stories, the categories list, and a welcome message.

Required Attributes: really only required if you have multiple categories. If you have only category, you can just link directly to categories.php

 The start of the categories block, that outputs the categories.

{categorytitle} Outputs the category name
{categorydescription} Outputs the category description
{categoryimage} Outputs the category image, if it has one
{numstories} Outputs the number of stories within that category

 The end of the categories block.

Optional Attributes & Blocks:

 If you want to display news or updates on the front page

 The start of the featured stories block

{featuredtitle} Outputs the featured story's title
{featuredauthor} Outputs the featured story's author
{featuredsummary} Outputs the featured story's summary (up to 75 characters)
{featuredrating} Outputs the featured story's rating
{featuredcategory} Outputs the featured story's category

 The end of the featured stories block

 The start of the recently updated/added block

{recenttitle} Outputs the recent story's title
{recentauthor} Outputs the recent story's author
{recentsummary} Outputs the recent story's summary (up to 75 characters)
{recentrating} Outputs the recent story's rating
{recentcategory} Outputs the recent story's category

 The end of the recently updated/added block

{categorycolumn} This is used by the script to know where to place the </tr><tr> tags that indicate a new row for the columns of categories. You must be using tables to display your categories for this to work, and each category should be placed within an individual cell. Example:

<table>


<td>
<img src="{categoryimage}" align="left">
{categorytitle} ({numstories})<br>
{categorydescription}<br><br>
</td>
{categorycolumn}


</table>

{welcome} Outputs a welcome message (defined in Settings in Admin panel)
{newspageprev} Previous page of news stories
{newspagenext} Next page of news stories
{totalstories} Total number of stories in the archive
{totalauthors} Total number of authors
{home} A link that takes you back to the main index
{catslink} A link that takes you to the categories page - really only necessary if you have more than one category
{recent} A link that goes to a page that displays the most recent additions to the archive
{authors} A link that goes to a membership/authors list
{help} A link that goes to the help page
{search} A link that goes to a search page
{login} A link that shows either "Log in" or "My account" (if someone is logged in)
{logout} The logout link
{titles} A link to the titles page
{adminarea} Link to the admin area, if the admin is logged in
{footer} Text of the footer message

D. newsbox.tpl The block for the news stories -- NOTE: most of the other template files are full html files, with <body> tags. This file is one of the exceptions. Only input the code for the individual block itself, which can include <table> tags or whatever you want, but should not have the following tags: <html><body><head><title>

Required Attributes & Blocks:

 Starts the news story block. Must be at the beginning of the file.

{newstitle} The title of the news story
{newsstory} The text of the news story
{newsauthor} The author of the story
{newsdate} The date it was written
{newscomments} The number of comments, and link to them

 Ends the news story block. Must be at the end of the file.

E. reviews.tpl This template is used to display the reviews page.

Required Attributes & Blocks:

Starts the reviews block.

{reviewer} The name of the reviewer
{reviewdate} The date of the review
{member} If the person is a member, it says so. If not, then it says anonymous.
{chapter} The name of the chapter for that review.
{chapternumber} The number of the chapter for that review.
{review} The text of the review

 Ends the reviews block.

{jumpmenu} A jumpmenu to view the reviews for other chapters.
{reviewslink} A link for people to submit their own review.
{reviewpagelinks} Page links for the reviews.
{title} You can output the title at the top of the reviews page or wherever.

Optional Attributes:

{home} A link that takes you back to the main index
{catslink} A link that takes you to the categories page - really only necessary if you have more than one category
{recent} A link that goes to a page that displays the most recent additions to the archive
{authors} A link that goes to a membership/authors list
{help} A link that goes to the help page
{search} A link that goes to a search page
{login} A link that shows either "Log in" or "My account" (if someone is logged in)
{logout} The logout link
{titles} A link to the titles page
{adminarea} Link to the admin area, if the admin is logged in
{footer} Text of the footer message

F. search.tpl This is the template used for the various search functions.

Required Attributes & Blocks:

 When needed, outputs story summary, title, etc.

{output} Outputs the content of the page, such as the search box
{pagelinks} Page links for the results

Optional Attributes:

{home} A link that takes you back to the main index
{catslink} A link that takes you to the categories page - really only necessary if you have more than one category
{recent} A link that goes to a page that displays the most recent additions to the archive
{authors} A link that goes to a membership/authors list
{help} A link that goes to the help page
{search} A link that goes to a search page
{login} A link that shows either "Log in" or "My account" (if someone is logged in)
{logout} The logout link
{titles} A link to the titles page
{adminarea} Link to the admin area, if the admin is logged in
{footer} Text of the footer message

G. storyblock.tpl The template file for the individual story summaries. This is another example where you don't want to use <body> tags, as it isn't outputting a whole page -- it's just one element of the overall page.

Required Attributes & Blocks:

 Starts the news story block. Must be at the beginning of the file.

{title} The title of the story
{author} The author of the story
{ratingpics} If you have ratings turned on, it will display the appropriate rating (stars, thumbs)
{reviews} The reviews link, to view the reviews
{roundrobin} If the story is a roundrobin, it will display a robin graphic
{summary} The summary of the story
{category} The category the story is located in
{characters} The characters within that story
{genres} The genres that the story falls under
{rating} The rating of the story
{warnings} The warnings for the story (prints "none" if there are none)
{numchapters} The number of chapters in the story
{published} The date the story was published
{updated} The date the story was updated
{completed} If the story is completed or not
{numreviews} The number of reviews for that story
{wordcount} The number of words in the chapter

 Ends the news story block. Must be at the end of the file.

H. storyindex.tpl The template file used by the script when someone is viewing a story with multiple chapters. You can think of the story index as working two ways: you can just print out all the information for each individual chapter, using the storyindexblock on this page, OR if you tend to input all the pertinent information for the entire story in the first chapter, you could include all that info at the top of the page using the {first***} attributes, with the storyindexblock below only outputting the chapter title, reviews, wordcount, and any other specific attributes you want only to show for the chapters.

Required Attributes & Blocks:

 Starts the story index block

{title} The chapter of the story
{author} The author of the chapter
{reviews} The reviews link, to view the reviews
{summary} The summary of the chapter
{category} The category the story is located in
{characters} The characters within that chapter
{genres} The genres that the chapter falls under
{rating} The rating of the chapter
{warnings} The warnings for the chapter (prints "none" if there are none)
{published} The date the chapter was published
{wordcount} The number of words in the chapter
{numreviews} The number of reviews for the chapter
{chapternumber} The chapter number

 Ends the story index block

{completephrase} Outputs whether or not the overall story is completed.
{firsttitle} The title of the first chapter (i.e. the title of the overall story)
{firstauthor} The author of the first chapter
{firstsummary} The summary of the first chapter
{firstcharacters} The characters within that first chapter
{firstgenres} The genres that the first chapter falls under
{firstrating} The rating of the first chapter
{firstwarnings} The warnings for the first chapter
{firstcategory} The category for the first chapter
{addtofaves} Allows a logged in member to add the story to their favorites list

Optional Attributes:

{home} A link that takes you back to the main index
{catslink} A link that takes you to the categories page - really only necessary if you have more than one category
{recent} A link that goes to a page that displays the most recent additions to the archive
{authors} A link that goes to a membership/authors list
{help} A link that goes to the help page
{search} A link that goes to a search page
{login} A link that shows either "Log in" or "My account" (if someone is logged in)
{logout} The logout link
{titles} A link to the titles page
{adminarea} Link to the admin area, if the admin is logged in
{footer} Text of the footer message

I. user.tpl The template file used by the script when someone is viewing a user's page. It's pretty much the same as search.tpl, but if you wanted to include something else on this template, you could.

Required Attributes & Blocks:

 When needed, outputs story summary, title, etc.

{output} Outputs the content of the page, such as the user's name, bio info, and so on

Optional Attributes:

{home} A link that takes you back to the main index
{catslink} A link that takes you to the categories page - really only necessary if you have more than one category
{recent} A link that goes to a page that displays the most recent additions to the archive
{authors} A link that goes to a membership/authors list
{help} A link that goes to the help page
{search} A link that goes to a search page
{login} A link that shows either "Log in" or "My account" (if someone is logged in)
{logout} The logout link
{titles} A link to the titles page
{adminarea} Link to the admin area, if the admin is logged in
{footer} Text of the footer message

J. Viewstory.tpl The template file used when viewing the text of a story.

Required Attributes:

{title} The title of the story
{author} The author of the story
{story} The text of the story
{jumpmenu} The jumpmenu to view the chapters
{reviews} Link to the reviews for the story
{adminlinks} If you're an admin and viewing the story, you'll see edit and delete links
{roundrobin} If the story is a roundrobin, this will show a link asking people if they'd like to contribute

The following could be optional:
{summary} The summary of the story
{category} The category the story is located in
{characters} The characters within that story
{genres} The genres that the story falls under
{rating} The rating of the story
{warnings} The warnings for the story (prints "none" if there are none)
{numreviews} The number of reviews for that story
{addtofaves} Allows a logged in member to add the story to their favorites list

Optional Attributes:

{home} A link that takes you back to the main index
{catslink} A link that takes you to the categories page - really only necessary if you have more than one category
{recent} A link that goes to a page that displays the most recent additions to the archive
{authors} A link that goes to a membership/authors list
{help} A link that goes to the help page
{search} A link that goes to a search page
{login} A link that shows either "Log in" or "My account" (if someone is logged in)
{logout} The logout link
{titles} A link to the titles page
{adminarea} Link to the admin area, if the admin is logged in
{footer} Text of the footer message

K. style.css The stylesheet used by the skin. If you've never played around with Cascading Style Sheets before, there's no time like the present to learn! A few sites worth checking out if you're new to CSS: http://www.lissaexplains.com/css.shtml or http://www.echoecho.com/css.htm or http://www.html4newbies.com/css/index.shtml

If you take a look at the stylesheet included with the sample skin(s), it should be fairly obvious. Basically, you're defining the attributes of each kind of page element, such as the overall font, the different kinds of form elements, and so on. It lets you define the font that is used, the color, and other nifty things. I stuck to basics with the sample CSS files -- it's important that if you do any major modifications or additions, that you check and make sure that things work in the major browsers.

There are a few CSS classes that are required by the script:

.tblborder This class is used in several places, mainly to make things display with a nice, clean 1-width border.

.tblbackground This class is used the viewuser page, to color some cell backgrounds (only needed if favorites are turned on.)

.A.tbllink:link This class, and the related and the active, visited, and hover versions of it display as a different color than most links on the site, and is used in conjunction with .tblbackground (only needed if favorites are turned on).

. locked This class is used by the text of locked categories in the drop down menu when a member tries to add a story -- it's important to pick a color that makes it clear that this item should not be selected (i.e. gray). Including a note about this in your submission rules is probably a good idea, too, so people aren't confused (i.e. "Greyed out items in menu are not open to submission" or something similar.)

.notlocked The color of the text in the "Add Story" drop down menu for categories that are not locked.

A.menu:link This class, and the related and the active, visited, and hover versions of it display as a different color than the rest of the links on the site, and are used by the {home}, {recent}, {authors}, {help}, {search} and {login} template attributes. You can set this to have exactly the same color, font, etc. as the standard a:link elements, but it needs to be part of the CSS file regardless.

You can also add whatever CSS classes you want to the style.css file for each skin. For example, in the test skin, I added a .news class that allowed me to show the title and author of the newstory in a different color font than is used by the rest of the page. To tell the page to use that class, I simply put the following in the newsbox.tpl file: <span class="news">{newstitle}</span>

Other Tips

- You can use whatever html, images, or text you want outside of the attributes and block codes -- this allows for you to make your site look like anything you want it to, although the layout of the individual attributes are somewhat confined by the code of the script. Still, try to be creative and think about what you can do that would be different, useful, or interesting to make your archive stand out.

- Probably the best way to make a new skin, especially if you're new to html, is to go into your favorite WYSIWIG editor such as Frontpage or Dreamweaver, and create a skin that looks nice there. You can then start plugging in the different attributes where you want them to go on the page. Be sure to edit the actual HTML to add the block tags, though (i.e. ) because the editor won't input the code properly otherwise.

- If you have some javascript you want to use, feel free to add it to the file javascript.js as this file is called on every page -- just don't remove what is already there, as that will affect certain areas of your site

- Once you upload a skin to your site, it is strongly recommended that you not remove it. If you do, members who have selected that skin may have difficulty viewing the site, since their skin no longer exists!

- If you use images for your categories, you need to place the images in your skins/images folder -- they all must have the same name within each skin/images folder that you indicated when you created your category, but the images can be different for each skin.

Have questions, or have a really cool skin you want to show off? Come tell us in the forums at http://orodruin.sourceforge.net