Making and Customizing Themes for Rilke CMS Jayesh Sheth [jayeshsh [at] ceruleansky.com] http://www.rilkecms.com

July 15, 2003 - First Version

This document contains a  a brief summary of how themes in Rilke CMS work This document is a work-in-progress and will be replaced with more detailed information as it is updated.

What are Themes?
A Theme lets you personalize the look and feel of your Rilke CMS powered site. Themes in Rilke CMS consist of standard HTML, CSS and some embedded PHP.
Where are Theme Files Located?
Each Theme has its own folder, and is located under the main themes folder.

The name of a theme folder is the same as the name of the theme. For example, the files for the "illusion" theme are located in the illusion folder. So, for example: http://rilke.yoursite.com/themes/illusion/

What Kind of Files Make up a Theme?

The files in a theme folder have the following extensions: .php, .css, and .png.

Each theme folder should have four .php files, with the following names:
index.php [ Holds the main page's content ]
submit.php [ Allows a website visitor to submit content ]
categories.php [ Allows a website visitor to view all the categories defined for a site, and the posts in each category]
allposts.php [ Allows a visitor to browse all posts which have been posted to the site ]

Each theme folder should also have two image files. If your theme is named Illusion, your image files will be:
illusion.png [ full screen image of the theme being used]
illusion_tn.png [ thumbnail of the theme being used (recommended size: 100 x 54 pixels) ]

Most themes also contain a CSS file with the same name as the theme name, i.e. illusion.css.

How do I Create a New Theme?

If you want to a create a new theme called "Spiffy", perform the following steps:
1) Create a new folder called spiffy, under the existing themes folder. For example, the spiffy folder would be located at:
http://rilke.yoursite.com/themes/spiffy/
2) Copy all the files from the themes/default folder to this new folder
3) Open up the four .php files - index.php, submit.php, categories.php and allposts.php and look for embedded PHP tags such as the following:
<?php echo $title . " - " . $header ;?>
Do not edit any such tags.  You can safely edit other non-PHP HTML tags.
4) The easiest way to customize the design is to simply edit the css file which was copied over (in this case illusion.css). I recommend TopStyle ( http://www.bradsoft.com ) for editing CSS files such as this one.
5)When you are done, upload the new spiffy folder to the themes folder at your webhost.
6)Log in to the Administration Screen, and click on "Themes" at the top.
7)Choose the "Add New Theme" link and type in the name of the new theme you are adding. In this case, type "spiffy".
8)Press tab to go to the next text input field, and the path to the theme will be automagically filled in.
9)Press the add new theme button, and if all goes well (if it can find the Theme files),  the new theme will be added.

How do I Remove a Theme?

Currently, you cannot remove a theme from the Administration Panel directly. I plan on adding the user interface for this in the upcoming 1.0 version. (Before the 1.0 version there will be other incremental versions). You can remove a theme manually by following the following steps:

1. Set a theme other than the one you want to delete as the default one by going to "Themes" in the Administration Screen.
   
2. Using PHPMyAdmin, you can remove the entry for a particular Theme by deleting its reference in the themes table. (Please check prefs.php for the name of the themes table if you chose a different one when you generated prefs.php). Great caution is advised if you choose delete a Theme row manually.
3. Once you have deleted the reference to the theme from the Themes table, you can remove the folder which contains its files. For example, if you are removing the "Illusion" theme, you can delete the following folder: http://rilke.yoursite.com/themes/illusion/

How can I use an Existing Design as a Theme (adding Rilke CMS PHP tags)?
You can use any design  that you have already created as a Rilke CMS Theme. Also, you can adapt a theme you download from oswd.org or  Blog Your Design but you will need to add in the necessary Rilke CMS PHP tags to them. These tags help Rilke CMS indentify which information is to be pulled from a database (such as the title and content of the currently viewed post) and the information which is pulled from the preferences file (such as the site's name).

Which Rilke CMS PHP tags do I need to add to my Theme files?

In the following examples, HTML tags are in red, PHP tags are highlighted in in yellow:

Common PHP Tags:
The four .php files ( index.php, allposts,php, submit.php, categories.php ) all contain the following PHP tags:

• Title Information:
  <?php echo $title . " - " . $header ;?>
  
  Usage: Place this between the HTML <title> tags. Eg: <title> <?php echo $title . " - " . $header ;?> </title>
• Navigation :
  
  The following navigation links are present in all .php theme files. The are the links found usually at the top of the page, and point  to the site's main sections.
  
  <a href="index.php">Home</a> <a href="allposts.php">All <?php echo $entry ;?>s </a> <a href="submit.php">Submit <?php echo $entry ;?></a> <a href="adminpear/">Login</a>
  

index.php PHP tags:
The index.php page, which holds the front page's information contains the following PHP tags:

• List Recent Posts:  <h3>Recent <?php echo $entry ;?>s:</h3>
  <?php include("lib/archives2.php");
  archives(5,"desc","index.php");
  ?>
• Display Selected Post, Comments and  Related  Posts:
  
  Important note - two versions of this PHP code block are listed below. The first is for the existing 0.82 version of Rilke CMS. Due to changes in the upcoming 0.83 version, this PHP code block is due to change. The code block for the upcoming 0.83 is listed thereafter.
  
  Content Block for version 0.82 :
  <?php
  $output = displaypost($date, $header, $content, $last, $link, $next, $category, $showrelated = true, $id);
  echo $output;
  ?>
  
  Content Block for the upcoming version 0.83:
  <?php
  $output = displaypost($date, $header, $content, $last, $link, $next, $category, $showrelated = true, $id, $author, $editauthor, $edate);
  echo $output;
  ?>
  

submit.php PHP Tags:
The submit.php file, which holds the form which lets site visitors submit posts for approval, contains the following tags:

• Submit Form Block:
  <h1>Visitor Submitted Posts</h1>
  <?php include("lib/visitorsubmit.php") ;?>

allposts.php PHP Tags:
The allposts.php file, which displays all the posts currently entered into the site, contains the following tags:

• Archives Block:
     <?php
  
  if (!(isset($start_at)) || !(is_numeric($start_at)))
      {
      $start_at = 0;   
      }
     
  require_once("lib/archives_pag2.php");
  archives_pag("desc","index.php",$start_at,10 );
  ?>

categories.php PHP Tags:
The categories.php file, which displays all the categories for posts (and the posts contained in each category), contains the following tags:

•  Categories Block:
  <?php
  require("lib/categories.php");
  if (!(isset($c)))
      {
      $c = "all";   
      }
  listcategories($c);
  ?>
  

More detailed documentation, and a browser-based Themes generation wizard that will automatically insert the necessary PHP tags into your existing HTML design (similar to the installation wizard) are planned.

It is hoped that this beginning information helps. Detailed Theme information is set to follow. If you need help integrating an existing design as a new Rilke CMS Theme, please contact Jay Sheth using the address listed above.