Search the Manual:

6. Designing for Bistro

This section of the manual is intended for website designers and developers who will be creating new design themes or significantly modifying existing design themes.

We have tried to make the process of designing layouts and websites using Bistro as close as possible to the process many web designers follow for any traditional web site. It is entirely up to you which tools you use.

You may choose to

All of these options are feasible alternatives - the choice is up to you. Whichever you choose, this section of the manual will help you convert your finished design into a great Bistro theme as part of your regular design approach.

You can navigate through this section of manual by scrolling through this page, accessing the menu tree on the left side of each page, or via the Table of Contents page.

6.1 Theme Design

Let's start with some terminology:

Theme: In the context of Bistro, a theme is an entire web site design; it is a collection of files stored within their own folder within the Bistro themes folder. A theme can include any combination of template, CSS, JavaScript, Flash and images files.

AutoStuff™: AutoStuff tags are short pieces of code that dymically pull content elements into your theme or into individual pages throughout your website. Click here for a list of available AutStuff tags in Bistro

Template File: A template file is a single HTML file that includes a few Bistro AutoStuff tags that allow Bistro to inject content elements into the layout.

In order to create a theme, you have to complete the following steps:

Although this may seem like an involved process, it really is quite simple once it is broken down.

The next section breaks these steps down in more detail. Alternatively, you can skip to section 6.3 The Minimum Requirements for the condensed version of these steps.

6.2 How to Create a Theme

In essence, the process of creating a theme is identical to the process you would normally follow for creating a single HTML web page, with the exception that you need to follow some simple guidelines, and plug a few key words into the HTML file to turn it into a theme. Some designers will choose to use a text editor to create their HTML and an imaging program to create their graphics, and others will choose to use something like FrontPage or Dreamweaver; either direction is possible, you can choose which suits you best.

6.2.1. Create a folder using your theme's name

To begin creating a new theme, create a folder and give it the same name that you would like to give your theme. The folder name will be what Bistro users see when they are choosing a theme. Also, this folder will be uploaded to your FTP site, so it is recommended that you avoid using special characters and spaces.Some Examples:

Good name: MyNewTheme
Bad name: My New Theme
Worse name: Mŷ Ńėw ThėmƏ!!

6.2.2. Design the layout and save it as an HTML file in your theme folder.

You can use any combination of tools as long as, at the end of the design process, you can save the design as an HTML file. Keep in mind, this means that you should avoid designing a site completely in Flash.

For your first theme, we suggest that you keep it simple and go with a single template. This means you should try and design pages that have consistent graphics and navigation on every page. If you design different section of the website with different layouts and graphics, each will need their own template file.

While you're designing your site there are a few things that you can do to make the design easier to convert into a theme.

  • Place all page content into a single container. For example, place all the content in one DIV element or in one cell of a table. Splitting up the content into multiple blocks will make your content more difficult to update and will hamper Bistro's ability to perform some automated actions like searching.
  • Keep layout elements consistent between pages on your website. Moving things around too much between different pages makes the theme more challenging to maintain.
  • Be sure that you are using relative paths to all your external files. In order to have Bistro automatically find your resources, and to ensure that you can edit your layout comfortably, you must reference your images using relative URLs. For example, if you have a subfolder named images, and you have an image named logo.jpg within that folder, you should reference it in your template file as follows:
CORRECT: images/logo.jpg
INCORRECT: /images/logo.jpg
INCORRECT: http://www.mydomain.com/images/logo.jpg
INCORRECT: ./images/logo.jpg

As another example, if you are keeping your CSS in a separate folder called css and your images in a folder called images, you would reference the images from the CSS as follows:

CORRECT: ../images/logo.jpg

INCORRECT: /../images/logo.jpg

INCORRECT: http://www.mydomain.com/images/logo.jpg

INCORRECT: ./images/logo.jpg

  • Avoid using automatically generated special effects. Some applications like Dreamweaver and FrontPage make it easy to include rollover buttons, dropdown menus and other special effects. Be careful when including these elements in a Bistro template as some of them are not always compatible with all Bistro features. For example, Bistro includes a module that allows you to easily edit your menu. The rollover effects created by Dreamweaver generate image references that are challenging for the Menu Manager to manipulate automatically.

6.2.3. Add the required AutoStuff tags into the template file.

In order for Bistro to automatically place content within your layout, there are several AutoStuff tags that you must place within your template's HTML code. AutoStuff is one of the most powerful features of Bistro.

AutoStuff tags are keywords that are replaced with text or HTML content when a site is displayed to a visitor. An example of AutoStuff is , which will be automatically replaced with the name you give your website in the System Setup area of Bistro.

To set up your template file, there are a few tags that are required. These tags and what they will display are:


Place this statement where you would like the content of your pages to be displayed. This will automatically be replaced with content as a page is rendered.

 


Place these statements within your meta tags. These tags will automatically be replaced with the description of the site and the content being viewed by the site visitor. Although excluding these tags won't break your site - it would be a shame if the keywords and descriptions created by the site weren't used.

The Proper way to use these tags are and

 


Place this statement where you would like the title of your pages to be displayed. This will automatically be replaced with your page title as a page is rendered.

The Proper way to use this tag is

 


Place this statement within your "head" tags, but before any CSS files or JavaScript files that you include. This statement will be replaced with CSS declarations and JavaScript defined by Bistro and, by placing it before your own declarations, you will be able to overwrite any of the default styles and code that Bistro generates.

In addition to these key AutoStuff tags, you will want to review optional AutoStuff tags and other PHP statements that offer greater design flexibilty.

6.2.4. Rename the file to default.php

PHP is the programming language in which Bistro was written. In order for Bistro to be able to replace all the key tags with the content of your website, you need to change the extension of the template file from a .html or a .htm file, to a .php file. Furthermore, it is important that this file be named default.php because Bistro will always look for at least one template file named default.php. If you name it differently, Bistro won't know what it is called and won't be able to include it, so your theme will not work.

6.2.5. Copy any necessary CSS declarations to wysiwyg.css

If you are using CSS to modify the appearance of default styles or to add new classes, you may want to save some of these CSS definitions in a separate CSS file named wysiwyg.css within a sub-folder of your theme named css.

Bistro uses a WYWIWYG editor so that end users can edit pages just as they would using a common word processor; however, the default layout of that editor uses Times New Roman as the font on a white background. If your site uses a different combination of fonts, colours and backgrounds, you should define them in wysiwyg.css so your users are not confused when they go to edit their pages. If your theme has a wysiwyg.css file, this file will be imported into the WYSIWYG editor within Bistro, so that when users edit pages or items, their text will resemble the text as it would appear on the site, and the custom CSS classes you have defined will be available to them within the Styles options.

For example, if you have defined a custom class called myCoolHeader, if you would like to make this style available to users editing their pages, be sure to define it within the wysiwyg.css file. Because the WYSIWYG editor is only editing the content area of your site, the definitions in wysiwyg.css may not be identical to the definitions within the rest of your theme; as such this file generally isn't used in the public display of your website.

6.2.6. Add or replace any optional AutoStuff into the template

AutoStuff is one of the most powerful features of Bistro. Although the use of it is entirely optional, if used correctly it can greatly simplify your web design process. In short, AutoStuff are keywords that are replaced with HTML content when a site is displayed. A good example is one piece of AutoStuff made available by the Event Calendar module: . If you place that phrase in your template file, it will be replaced with an automatically-generated calendar of the current month. Similarly, there are AutoStuff keywords for several URLs and several key components.

For example, in your template, you may include an image that links to the Contact Us page on your website - if you were creating a traditional site, you would create a link to a file called contactUs.html. However, because Bistro stores all the pages in the database, you would have to create a link to a script, which may look like index.php?module=4h4u8&pageId=contact1. You can simplify this step by linking to the AutoStuff keyword .

So, in full HTML:

would become

The reason this is useful is that it is easier to read, and it allows you to design themes that work across multiple sites and across multiple different configurations. Since, on different sites, different modules may be installed, if you use AutoStuff, you don't need to worry about module ID's or specific syntax at all! Bistro takes care of it for you!

Click here for a full listing of available AutoStuff entries.

6.2.7. Upload your theme to the web site

The final step in the process is uploading your theme to the website. When you connect to your website through FTP, you'll see that there is a folder called themes. If this is a brand new install, you'll see several subfolders within that folder, for example chlorophyll and rockOut. Each of these subfolders is a separate theme. All you need to do to install your new theme is to upload your theme into its own subfolder within the themes folder.

And that's how you can design your own theme. To review these steps, we highly recommend you review the following sections on the minimum steps required, as well as our recommended best practices. There is a lot of flexibility in how you choose to design your theme, but if you follow the best practices we've outlined in this document, it will help keep your theme consistent and easy to maintain.

6.3 The Minimum Required Steps

Although the steps mentioned above can seem daunting, it's actually very easy to get a theme up and running in a couple of steps. To get a basic theme up and running, all you need to do is create a new folder for your theme inside the themes folder, then complete these two steps:

6.3.1. Create a folder using your theme's name

Avoid spaces and special characters

6.3.2. Design the layout and save it as an HTML file in your theme folder

6.3.3. Add the required AutoStuff tags into the template file.

6.4 Recommended Best Practices

In addition to the three required steps mentioned above, there are a number of best practices we recommend that will help simplify your theme development, as well as improve the quality of the themes you create.

6.4.1. Folder Structure

All themes provided by Lewis Media adhere to the following folder structure. If you follow the same structure, it will help you better manage your themes, and more easily share ideas and themes with other designers.

3 Themes that are provided for download by Lewis Media include all source files including AI, PSD, and FLA files. However, due to the size of these files, they are not automatically included in Bistro install packages.

6.4.2. Layout Source Files

If you are preparing a theme to be shared with other designers, or if you are storing a local backup of your theme, we recommend that you store all source files used to create the theme in a subfolder named sources within your theme folder. Once you prepare your theme to be uploaded to a website, we recommend you do not upload your theme sources. Because theme files must be stored in a folder that is web-accessible, any source files you upload may become available to public visitors on your website. Also, because of the large file size of many source file types, uploading source files may lead to disk space issues within the web site's hosting account.

6.4.3. Prevent Directory Browsing

In order to help secure your theme folders against malicious users, it is recommended that you include a blank file named index.php or index.html within each folder of your theme. Including such a file will prevent malicious users from navigating to your theme's folder using their web browser and learning sensitive information about the website you are developing.

6.4.4. Autostuff

The best way to link to content within a Bistro website, is to use AutoStuff rather than manually entering fully qualified URLs, or using PHP code to calculate links directly. The reason for this is that using AutoStuff will allow your website to update links and items automatically, and will make your website more resilient to items that are deleted or moved.

For example, to insert a link to the most recent post on your web site blog, rather than using the usual HTML reference,

we recommend you use the following AutoStuff entry:

If you were to use traditional HTML every time a user adds a blog entry, you would have to update the link manually. If you use AutoStuff, however, that AutoStuff tag will be replaced with the appropriate link automatically and will display the most recent post in your blog.

A full list of available AutoStuff entries is included here in Section 9.3 AutoStuff Entries.

6.4.5. XHTML Transitional Code

Lewis Media, by default, provides code that is XHTML 1.0 Transitional4 compliant. Although content generated by Bistro typically works well with other standards, we recommend you try to adhere to the same specifications to increase the likelihood of a smooth theme design.

4 As specified by the W3C, http://www.w3.org

6.4.6 PHP Statements

Beyond the PHP Statements mentioned in this section, there are a number of additional PHP statements that may be used. These are listed in Section 9.2 - Additional PHP Statements

6.4.7 Use Messy URLs

Bistro automatically converts messy URLs to search-engine-friendly URLs. When creating a link to a page, if using AutoStuff is not a viable option and you must use a URL to link to content, be sure to use the messy url (as in "index.php?module=3nb483&id=37h373") rather than the friendly URL (as in "/myNewPage.html").

The reason for this is that search-engine-friendly URLs is an option that can be disabled, and any friendly URLs that are hard-coded into a template file will not be properly interpreted when this feature is disabled. If messy URLs are used, the URLs will function whether search-engine-friendly URLs are enabled or disabled.

6.4.8. Make module-specific content conditional

If you are including module-specific content within your theme, we recommend that you wrap the content in a conditional statement, which will allow you to make your theme more transportable, and will keep your theme functioning smoothly in the event that the module you're referencing is uninstalled.

For example, if you were including a stylized box that contains a mini-calendar (pulled in using the appropriate AutoStuff tag) from the Event Calendar/Listing module, your first inclination may be to do it as follows:

Although this is all syntactically correct, if the Event Calendar/Listing is uninstalled, then the AutoStuff will not be translated. In this case, visitors viewing the website would see an empty DIV with the words displayed. Instead, we recommend that you make the entire stylized box conditional by using the isInstalled helper function. Note: more helper functions are provided in Section 9.2 - Additional PHP Statements

 

6.5 Potential Pitfalls

When designing themes for Bistro, there are a few common pitfalls that you may encounter. We've tried to outline the most common below, and we are always open to suggested additions. Let us know if you have encountered something that you think belongs on this list.

6.5.1 Parsing Errors if XML Line is Unbroken

Earlier we recommend that you create XHTML compliant themes. A key part of this compliance is the first line - the XML encoding line. In full, the line reads:

However, you may notice that in our themes, we have written the line as:

The reason for this discrepancy, is that Bistro processes the template files as PHP scripts. The first version of this line, if included in a PHP script, would cause errors. As such, we've broken it up to make sure that we don't encounter problems.

If you create a template file with this line as it appears in the first example, you will likely encounter errors as well. The way to correct this is to replace it with the second version. An alternative to this full statement, however, is to use the XML header AutoStuff tag which will be automatically replaced with the code as above.

6.5.2. Omitting Title & Meta Tags

During your design process, be sure to include the AutoStuff tags for the page title, keywords and description. It's amazing how small this item seems, but it can be a shocking realization for a website owner when their website doesn't include the search engine optimizations they have provided and expect.

As a refresher, these tags are:

The following is an example of how the beginning of your template files may look, if you use a format similar to the themes developed by Lewis Media:

 

6.5.3. Invalid Paths

For many designers, this is a common error for the first few themes that they design. As described in 6.3 The Minimum Required, it is important that images, CSS files and JavaScript files are referenced using relative referencing. Any absolute referencing may result in broken images and links.

 

6.5.4. Fully-Qualified URL's not Search Engine Friendly

Bistro has a built in feature called Search Engine Friendliness. When it is enabled, all URLs will automatically be replaced with "pretty" URLs, for example a link to

May be replaced with the much more friendly link

Sometimes though, if things aren't properly configured, this replacement doesn't work. The most typical reason for this malfunction is that the designer has used fully-qualified URLs for links.

Bistro will only replace links to pages within the website you just created, so if you create a link to an outside website, it won't be replaced. This means, that if you create your link to http://www.myserver.com/index.php as opposed to just  /index.php, Bistro may believe the link is to an outside page and thus not replace it.

Use relative URLs to ensure the Search Engine Friendliness feature can work.

6.5.5. Fonts not Displayed in WYSIWYG Editor Correctly

Bistro comes with a built-in editor so that when you are editing pages and content for other modules, you can edit it like a word processor. By default, it starts off with a white page, black text, using Times New Roman as the font. As you can expect, this is not the font and colour combination of choice for many web sites. If you have a theme that displays pages with fonts and backgrounds other than this, you can tell the WYSIWYG editor about these settings by creating a wysiwyg.css file and placing it within a css subfolder within your theme. This is explained in more detail in section 6.4 Recommended Best Practices.

6.6 Tips & Tricks

6.6.1. Display the Current Date

To display the current date in your theme, all you need to do is add the follow AutoStuff tag:

This will be replaced with the current date formatted according to the preferences you selected in System Setup. If you want more control, however, you can also use this snippet of PHP code:

This will display the current date, formatted like March 10, 2006. The letters F j, Y tell the system how to display the date. You can learn more about which special characters to use from the PHP website, but here are a couple of popular formats with their related output.

6.6.2. Homepage Only Content

Sometimes you may want to include content in your theme that only shows up when someone is viewing the home page of the website. The way to do this is to enclose your display items in conditional statements. The following is an example of some code that will display the words "Welcome Home" in bold when viewing the homepage.

6.7 Addtional How‐To Tutorials

The following how-to tutorials are being prepared for inclusion in this manual. For more information on the progress of these tutorials, contact Lewis Media.

6.7.1 How To Include a Menu

The easiest way to include a menu is to use one of the AutoStuff tags to display your menu, then to customize the CSS classes as required. To see the list of AutoStuff tags available for your menu, see the Menu Manager area of Section 9.3 AutoStuff Entries.

6.7.2 How To Create a Custom Form

The easiest way to create a custom form in Bistro is to simply create a form like you normally would, but to not specify an action. You can design your form in a software package like DreamWeaver, or you can create it by hand within the Bistro WYSIWYG for editor. Either way, when creating the form, you can name the form whatever you would like, but be sure to set the method to POST and to leave the action blank.

When naming your fields, be sure to use names that you will recognize such as "FirstName" as opposed to "Field1".

Once your form is complete, when a website visitor completes the form, the submitted data will be compiled into a text-only email message that is then sent to the Bistro default address (which can be specified in the System Setup area of Bistro). If you would like to customize the email address the form is sent you, include a hidden field named "to" with the value set to the target email address. For example:

If you would like your form contents to be submitted to more than one address, you can include multiple hidden fields, but if you have more than one, you must name the field "to[]" (note the square brackets). For example:

6.7.3 How To Modify the Meta Tags

Although you can specify the keywords and description used by your meta tags within your template file, the best way to define your meta tags is to use the two AutoStuff tags .

To use these tags, simply include the following HTML in your template, as opposed to the original meta tags you would have used.

You can then log into Bistro, and in the System Setup area change the default keywords and description used by your site, or you can specify unique keywords and description values for each page on your site, and for many of the other modules.

6.7.4 How To Create a Configurable Footer

The way to create a configurable footer is exactly the same as creating an editable area in your template. See Section 6.7.6 How To Create Editable Areas in a Template.

6.7.5 How To Create Random Images

Although there are many ways to have random images included in your theme, this short tutorial highlights the easiest.

 

In the above example, you can modify the text that shows the image to add your own styles, parameters and attributes. When copying and pasting the above code snippet, be sure to include the opening and closing .

 

6.7.6 How To Create Editable Areas in a Template

Many designers want to create an area in their theme or template that the site owner can edit. This editable area may be an area with recent news that shows up on every page, or even making the footer or header more configurable. To create such an editable area, simply follow these steps:

When using this method to create an editable area, be sure to name the page appropriately so that the website owner will recognize the page. If you have many different editable areas, or many different pages that are included within other pages, you may want to organize them within the Page Manager by placing them within a folder called Included Pages or some other easily identifiable name.