A basic introduction into xoops theming
Some days ago I was asked to write “A basic introduction into xoops theming or designing layouts for xoops” for designcontest.net. Subheading: What I would tell when a designer asked me to describe what is different or important creating layouts or themes for xoops.
It was thought to be what it was titled, a basic introduction for those who do not know xoops as well and to give a small overview. Perhaps some of you can use it as well?
- Introduction
- Some thoughts
- Basic overview or how to get the content into the theme
- Deeper look
- ModulTemlates
1. Introduction
You want to create a theme for XOOPS cms? For the fast and furious we can stop here by saying that there is no (big) difference between designing the visual appearance, the layout of a static [x]html file and a xoops theme besides the dynamic parts of the xoops file.
Assuming that you are able to read and write html, there will be no big problems. When your skills in html and stuff are limited, this won’t be a big problem too for you can use the basic structure of an existing theme and change images and/or edit parts of the html and stylesheet to get a different "result".
We on XOOPS call the visual appearance "theme"; other cms use expressions like "template". A theme is a set of html, css, js, and images which all together build the visual appearance what visitors will see while browsing the website and what other user agents (UA) and browser will be able to read. Xoops as a CMS (Content Management System) is build to divide content from layout that is one of the basic principles of a cms. The layout could be changed by editing a preference in xoops administration. All files of a theme are organized within one folder with optional subfolder (/images, /js/, … ). The name of the (theme)folder is what xoops system will identify as the name of the theme.
Imagine you will create a static page within a folder containing the index.html, css, js and images. Nothing different but within a xoops theme we need a file called "theme.html" instead of the index.html. Xoops system will check if there is a file called theme.html. When you would rename your static html file to "theme.html" xoops will display your static file but … erm … then you will get bored very soon while always reading the same content.
Like a static file a xoops themefile ( theme.html) is a html file containing all basic html elements (tags), which means that (by default) the file will start with the document type description and ends with the closing html tag. Meta stuff is included and stylesheets and scripts are linked. Of course you are allowed to outsource some parts of the document like other CMS or (we)blogs do by using functions to include source. This depends on what you want to achieve. Sometimes it would be easier to divide the themefile into parts but this is not needed by default.
This having said, you can fire up your preferred graphics editor open a default theme.html in a text editor and begin to work as usual.
2. Some thoughts
Actually we find 2 different movements of implementing graphics and layouts into [x]html but that’s not only xoops related, we find this discussion on many places. The old way to (ab)use tables to position graphical elements and the "modern" way to use css for positioning things.
I don’t want to start a discussion at this place, what are the advantages and disadvantages for different groups but you might have noticed that I use the expression "read and write" html instead of coding. I for one personally believe in the spirit that html is a language, which should be seen as such, and a language should be readable. Having constructions of tables filled with images to get them displayed properly wouldn’t help to get a clean, readable source. But I see arguments from different sides. If you are used to use a graphics editor that slices images by exporting into html I can imagine how you would argue.
Personally I think that layoutimages do not belong into the output of an html source, they should be defined within the stylesheet as background images.
While more and more user Agents are able to understand css correct it should be much easier for a graphics designer to get his layout into an html file once he is used to work this way. It’s a bit different thinking even in making layout screens but you will get used to it very fast.
Ignore the above and let me tell you that you are free to act like you want when you create a theme for xoops. As said earlier you can work like you are working on a static html file. To be honest, actually there are still modules available for xoops, which make life harder for those who want to use the "modern" way. The output of some modules is put into layout tables and filled with inline styles to get the intended (display) result at least from the point of view of the module developer.
3. How to get the content into the theme
Let’s have a look on how xoops themes work and what is meant by dynamic parts.
Like any other html document, xoops output contains of some important information for User Agents (encoding, language, meta tags, pathes to scripts, css and stuff), the content of the page (this is why your visitors love to visit your site) and the visual things. XOOPS as a cms organizes these things for you and stores it into a database. Within the administration of xoops (the backend) you are allowed to change settings of your page e.g. name of the page, meta description, meta keywords, language, theme and many other things. This is the place where modules are installed and managed, users administrated and much more.
This information has to be displayed within the output. For there are many different and possible values and hopefully much content we are using placeholders (smarty tags) for such information in our themefile. While visitors type in the URL of your site the wanted document will be created using the themefile and replacing the smarty tags with the information stored in database (rendering).
XOOPS is (actually) using a template engine to place needed preferences and content into its html output. Some systems use their own engine or php strings, xoops is using the well-known template engine called Smarty ( http://smarty.php.net).
Smarty .. "provides the programmer and template designer with a wealth of tools to automate tasks commonly dealt with at the presentation layer of an application. I stress the word Framework because Smarty is not a simple tag-replacing template engine. Although it can be used for such a simple purpose, its focus is on quick and painless development and deployment of your application, while maintaining high-performance, scalability, security and future growth." ( http://smarty.php.net/rightform
There is a specific syntax using these smarty tags within a themefile. Let’s have a look at a practical example. Within administration area of xoops the webmaster is able to define e.g. the name of the page (sitename).
Within the theme.html you will find <{$xoops_sitename}> which will be replaced by the input made in administration while creating the output (rendering) of your website. When you open the default theme.html you will find some of those smarty expressions you will need to have in your themefile such as meta tags, path to theme etc. And there are many more smarty tags available you may want to use. A full list of default smarty expressions is available on xoops.org (at least a link to its destination) but this will not be the topic in this document. Anyway, using the default theme is a good example to get started and it contains all important things.
4. Deeper Look
In general xoops is organized within blockpositions and the contentposition.
By default we are used to use blockpositions left, right and center in our themes but this is because they are named like this within the blockadminstration and it’s much easier and intuitive to use for those webmaster who did not create the theme.
Anyway, blockpositions and contentposition can be placed (displayed) in themefile where you (the designer) want and where you want to manage and control the output. This may be within the visual position of header, left sidebar, etc. or on other places. Especially since XOOPS Version 2.0.14 where we have all in all 8 blockpositions with the ability to manage and display arrays of blockcontent this is more and more an opportunity. These (manageable) blockpositions are:
- left
- right
- top center center
- top center left
- top center right
- bottom center center
- bottom center left
- bottom center right
Within each blockposition we will find an array of active blocks set to be displayed in this area. Anyway, the designer is free to put 2 or more blockpositions into one layout area.
Each block that is within an Array of a blockposition (each block which is set active on a special site) contains of a title and the content of the block.
Let’s have an example again to make thinks more clearly to you.
Imagine you have a 2 column layout with a sidebar on the left and you want to place the content of blockposition "block left" into it.
< ! — start sidebar — >
<div>
< ! — Start left blocks loop — >
<{foreach item=block from=$xoops_lblocks}>
<{$block.title}>
<{$block.content}>
<{/foreach}>
< ! — End left blocks loop — >
</div>
< ! — end sidebar — >
This will display all those blocks which are set into blockposition "block left" (within blockadministration) and which are set active. This way you can use to call all different blockpositions with its content. For each different blockposition there is a smarty expression you can use in your theme.
Within the content position we will have the module content and typical pages like submit forms, summaries and so on. To display the content of a module, use:
<div>
<{$xoops_contents}>
</div>
There are more placeholder, smarty expression to display manageable content like eg.
- <{$xoops_banner}> (output of banner rotation)
- <{$xoops_footer}> (output of footercontent)
But the above will be enough to understand the way content is put into themes.
Each installed module like forum, download, gallery, etc., has it’s own set of blocks and it’s main content area. Within the blocks you will normally find specific output of the module with parts of information like eg. latest entries, latest submission and so on. Xoops itself comes with a set of system blocks (mainmenu, usermenu, who’s online, etc.). Within the administration of xoops blocks, we can define our own (custom) blocks with content type html or php without a module.
When you directly browse a module page (click on mainmenu entry), the main content of the module will be displayed. Blocks can be displayed on every page you like; it is not dependent on the module that is actually displayed. This means that you might want to show a block with the latest gallery images while the main content of downloads is being shown.
This is handled within the blockadministration, one of the hearts xoops is driven by. Here you can set blocks active, deactivate, weight, order them within a blockposition and edit their preferences.
This is what can be dealt within themes, the general appearance of your website.
5. ModulTemplates
When you need to arrange a different output of specific modules and/or their blocks, this can be achieved by editing the templatefiles of a module itself. Every Module comes with a set of modultemplates which organize the way the moduloutput will be displayed.
Like the blocks are called within theme.html the content of a module is arranged within arrays. For each valid argument of output the template will for example display a row within a table etc.
Normally there is no need to edit modultemplates when they do its job like you want them to. In some cases you might want to validate or change single output. This is the correct place.
This is what I think is enough to get a basic overview. Besides all theory it will be best and easiest to play with the default or some other theme with enhanced functions to see how it works. Every new theme idea may have different needs to display things. Most things you will find on xoops.org, help, tips and ideas.
