DeutschEnglish

Submenu

 - - - By CrazyStat - - -

5. February 2013

Oxwall Community Software: How to create your own theme

Filed under: PHP — Tags: , , , , , , , , — Christopher Kramer @ 14:45

Oxwall is a great community-software written in PHP. You can easily install it on your own server to build your own community site.

It is open source and you have full control over the data.

Although Oxwall comes with some great themes that can even be easily customized in the backend a bit, one might want to build one’s own theme for Oxwall.

So here is how it’s done:

  1. Probably first build an HTML template of your design (one HTML page with CSS that looks like you plan how your Oxwall should look like). If you do that, make sure to use a list-based main menu and a div/link-based bottom-menu (see below) so you won’t get into trouble later.
  2. Always a good idea to have a backup – although adding a new theme shouldn’t break anything. I’d recommend you to create a copy of your Oxwall installation where you create and test your new theme and when it’s finished, move it to your live installation of Oxwall.
  3. Create a copy of an existing theme. You will find the themes in ow_themes. Choose one you’d like to use as a base for your own theme.
    Copy it. E.g on a linux shell:

    cp -rp ow_themes/spring ow_themes/mytheme

    Of course you could also use FTP or something like that.

  4. Define the meta-data of your theme like name, author and so on. To do so, open ow_themes/mytheme/theme.xml in a text editor and adjust the data. Make sure the <key> is equal to the foldername (“mytheme” in the example).
  5. If you want to, you can replace the theme_preview.jpg with a small thumbnail representing your theme (optional).
  6. Now you can select this theme in the Oxwall backend. Try it.
  7. Note: To be able to adjust the theme, enable DEV_MODE. Otherwise you won’t see any changes. So open ow_includes/config.php in a texteditor. Search for:
    else
    {
        /**
        * Make changes in this block if you want to enable DEV mode and DEBUG mode
        */
    
        define('OW_DEBUG_MODE', false);
        define('OW_DEV_MODE', false);
        define('OW_PROFILER_ENABLE', false);
    }

    Change OW_DEV_MODE to true:

    else
    {
        /**
        * Make changes in this block if you want to enable DEV mode and DEBUG mode
        */
    
        define('OW_DEBUG_MODE', false);
        define('OW_DEV_MODE', true); /* HERE! */
        define('OW_PROFILER_ENABLE', false);
    }
  8. Now you can start to adjust your theme. So what does a theme consist of?

Meta-Data: theme.xml

Like said, theme.xml contains the meta data and theme_preview.jpg is a preview image.

CSS: base.css

The main css of a stylesheet is called base.css. You can change/adjust the css there (there are also other places like the backend). I would recommend you to keep the css of your base theme and only adjust and add things to it. Otherwise you’ll have a hard time styling lots of things.

Images: images/*

If you need to include images, this is the best place to put them. If you refer to them from the css, use a path like this:

background-image: url(images/myimage.jpg);

HTML: master_pages/*

The HTML that builds your theme is stored in master_pages.

Note: Lots of themes do not contain all master_pages. If one is missing, the master_pages of theĀ graphite theme are used. Therefore, I’d recommend you to first copy missing master_pages from the graphite theme to your theme so you get a full set of master_pages.

The following master_pages can be there:

  • admin.html (only for the admin backend – no need to adjust this)
  • blank.html (usually no need to change this as well)
  • dndindex.html (body forĀ  pages without sidebar – you’ll want to adjust this!)
  • general.html (body for pages with sidebar – you’ll want to adjust this!)
  • html_document.html (html-head of all pages, you might want to add css or javascript here)

Markers

The following are the most important markers that you can put into your html master_pages:

{$siteUrl}

{*$siteName*}

{*$siteTagline*}

{component class=’BASE_CMP_Console’}

This is the console containing “Login”, “Register” and so on (usually at the top right corner).

{$main_menu}

A list-based menu.
Hint: Listamatic has lots of great list-based menu examples.

{$heading}

{component}

The sidebar.
Note: only in general.html

{add_content key=’base.add_page_top_content’}
{$content}
{add_content key=’base.add_page_bottom_content’}

These 3 build up the main content.
Note: You’ll only need {$content} in dndindex.html

{$bottom_menu}

The bottom menu.
Note: Not list-style, but a div with links.

{text key=’base+copyright’}

{$bottomPoweredByLink}

{decorator name=’floatbox’}

This should be at the end of your html file – oxwall puts some JavaScript and stuff like that there (for chat etc.).

All the others should be self-explaining.

So how you could do it:

  1. Upload your images to “images” and your js (of any) to the theme-folder
  2. Add your css at the end of base.css
  3. Add your references to additional css / js to html_document.html (no need to add a reference to base.css!)
  4. Put the content of your body into general.html and dndindex.html
  5. Replace your static content in there with markers.

Don’t forget DEV_MODE

When you are done, don’t forget to set DEV_MODE back to false. Otherwise your site will load slowly.

If this was of help for you or you still have a question, please let me know.

You can also contact me if you need someone to do an Oxwall theme for you.

Recommendation

Try my Open Source PHP visitor analytics script CrazyStat.