Understanding and Making Your Own Custom Sphinx Theme

Latest News And Info! By Luke, for DynSCS
Published on Dynamic Systems and Content Solutions.

So, you want to make your own custom theme, and make your site “da bomb”, right?

That’s what we’re going to cover today, walking you through the basics of implementing your kick ass ideas.

Disclosure

First, understand that this isn’t exactly a beginner level article. If you do not know basic HTML/XHTML, CSS, and a little php, you will need to brush up on those skills. Don’t worry, there are plenty of forums and resources out there to help you get up to speed. Or, as an alternative, over time there will be additional themes made available by users and maybe the Developers for you to use.

Let’s get to it, shall we?

Please note that this is a basic overview, and you are expected to be able to fill in the blanks. This is not a hand-holding step by step guide, and we assume no responsibility for its misuse, etc.

Visualize, Create

First, you need to visualize what you want. Next, with Photoshop (Fireworks or a similar graphics program might work too, but we prefer Photoshop), draw it up!

This phase is your visual concept. No real need to add text and stuff, but you should at least sketch it out and get the basics out of the way.

Once complete, you will begin to copy various elements from your mock-up as you generate the HTML for it, and make new images from these pieces. Remember to take things into consideration such as file size, etc. If it is a solid color, use CSS instead. For a background that’s repetitive, take a 1, 2 or 4 px wide (or high if it is vertical) swath, and use the repeat property in CSS (x,y, etc).

Basic HTML Layout

On to actually theming your site, and creating the HTML.

We’re going to use the Sphinx default theme as a reference, so that you have a visual to look at while reading this. Now would be a good time to open up either your local Sphinx site, or your website in a new tab to reference on occasion.

First, let’s make a temporary directory locally to work with. Let’s say we make it on our Desktop, and call it my-theme. From here on, we will assume that you will be inside of this directory.

Next, remember we’re inside the my-theme directory, make another directory called images.

Next, let’s make a basic page, and work from there. Using your text editor of choice (Taco, BBEdit, TextWrangler, or similar for Mac; Kate, or even Vi for Linux; Notepad, Dev-PHP, or similar for Windoze), we’re going to make a basic HTML page to work out the basic layout, and then work on implementation into Sphinx/SMF. Let’s just call this index.html for now. Just save the blank file for the time being.

Next, lets make another file to work with. Let’s call it style_sphinx.css, and save it blank as well.

Now, our my-themes directory looks like this:

my-themes
– images
– index.html
– style_sphinx.css

Now, we’re going to generate some HTML and CSS.

With both the index and style files open, let’s look at our Photoshop mock-up and visualize the HTML we need to accomplish it.

Write up a basic head section for your html, that includes a <link> to our style sheet.

We’re not going to worry about validation, yet, but we will soon. Right now, this is like a very rough draft. However, you should script up your HTML inside your body tag to be as compliant as possible initially, when I said “don’t worry” a second ago, I was referring mainly to the doctype and head of the document.

So, again we’re referring to our default template as a “visual” for this article, we know we need a header area with a logo for our site, and a “welcome” area for users/guests; a stretch of menu links; buttons for collapsing left, top, and right blocks; left blocks, center area for the main content of the page; bottom blocks; right blocks; bottom menu; and finally our footer area.

So, now we generate out basic layout. Let’s make a note right here. dreamweaver and frontpage just don’t cut it, but it’s your call and your site. We’re referencing writing from scratch, as it’s easier to do it right the first time than to have to do the work and then go back and redo it/clean it all up.

OK, we know our default theme isn’t exactly “perfect” code bliss, but wait for 2.0 and it will be.

Also, we’re not going to get into a div/table debate. We’ll leave that up to you.

As we go along, we’re adding and editing our CSS file, using ID’s and classes as appropriate, and making default background colors that are close to what images will be used (if applicable).

So we’ve scratched out the basics areas mentioned above. Now we’ll need some images to fill it in a bit. So, for example, we go back to our Photoshop file and grab a 1px wide portion of our header background. Repeating this image makes the same background, and the image loaded is still very small. Continuing on, we grab some other images as well for our portal related stuff like block title or what have you.

Note, we aren’t playing with the output from other files yet, just the main portal output present on all pages, etc.

So now we have a generic layout, let’s add a little text to it to play with and style.

Right, now we have the basics working in a “dummy” file, it’s time to integrate!

Theme Integration

First, and most important, we’re going to make a new theme directory inside of the Themes directory on our site.

Next, let’s copy over the following directories and files from our default theme:
- images
- fonts
- index.template.php
- index.php (so folks definitely can’t browse the directory)
- style.css (this contains all the styles for the forum side of things)

Remember, you only need to have the templates you edit present in your theme. The others will be pulled from the default theme. With the exception of style sheets, images, etc.

Now, the fun shall begin.

An example of default Sphinx theme, broken into template areas.

–Sphinx Default Theme–
Template Areas

Template Structure

First, we need to understand the template structure, and the areas we’re dealing with. Referring to the image to your right, you’ll notice 3 areas we’re concerned with.

They are:
- template_main_above
- non-index template output
- template_main_below

template_main_above

This area, depicted by the yellow outline in our example image, is everything in the final output source that occurs before the main page content. Again, using our default theme as an example for visual reference, this would include the header, main menu, collapsible block links, our left side and top blocks.

Non-index output

This area, depicted by the red outline in our example image, is the main content for whatever page we are on. For example, the board index or the News or Article areas. We will not be concerned with this area yet, but we need to know that this areas output is controlled by whatever additional template is required.

template_main_below

This area, depicted by the green outline in our example image, is also in the index.template.php file. This controls the output that comes after the individual page template, and from there closes out the remainder of the document source. This would include bottom block, right blocks, the bottom menu and closing with the footer.

Main Above/Below Output

Now we’re going to convert the HTML in our basic index file, and code it into our theme.

Let’s make a duplicate copy of the index.template.php file to use as a guide while we make the merger.

Opening the copy, and moving it to the side, we now open the index.template.php file.

Moving down to the template_main_above function, we locate the closing of the document head section, and the start of the body.

We now are going to copy over our HTML parts as necessary from our draft index file into our main_above area. This is where some basic PHP knowledge comes into play. Remember, we’re not here to teach that, we’re here to provide the basic info for making your theme.

The HTML will be enclosed in echo statements. Replace and modify as need be, and follow along with it. Working around the if statements, and certain tag/function aspects. Most little things can be left as is from the default index.template, so compare yours to the copy you made if something goofs up. For example, collapsible blocks, etc.

As a reminder, the HTML being copied is only from the body of our draft index template, and only that portion up to the non-index template output. Skipping the actual menu layout, and left/top block layout (for individual items), and leaving the main layout pieces for these areas.

Repeat this procedure for the templat output after the non-index output, to close out the document. Don’t forget that you only need the main pieces for bottom and right blocks, and the bottom menu.

Blocks and Menu’s

Now we need to make our individual menu and block outputs, maybe.

I say maybe simply because you may be able to use the default menu and block templates, but modify the existing CSS to fit.

For now, we’ll assume you need to make a few changes.

Let’s make a new directory in our theme called “portal”, and then a “blocks” directory inside of that.

Now, we’ll copy over the following from the default/portal/ directory:
- Menus.template.php
- index.php

Then copy over the following from default/portal/blocks/ directory:
- Blocks.template.php
- index.php

Now modify as needed to match what you’re doing in your HTML/CSS.
If you need to add a new function for your menu, we’ll assume you know how to do this.

Finalizing Your Theme

Now that we have made the edits to the main above, below, block and menu files according to our needs (you may have not needed to edit the block or menu files), we can now first see that we have what we desired.

Note: We haven’t touched the forum CSS yet, so don’t freak. We’re checking what’s around it first.

Not what you thought it would be? Excluding the non-index template stuff, make edits and adjustments to the above/below stuff until it is. This may take some time to get used to.

Non-index template stuff

This is the stuff not covered in the above/below functions we’ve already edited. How far you take these edits is up to you and beyond the scope of this article.

We’re going to need to match up the CSS with our theme now, by editing our style.css file.

As you may have noticed, starting with Sphinx 1.1 we are “promoting” a separation of the forum css and the portal specific css. Mainly because in the long run it is easier for theming, and knowing where to look for certain things. Not that the portal doesn’t use those style, but so that you as a user can know from where each style comes from and overall what area it will effect.

By calling the style_sphinx.css file second in your document, you can “overwrite” certain basic characteristics, and keep track of your edits and changes. If you would prefer to combine it all into a single file, fell free to do so.

We recommend finding the images referenced in style.css, and making new ones with the same name. It’s just easier that way. Again, it’s your call.

Next, we’ll edit colors and such to match our theming efforts.

Next, we’ll verify it’s meshing and looking like we want. Tweaking as necessary.

Finally, we may need to do something with the remaining images being used. Like buttons, the tab looking links in the forums and admin areas, etc.

The tab setting is in the index.template.php file, up towards the top in the template_init function. Set $settings[’use_tabs’] to false if you don’t want the tabs.

Next comes those forum images. Buttons, icons, and all that jazz. They can be found in the images directory and its sub-directories. All we’re going to say is have a good time. There’s a lot to edit and play with.

(Remember, you can add new thumbnail sized images to the News and Articles images directories, and they’ll show up in news and article management to select from. ;))

Finishing Touches

Check your theme with the validator at the W3C site, and don’t forget to test it in as many browsers as possible. BrowserShots is a great tool if you don’t have much access to other browsers.

Did we mention to be sure to validate your code? Having a browser rendering in quirks mode kinda sucks, plus standards are the right thing to do for so many reasons!

In Closing

OK, that was a long winded read. However, it hopefully will help get you started on the right track to integrating and creating your own custom theme for your site. At the very least, hopefully we’ve left you with a better idea of how things work overall.

Really, the sky is the limit and the only thing to hold you back is the strength of your knowledge. The stronger your knowledge, the closer to the sky you can climb.

Oh yes, remember that basic layout you worked up as a draft? Now that you have it, you can apply it to other things you may add to your site as well. Like a photo gallery, blog, or other great bridges that are sure to come from Dynamic Systems and Content Solutions!

Keep it handy, you may need it.

Theming Sphinx? It’s A Snap With A Little Effort!

By Luke, for DynSCS
Monday March 26, 2007
8:15pm CDT
Published on Dynamic Systems and Content Solutions.

What can you do with Sphinx? What can’t you do with it?

It’s built around the SMF template engine, for now, which allows for some pretty interesting theming capabilities. Just check out our community and see for yourself.

Have an existing SMF theme for your site that you would like to use? Sure. Just make room for the block areas you want, like left or right or both (or top, bottom, etc), and then add the call to the dsp() function in your footer somewhere.

By default, Sphinx comes with a nice pretty default theme, and we’ll be working to add more themes as we have time.

Please note though, that since were a two person show at the moment, that our primary focus is on Sphinx. Any additional themes and mods from the Community are greatly appreciated.

So with that, that’s about all for our initial look at theming Sphinx 1.x…

For our upcoming 2.x branch, you can throw all of this out the window. Why? It’s too darn complicated for an average user. Nothing against you folks, but if we could all speak PHP it wouldn’t be a problem. It is a problem though. You want control of your website, and in our upcoming 2.x release(s) we’ll give you back the power to theme your site until your heart is content.

If you can make a simple html template, add some css, and then add a couple of “tags” where you want certain content, you’re going to absolutely love Sphinx 2.0 and beyond.

You thought Enigma 1.x was easy? You ain’t seen nothing yet, folks.

Welcome to Sphinx, and the beginning of a new chapter in your website and content management lives.