Styles

Applying Styles

A style defines how your blog appears to the users. There are some bundled themes with serendipity and are fully based on Cascading Style Sheets? (CSS) for customization.

To choose how your blog looks like, enter your Administration Suite and click on the Manage styles item. There you will see an overview of existing templates. You can see the original author of the theme and maybe even a small screenshot. Choose the radiobutton next to the style you want to have and click on Save. On the next page relead you'll see your blog in the desired layout.

If you want to leave it up to your visitor how your blog looks, consider using the Template Dropdown Sidebar plugin.

Template, Style, Theme...?

Yes, we know - we definitely need to work on our terminlogy. We are currently using all the three terms Template, Style and Theme to refer to actually the same thing. There's no difference in them, only that different developers used different terms.

Creating a style

It's very easy to create your own style. All the available styles are saved within the templates subdirectory of s9y. Each style has its own subdirectory there.

It is advised for creating a new style that you take an existing subdirectory, copy it to a new directory and then modify the files. Serendipity will always fall back to the default template file, if your theme doesn't have one. This way you can keep redundant code outside of your template, and only customize the files you really want to customize.

You can only use Smarty templating for the frontend. The look of the admin interface can only be affected via CSS. This is mainly because enhancing the admin interface with templates is a lot harder and would create more maintenance overhead. It would also hurt performance, and when your server has trouble with the Smarty application you will still have the opportunity to use the Admin interface.

Inside each style subdirectory, there are several files:

Creating the CSS files

Most important, the CSS files which immediately define the look of your page.

style.css, admin/style.css, admin/pluginmanager.css

This stylesheet contains all CSS definitions for both the frontend and backend pages of your weblog.

atom.css

This stylesheet is applied to your RSS/XML syndication link, if users choose to view the Atom version. This stylesheet is cut cown to only a few elements which apply to given XML directives.

htmlarea.css

If you are using the WYSIWYG-editor for creating your entries, you may want to have the area look like on your homepage. You can modify all the CSS classes inside this file to tweak the look of that area.

Creating info.txt

Inside this file you can insert your credits, which are displayed in the s9y backend.

Creating preview.png

To easily see how your template looks like, you should later make a small screenshot of your layout and save it as preview.png file.

Creating dragdrop.js, imgedit.js, treeview/, YahooUI/

Those files are the bundled Yahoo UI components that are used for showing the media database drag+drop functionalities.

layout.php

This layout.php file is a deprecated way of Serendipity prior to version 0.8, where no Smarty features existed yet. The layout.php mechanism is STILL avaiable to your themes, putting them in 'raw/backwards compatibility mode'.

Basically, you don't need to edit those layout.php files any more, they are no longer required. Most things are now done via specific Smarty .tpl files. The only upside the layout.php brings to your theme is that you can use PHP code in that file to control the "workflow" of your page. So you can have a look at the templates/newspaper/layout.php file for an example of how such a file can still look - but you don't really need to understand that part any more.

Editing the Smarty *.tpl files

There are various *.tpl files that hold the smarty template code for display HTML and logic.

For various variables, refer to this documentation [1] or a Editing Tutorial [2].

commentform.tpl

This file controls the look of your comment form where visitors can comment on your entries.

commentpopup.tpl

This controls the basic HTML layout of the optional comment popup window.

comments.tpl, trackbacks.tpl

This shows the available comments and trackbacks made to an entry.

comments_by_author.tpl

This controls the layout of the functionality where comments by visitors are shown.

content.tpl

This is a master template that holds your page content area, and depending on the page type (entries overview, entry search, archive page, ...) emits different messages.

entries_archives.tpl

This file holds the display of entry archives (per month / year).

entries_summary.tpl

This file displays the overview of entry archives (per month/year).

feed_*.tpl

These files hold the various RSS/Atom feed template files. Here you could add customization to those feeds.

index.tpl

This is the main template file that controls the general look of your page as well as HTML headers, meta tags, CSS embedding, sidebar locations etc.

entries.tpl

This is the main logic file and it tells Serendipity how to format your entry overview, how to loop entries, where to show commentsforms etc.

plugin_calendar.tpl, plugin_categories.tpl

Some plugins allow their own templating. Those files are prefixed with "plugin_" and can also come with certain plugins. Putting those files into your template directory will customize the look of that plugin within your theme. The files available by default for bundled plugins are for the Calendar and Categories sidebar plugins. You first need to enable the templating option in the configuration of those plugins, though!

preview_iframe.tpl

When you create a preview from within the admin interface, this file controls the basic look of the embedded iframe holding the preview. You need to adapt this file of your preview looks odd/off.

sidebar.tpl

This file controls how the list of sidebar plugins is displayed.

config.inc.php

This master PHP file can customize options only available with PHP coding in your theme.

For a possible use of this, check these documents: Special Smarty Templating [3] and Configuration of Theme options [4].

Styling the media manager

The media manager is the only part of the admin interface that is Smarty customizable.

The files for this are in the admin/ subdirectory of your theme:

media_choose.tpl

The main template file of the media manager popup window.

media_items.tpl

The display logic of the specific items in your media database overview.

media_pane.tpl

The header/footer area of the media database overview.

media_properties.tpl

The page which displays properties (keywords, exif-information etc.) of a selected image.

media_showitem.tpl

Used when displaying an image via the frontend of your blog to visitors.

media_upload.tpl

The template file for uploading a single or multiple images.

media_imgedit.tpl, media_imgedit_done.tpl, imgedit.css

The files responsible for "editing" an image. Currently still in development.

Creating images

Inside the img subdirectory of your template directory you can place a list of common images:

back.png

This image is used for the calendar plugin as the back arrow

forward.png

This image is used for the calendar plugin as the forward arrow

xml.gif

This image is used for indicating XML file links (like for the syndication and categories plugin)

cry_smile.gif, embaressed_smile.gif, omg_smile.gif, regular_smile.gif, sad_smile.gif, shades_smile.gif, teeth_smile.gif, tounge_smile.gif, wink_smile.gif

Various emoticons which are used by the Emoticate Event Plugin to transform text-smilies into graphical representations. You may want to tweak those to match your template look.

To customize smilies with individual images from a theme, you can

create the file 'emoticons.inc.php' inside this template directory

and use an array like this:

[code]

<?php

$serendipity['custom_emoticons'] = array(

":'(" => serendipity_getTemplateFile('img/cry_smile.gif'),

':-)' => serendipity_getTemplateFile('img/regular_smile.gif'),

':-O' => serendipity_getTemplateFile('img/embaressed_smile.gif'),

':O' => serendipity_getTemplateFile('img/embaressed_smile.gif'),

...

);

?>

[/code]

This will override the default list of emoticons set inside the file plugins/serendipity_event_emoticate/serendipity_event_emoticate.php and use the ones you created for your template.

Available Style IDs/Classes

Commonly used HTML elements

We use the <h1> element for the header of a page, the <h2> element for a subheader. <h3> elements are used for the entry dates and <h4> elements for the titles of each entry.

Sidebar plugins are used, depending on your layout.php, within either <table> elements or <div> containers. Depending on that, subcells are either <td>s or <div>s again.

All other HTML elements can be styled in context of either a surrounding element with a Class or an ID

.emoticon

A smily, created by the Emoticon Markup Event Plugin.

#serendipity_banner

The top area of the page, containing your blog title (<h1>) and description (<h2>).

a.homelink1, a.homelink2

Surrounding anchor elements for your blog title (<h1>) and blog description (<h2>).

.serendipity_calendar

Surrounds the calendar plugin table (containing <td> and <tr>s).

td.serendipity_weekDayName, td.serendipity_calendarHeader

Cell containing either the weekday or the header

td.serendipity_calendarBlankDayFirstInRow, td.serendipity_calendarDayFirstInRow, td.serendipity_calendarBlankDay, td.calendarDay, td.serendipity_calendarBlankDayLastInRow, td.serendipity_calendarDayLastInRow

(Empty) Day area.

#mainpane

This contains the main serendipity contents, including sidebars.

#content

Contains the main serendipity entry list

#serendipityLeftSideBar

Contains the full left sidebar area

#serendipityRightSideBar

Contains the full right sidebar area

.serendipitySideBarItem

Inside context of the Left Side Bar? or Right Side Bar?, this surrounds each plugin.

h3.serendipitySideBarTitle

Inside context of serendipitySideBarItem, the title area of each plugin sidebar component.

.serendipitySideBarContent

Inside context of serendipitySideBarItem, the content area of each plugin sidebar component.

.serendipity_Entry_Date

Wraps around all articles for a single day.

h3.serendipity_date

The date field header

h4.serendipity_title

The title of each entry.

.serendipity_entry

Wraps around the complete articles contents

.serendipity_entry_body_folded

Wraps around the teaser text of the article. Only used in article overview, not in detail mode.

.serendipity_entry_body_unfolded

Wraps around the teaser text of the article. Only used in article detail mode, not in overview.

.serendipity_entry_extended

Wraps around the extended text of the article. Only used in article detail mode.

.serendipity_entryFooter

Contained within serendipity_entry this holds all detail information about the author (posting date, name, ...)

.serendipity_commentsTitle

Title for the following commentarea

.serendipity_comment

Comment area in detail view of an article. (per-comment)

.serendipity_comment_source

Holds detail information about the comment author

.serendipityCommentForm

Surrounds the form for entering a comment.

.serendipity_commentsLabel

For the comments page, spans around the title of each input fields description.

.serendipity_commentsValue

For the comments page, spans around the value area of each input field.

#serendipity_comment_page

The surrounding area on the single comment popup.

.serendipity_imageComment_center, .serendipity_imageComment_left, .serendipity_imageComment_right

When using comments for images given in the s9y image manager. Inside .serendipity_entry, surrounding the whole comment box.

.serendipity_imageComment_img, .serendipity_imageComment_txt

The nested parts within .serendipity_imageComment_* to seperate comment from the actual image.

#serendipity_admin_entries_page, #serendipity_admin_image_page, #serendipity_admin_page

Backend: The full page area for the Authoring Suite, the Image Manager and the Administration Suite.

.serendipity_Admin_title

Backend: Title of the backend page

.serendipity_Admin

Backend: Content area

That's too much!

Even though there are lots of combinations or variations possible with those IDs/classes, you may easily get confused when dealing with CSS. Try out Mozilla Firefoxes EditCSS [5] for seeing how easy that actually can be!

I want MORE! All the trouble, all the FUN!

This page only described how you can easy Smarty/HTML code to mockup your blog.

If you want more features like distinct page HTML things, navigation items or custom functionality, you will need to get yourself familiar with the awesome Serendipity Plugin API [6] and the various Event Hooks [7].

Or have a look at all the already existing plugins and themes in the Spartacus repository [8].

Even though there are lots of combinations or variations possible with those IDs/classes, you may easily get confused when dealing with CSS. Try out Mozilla Firefoxes EditCSS [5] for seeing how easy that actually can be!

Contributing!

If your style is finished, why don't you contribute? it? :-)

URL of this document:
   http://www.s9y.org/44.html

Links:
   [1] http://www.s9y.org/102.html
   [2] http://www.s9y.org/121.html
   [3] http://www.s9y.org/78.html
   [4] http://www.s9y.org/137.html
   [5] http://editcss.mozdev.org/
   [6] http://www.s9y.org/43.html
   [7] http://www.s9y.org/116.html
   [8] http://spartacus.s9y.org/

Driven by coWiki 0.3.4 web collaboration tool.