Creating Skins - WIP
Content of file: docs/creating_skins.htm
Last updated
Content of file: docs/creating_skins.htm
Last updated
In theory, there is no limit to the number of skins you can create for your site. If you have created skins for eFiction 1.1, you won't find many differences. The number and names of the .tpl files have changed some though. A complete skin will include the following files.
Now, to quote Douglas Adams...Don't Panic! That's the most number of files a skin would use. Most skins will consist of quite a few less. If you install add-on modules, those modules may require additional .tpl files which will be included with the module.
Within the script files is a folder called default_tpls. It includes a very basic complete skin that will be used if for whatever reason your site's default skin or your member's chosen skin are missing. If any of these .tpl files (except for header.tpl and footer.tpl) are missing the script will fall back on the files in the default_tpls folder. Many of the tpl files are generic enough that they can easily be left to the ones in default_tpls and styled using CSS. In addition to the .tpl files you will have a style.css file and optionally, a variables.php file. The variables.php file allows you to override certain universal settings for this skin such as where blocks load and the graphics used for your ratings and featured stories.
A fewimportant things to pay attention to when modifying the template files:
Variables: Items in curly brackets are variables, 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 variables are required on some of the template pages and some are optional.
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:
<!-- INCLUDE BLOCK : newsbox -->
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:
<!-- START BLOCK : categoriesblock -->
Content goes here, which will also include attributes, such as {category} or {description}
<!-- END BLOCK : categoriesblock -->
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. Block declarations should go on lines by themselves.
Blocks vs. Blocks: The template blocks in the .tpl files are not the same as the blocks you configure in the admin panel. The blocks in the admin panel are "blocks" of code that generate content they place inside template variables. The blocks in the .tpl files are "blocks" of content. While there is some overlap, thinking of them as being separate from each other will help you keep things straight. Each "code block" will generate two "content blocks": {blockname_title} and {blockname_content}. You may or may not include the {blockname_title} variable in your skin. It's up to you. However, using the {blockname_title} in your skin means if you ever want to change the title of the block you only have to do it in one place instead of in each skin. You assign where the block will be assigned to in the admin panel. There are 3 choices:
You may also override these settings for an individual skin by placing information for that block in the variables.php file. More on that later.
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 file. Most of the template files begin with the header block and end with the footer block except for a couple of the blocks (newsblock.tpl, comments.tpl and listings.tpl)
Using "hooks" various 3rd party and included modules (such as challenges) can add their own variables to these templates. Check the documentation for the modules for specific additions.
Feel free to use the files in the default_tpls/ folder as templates for your own skins. Copy the files into a new skin folder and modify them there. Do not modify the files in default_tpls/ if at all possible. They're often used for diagnostic purposes if the site isn't functioning as expected. Also, you are in no way limited to CSS for the layout of your skins. Feel free to use tables to your heart's content.
This file controls the look of the browse pages (categories, classifications, etc.) The header, footer, and listing blocks are included in this file along with a block for the sort form that is displayed when there are story results. In addition you will want to include two other variables:
You will need to start by including the header block.
<!-- INCLUDE BLOCK : header -->
And end by including the footer block.
<!-- INCLUDE BLOCK : footer -->
{output} - Miscellaneous information on the pages including the page title.
{otherresults} - The list of other results (challenges, series, etc.) that fit the criteria for the page.
Within the sort form the following variables are used:
{sortbegin} - the beginning of the sort menu form
{charactermenu1} - A list of characters to choose from
{charactermenu2} - A second list of characters
{classmenu} - A dropdown list for each of the site's classification types (genres, warnings, etc.)
{ratingmenu} - A list of ratings
{sortmenu} - Choose how the stories will be sorted alphabetically or by most recently updated
{completemenu} - Choose all stories or only completed stories
{sortend} - the end of the sort menu form
You may include all or none of these and in whatever order you wish, except the {sortbegin} and {sortend} variables must be at the beginning and end of the list of variables in the form.
Sample:
The categories.tpl controls the look of the individual category on the categories browse page. Note: The appearance of the categories block is controlled separately through the block's admin panel.
The block must start with:
<!-- START BLOCK : categoryblock -->
and end with:
<!-- END BLOCK : categoryblock -->
The following variables are available to use in the block:
{image} - The image associated with that category. Note: The name of the image is set in the Categories admin panel. The image file must be in the skin's directory. If the script can't find the image it will display nothing. (In 1.1 a broken image was displayed.)
{link} - The link to the category's browse page.
{count} - The count of stories within that category.
{description} - The category's description.
Sample:
This block controls the display of comments on the news.php page for a single story.
You must start the file with:
<!-- START BLOCK : commentbox -->
and end it with:
<!-- END BLOCK : commentbox -->
This information should be placed on separate lines. Between these two lines the following variables should be included.
{comment} - The comment from the member.
{uname} - The member's name as a hyperlink to their profile.
{date} - The date the comment was made.
{adminoptions} - Options visible to the administrator when viewing the page.
The variable {oddeven} is optional, you can use it to assign alternating styles to each comment.
Sample:
The majority of pages use this for their layout. Most likely you won't need to include it in your skin at all.
You must include the header, listings, and footer block as seen below and include the {output} variable BEFORE the listings block. The {output} variable provides various text like the page title and alphabet list for titles. You will probably not need to replicate this file in your skin since there's nothing much to change really.
Sample:
In eFiction 3.0 when favorites are turned on by the admin, members have the option of not only marking a story as a favorite, but also including a comment as to why it is their favorite. The favcomment.tpl us used to display these comments in the user's profile.
The block must start with:
<!-- START BLOCK : comment -->
and end with:
<!-- END BLOCK : comment -->
In addition the following variables can be used within the block:
{comment} - The member's comment
{commentoptions} - Options concerning this comment for admin and the person who commented
{oddeven} - This variable can be used to style alternating comments differently.
Sample:
You must start the file with:
<!-- START BLOCK : footer -->
and end it with:
<!-- END BLOCK : footer -->
In addition to the universal page links, the footer.tpl also has one other variable assigned to it.
{footer} - Your copyright statement.
Content assigned to the footer in the admin panel or in the skin's variables.php file will also be included here.
Sample:
You must start the file with:
<!-- START BLOCK : header -->
and end it with:
<!-- END BLOCK : header -->
In addition to the universal page links, the header.tpl also has two other variables assigned to it. The use of these variables is optional.
{sitename} - Your site name
{slogan} - Your site slogan
Content assigned to the header in the admin panel or in the skin's variables.php file will also be included here.
Sample:
This file controls the look of your site's home/index page.
You will need to start by including the header block.
<!-- INCLUDE BLOCK : header -->
And end by including the footer block.
<!-- INCLUDE BLOCK : footer -->
In addition to the universal page links, the index.tpl also has one other variable assigned to it.
{welcome} - Your welcome message.
Content assigned to "index only" in the admin panel or in the skin's variables.php file will also be included here. The sample below creates a two column index page via positioning. See the style.css in the default_tpls for the leftindex and rightindex style declarations.
Sample:
This block is included in all pages where stories or series are listed such as titles, categories, user's profile page, search results, etc. It is an expansion of storyblock.tpl from 1.1.
You must start the file with:
<!-- START BLOCK : listings -->
and end it with:
<!-- END BLOCK : listings -->
In addition, the following variable should be included just above the end line:
{pagelinks} - If the results for the page require pagination, this variable will contain the list of page links.
This block contains 2 inner blocks that control the appearance of the individual series and stories.
Both the seriesblock and storyblock should contain the following variables:
{title} - Title of the story/series
{author} - Author (Owner if it's an open series) of the story/series
{score} - The story/series rating by members like/dislike or stars
{reviews} - A link to the reviews for the story/series
{numreviews} - the number of reviews linked to a listing of reviews for the story/series
{summary} - The summary for the story/series
{category} - The categories for the story/series
{classifications} - The list of classifications for the story/series (genres, warnings, etc.)
{characters} - The characters for the story/series
{reportthis} - A link to report problems, errors, etc. with this story/series
{addtofaves} - The option to add the story/series to favorites.
{comment} - Will be used for favorite stories and also in certain reviews pages to display comments and reviews about the story/series
Optional for both seriesblock and storyblock is the variable {oddeven}. This variable can be used to assign "odd" or "even" status to the block for CSS styling.
The seriesblock will have the following additional variables:
{adminoptions} - Options visible to the admin when viewing the page.
{open} - Whether or not the series is open to contributions from others (like a round robin)
{parentseries} - If the series is a sub-series of another, the parent series will be listed here.
{numstories} - The number of stories within the series.
The storyblock will have the following additional variables:
{adminlinks} - Options visible to the admin when viewing the page.
{serieslinks} - If the story is part of a series this will contain a link to those series.
{numchapters} - The number of chapters in the story.
{completed} - Whether or not the story is complete.
{wordcount} - The total number of words in the story (all chapters)
{toc} - A link to the story's table of contents
{count} - The count for the number of times the story has been viewed.
{roundrobin} - If this story is a round robin an icon will be displayed showing this.
{new} - If the site has set a "recent" date range new or updated stories falling within that range will be flagged a "New!" using this variable.
{featuredstory} - If the story is listed as a featured story or a retired feature story an icon will be displayed showing this status.
{published} - The date the story was published.
{updated} - The date the story was last updated.
Sample:
This block displays one news story, and will be called by the news block and is also used in the news archive page.
You must start the file with:
<!-- START BLOCK : newsbox -->
and end it with:
<!-- END BLOCK : newsbox -->
At a minimum, the following variables should be included in the block.
{newstitle} - The title of the news story
{newsstory} - The content of the news story
{newsauthor} - The author of the news story
{newsdate} - The date the news item was added to the site
{newscomments} - The number of comments the story has received with a link to view the comments.
Additionally, if you wish administrator options to appear when an admin views the story you should include:
{adminoptions}
Finally, if you want alternating stories to appear with different CSS options you can include:
{oddeven} - Where this variable is placed the word "even" will appear in even numbered stories and the word "odd" will appear in odd numbered stories.
Sample:
This template is used when the print story function is used. Generally this is another block that you can probably leave to the default_tpls. The following variables should be included in this template:
{title} - The title of the story
{author} - The author(s) of the story
{featuredstory} - The featured/retired icon will be displayed here if the story is featured.
{summary} - The summary of the story
{category} - The story's categories
{characters} - The story's character list
{classifications} - The other classification information for the story (genres, warnings, etc.)
{challengelinks} - The challenges to which this story is a response
{serieslinks} - The list of series to which this story belongs
{numchapters} - The number of chapters in the story
{completed} - Whether or not the story is complete
{wordcount} - The word count for the story
{count} - The read count for the story
{published} - The date the story was published
{updated} - The date the story was updated
{copyright} - The print version of the site's copyright notice
{archivedat} - A statement of where the story is archived at.
In addition to these variables there are several blocks included in this template. The storynotes block will be displayed if the story contains notes. It contains one variable, {storynotes}. The next block should be the storyindexblock. For multi-chapter stories, this will be the table of contents. The storyindexblock will be one chapter's worth of information about the story. The following variables can be included in the storyindexblock:
{title} - The chapter's title
{author} - The author of the chapter
{chapternumber} - The chapter number.
The next block will be the chapter information for each chapter. This block contains blocks inside it for the chapter notes and endnotes. The following variables can be included in the chapterblock:
{chaptertitle} - The title of the chapter
{chapterauthor} - The author of the chapter
{chaptertext} - The text of the chapter
{back2top} - An anchor back to the top of the document.
The notes block contains a single variable {notes} and the endnotes block contains a single variable {endnotes}. These blocks plus the storynotes block are placed in blocks so that html can be used around the blocks if the information is present and hidden when not.
Sample:
This template is used in the author's profile page. It's been separated out of the user.tpl so that it can be re-used in other panels if needed.
You must start the file with:
<!-- START BLOCK : profile -->
and end it with:
<!-- END BLOCK : profile -->
The following variables can be included in this file:
{realname} - The member's real name
{userpenname} - The member's penname
{membersince} - The date the member joined the site
{userlevel} - The member's user level Member or Admin (if the person viewing the page is an admin they will see the admin level)
{image} - The member's image from their bio information
{bio} - The autor's bio
{authorfields} - The list of admin defined author fields. i.e. aol, icq, etc.
{adminoptions} - A list of admin options about the member (visible only to admins)
{reportthis} - A report this link for the members profile
For each active authorfield, you will also have a variable for that information. For instance, if you've activated the AOL authorfield, the variable {aol} will also output the aol information for the member.
Note: this is for a non-bridged site. If you've bridged your site, the variables available to your profile will depend on how your bridge is set up.
Sample:
This block controls the display of an individual review. It's been separated from the reviews.tpl file so it can be re-used in other panels.
You must start the file with:
<!-- START BLOCK : reviewsblock -->
and end it with:
<!-- END BLOCK : reviewsblock -->
The following variables can be included in this file:
{reviewer} - The name of the reviewer
{member} - The words Signed or Anonymous depending on whether the reviewer was a member
{rating} - The thumbs up/down or star rating the reviewer gave
{reportthis} - A link to report trouble with this review
{reviewdate} - The date the review was given
{chapter} - The title of the item being reviewed (chapter if it's a story and the chapter is named)
{review} - The text of the review
{adminoptions} - Admin options for the review
Sample:
This block controls the display of the reviews page. This .tpl includes an inner block that formats the individual reviews on the page. The following variables are included in the reviews.tpl
{pagetitle} - The title of the page
{output} - Used for error and confirmation messages. Should probably be included just below {pagetitle}
{jumpmenu} - Displays the jump menu for reviews pages that require it.
{reviewpagelinks} - Used for pagination. Should be included AFTER the reviewsblock
{reviewslink} - Link inviting visitor to submit a review (Optional can use {reviewsform} instead)
{reviewsform} - The review form. (Optional can use {reviewslink} instead)
You will need to start by including the header block.
<!-- INCLUDE BLOCK : header -->
And end by including the footer block.
<!-- INCLUDE BLOCK : footer -->
Sample:
This template displays the title block information on a series page.
You must start the file with:
<!-- START BLOCK: series -->
and end it with:
<!-- END BLOCK : series -->
The following variables can be included in this file:
{pagetitle} - This will be the series title and author links
{rating} - The thumbs up/down or star rating for the series
{summary} - The series' summary
{category} - The category information for the series
{characters} - The characters for the series
{classifications} - The other classification information for the series (genres, warnings, etc.)
{parentseries} - If this series has a parent, this will be a link to the parent series
{numstories} - The number of stories in the series
{open} - The open status of the series
{adminoptions} - The admin options for the series
{addtofaves} - The link to add the series to favorites
{jump} - The dropdown list of options for the series.
Sample:
This template controls the story index (table of contents) for an individual story.
You will need to start by including the header block.
<!-- INCLUDE BLOCK : header -->
And end by including the footer block.
<!-- INCLUDE BLOCK : footer -->
The following variables may be included in this template:
{title} - The title of the story
{author} - The author(s) of the story
{reviews} - A link to the reviews for the story with the word "Reviews" as text
{numreviews} - A link to the reviews for the story with the number of reviews as the text
{score} - The thumbs up/down or star rating for a story
{jumpmenu} - The dropdown menu of chapters in the story
{featuredstory} - The featured/retired icon
{summary} - The summary of the story
{rating} - The story's content rating
{category} - The story's categories
{characters} - The list of characters for the story
{classifications} - The other classifications for the story (genres, warnings, etc.)
{serieslinks} - The list of series to which the story belongs
{numchapters} - The number of chapters in the story
{completed} - Yes or No depending on the status of the story
{wordcount} - The total word count for the story
{count} - The read count for the story
{published} - The date the story was published
{updated} - The date the story was last updated
{adminlinks} - The admin options for the story
{addtofaves} - The option to add this story to favorites
{roundrobin} - The option to contribute to the round robin
{jumpmenu2} - The drop down menu of options concerning the story
{reviewform} - A form to submit a review of the story
{reviewslink} - A link to review the story
In addition there are two included blocks. The first is storynotes which includes one variable {storynotes} for the story notes. The second is the storyindexblock. The following information can be included in the storyindexblock for each chapter of the story:
{chapternumber} - The chapter number
{title} - The title of the chapter
{author} - The author of the chapter
{reviews} - The reviews link for reviews for that chapter
{numreviews} - The number of reviews that chapter has received
{ratingpics} - The thumbs up/down or star rating for that chapter
{wordcount} - The word count for that chapter
{chapternotes} - The chapter notes for that chapter (end notes are not displayed)
{adminoptions} - Admin options for that chapter
Sample:
This page displays the user profile page.
You will need to start by including the header block.
<!-- INCLUDE BLOCK : header -->
And end by including the footer block.
<!-- INCLUDE BLOCK : footer -->
In addition you will want to include the profile block as well.
<!-- INCLUDE BLOCK : profile -->
The user.tpl file includes one other block used to form the "tabs" for the profile panels. You can build these tabs any way you wish. The sample below places them inside a div with each individual tab as a span. Another idea is to use an unordered list. Within this block you can use the following variables:
{class} - The class for that "tab" used to differentiate the current/active tab from the inactive tabs.
{link} - The link to the tab
{count} - The count of items in the tab (may be empty)
{linkcount} - The link to the tab with the count of items in the tab included in the link
In addition to these blocks, the following variables can be included:
{adminoptions} - Options regarding this member's account
{sort} - Gives the sort for when displaying the user's stories.
{output} - Used for various messages and errors in panels.
Sample:
This page displays the story/chapter text.
You will need to start by including the header block.
<!-- INCLUDE BLOCK : header -->
And end by including the footer block.
<!-- INCLUDE BLOCK : footer -->
Three included blocks are used to display the story notes, chapter notes, and chapter end notes.
In addition, the following variables may be included:
{title} - The title of the story
{author} - The author(s) of the story
{reviews} - A link to the reviews for the story with the word "Reviews" as text
{numreviews} - A link to the reviews for the story with the number of reviews as the text
{score} - The thumbs up/down or star rating for a story
{jumpmenu} - The dropdown menu of chapters in the story
{featuredstory} - The featured/retired icon
{summary} - The summary of the story
{rating} - The story's content rating
{category} - The story's categories
{characters} - The list of characters for the story
{classifications} - The other classifications for the story (genres, warnings, etc.)
{serieslinks} - The list of series to which the story belongs
{numchapters} - The number of chapters in the story
{completed} - Yes or No depending on the status of the story
{wordcount} - The total word count for the story
{count} - The read count for the story
{published} - The date the story was published
{updated} - The date the story was last updated
{adminlinks} - The admin options for the story
{addtofaves} - The option to add this story to favorites
{roundrobin} - The option to contribute to the round robin
{jumpmenu2} - The drop down menu of options concerning the story
{reviewform} - A form to submit a review of the story
{reviewslink} - A link to review the story
Sample:
.tpl file
Related pages
browse.tpl
Browse Pages
categories.tpl
Browse Categories
comments.tpl
News
default.tpl
Most pages
favcomment.tpl
Favorites Lists
footer.tpl
All pages
header.tpl
All pages
index.tpl
Index
listings.tpl
Any page listing stories or series
newsbox.tpl
News & news block
printstory.tpl
View Story (Printable)
profile.tpl
User Profile
reviewblock.tpl
Reviews
reviews.tpl
Reviews
series_title.tpl
View Series
storyindex.tpl
Story Table of Contents
user.tpl
User Profile/Info
viewstory.tpl
View Story
Status
Associated .tpl file
Inactive
The block is off.
Active
The block is on. Can appear on every page.
Index Only
Appears on the index page only.