FOR ARCHIVAL PURPOSES ONLY

The information in this wiki hasn't been maintained for a good while. Some of the projects described have since been deprecated.

In particular, the "Ushahidi Platform v3.x" section contains information that is often misleading. Many details about this version of Platform have changed since.

This website is an extraction of the original Ushahidi wiki into a static form. Because of that, functions like logging in, commenting or searching will not work.

For more documentation, please refer to https://docs.ushahidi.com

Skip to end of metadata
Go to start of metadata

 

For the basics about Themes, see Add and Configure Themes

How To Build A Theme

Required Skills and Knowledge

  1. intermediate knowledge of html/css
  2. basic knowledge of the MVC paradigm
  3. Important but not mandatory: Graphic design or web design experience and knowledge of PHP/OOP concepts

Theme Standards

Rather than reinvent the wheel here, we encourage you to review Theme Standards set forth by the folks at Wordpress. Wordpress Themes are almost identical in concept to Ushahidi Themes. Therefore, the Wordpress Theme Standards can apply Ushahidi Themes as well. In short: when development themes, please write clean, well-documented code & use valid css.

What Makes up a Theme?

“Basic” Directory Structure: This is the directory structure you will see if a theme only deals with the look and feel of a deployment.

  1. “css” folder: Holds all CSS files related to the theme. All css files in this folder will automatically be included just after the default stylesheet declaration on every page of your deployment (the default stylesheet can be found in the css folder that is in the “default” theme folder).
  2. “images” folder: Holds all images related to the theme.
  3. readme.txt: This file contains all the information about your theme. 
    Important Note: If this file is renamed or deleted, the theme will not show up in the admin panel!
  4. screenshot.png: This is a screenshot of the theme and is used for display in the admin panel.

“Advanced” Directory Structure: If a theme not only changes the look and feel but also changes the layout, you will see one additional folder

  1. views: this contains all views files related to the theme. See this wikipedia article for more information on the “Model View Controller” paradigm. However, to quickly define what views are: “views” are basically the files that contain all the information you want to output to the browser. For example, the view file that produces reports page (http://demo.ushahidi.com/reports) is here: your-ushahidi-root-folder/themes/default/views/reports.php 
    Similarly, the file that produces the alerts page (http://demo.ushahidi.com/alerts) is here: your-ushahidi-root-folder/themes/default/views/alerts.php

How Do Themes Work?

In order to understand how themes work, let’s first look at what is inside the “themes” folder on a clean installation of the platform:

The “default” folder

Think of this folder as the “master” theme that governs all front end pages of the Ushahidi platform. This folder contains all of the default css, images and views that are used to render the pages. See this diagram for a visual illustration of this concept. This folder should always remain untouched when developing your own theme.

Other theme folders

“terra” is the a theme that comes packaged with the Ushahidi platform.  Notice that this folder only has a “css” and “images” folder. When this theme is activated in the admin panel, the css styles and images in the theme will override any css styles and images in the “default” theme. To take things further, if the “terra” theme also contained a “views” folder, those views would also override any corresponding views in the “default” theme.

In summary, the “default” theme folder holds all the default css, images, and views. Any other theme folder merely builds upon and/or overrides those css, images and views.

Getting Your Hands Dirty: Changing the Look and Feel

What follows are basic instructions for creating a theme that changes the default look and feel. This tutorial will assume that you’re working with a fresh install of the ushahidi platform. 

Part 1: Getting your theme files set up and activated

1. Duplicate the “terra” folder and rename it. 
Note: we’re just duplicating an existing theme because it’s quick and easy to do. In theory, you could just as well create a folder, and then add all the essential files and folders yourself and get the same result. 

2. Edit “readme.txt” and fill it in with your details:

Theme Name: Flying Nyan Cats
Description: A nice background pattern with a color scheme to match
Demo: http://your-demo-site.com
Version: 1.0
Author: Your Name
Author Email: your@email.com

3. Go to the theme management page in the admin area (http://your-deployment.com/admin/addons/themes). You’ll see that the Ushahidi platform has added your newly created platform to the list. Once there, click the “select theme” radio button to activate your new theme.

4. Go to the home page of our installation and refresh your browser. You’ll notice that default “grey” background has now been replaced with a “dark blue” blue one. This confirms that our newly created theme is indeed active. We are now ready to dive into the code!!

Part 2-Basic: Making changes to the images and css

Now that we have our theme activated, we can now make changes and additions to the css and images that will change the default look and feel.  If you want to modify the default look & feel at a basic level, you really just need to modify the css and images. The quickest way to get started with this is to use Firefox to view the pages of your deployment and then visually explore the html/css structure using the Firebug Addon (cheesy but helpful tutorial on how to do this). Once you know what sections of html/css you need to change, you’ll be able to easly modify and update your theme’s “styles.css” file accordingly.  

Part 2-Advanced: Making changes to the front-end markup

As mentioned earlier, “views” are the files that contain all the information you want to output to the browser. As such, we can use them in our theme to change the default layout and elements that are displayed on our pages. To make a change to the layout of a pages, you must take these two steps: 

  1. Copy the view you want to edit from the “default” theme folder into your new theme folder: Views tend to correspond with the url’s of the pages on your site... for example: the “view” file for http://demo.ushahidi.com/reports can be found here: your-ushahidi-root-folder/themes/default/views/reports.php
  2. Make changes to the HTML markup: Now that your view has been copied into your theme folder, it will take precedence over the corresponding view in the “default” theme folder.
  1. Has anyone done a Twitter Bootstrap implementation?

    (This has nothing to do with posting twitter map positions, I am talking themes here.)

    This would help me if someone has already embedded the php into the BS html.

    Thanks — jack marting

     

  2. Hey Jack,

    Have a look at this:-

    https://github.com/rrbaker/booty

    Its a responsive, HTML5 Ushahidi theme based on the Twitter Bootstrap framework

  3. Hey Jack,

    Angie beat me to it while I was traveling but, yes, Booty is an Ushahidi theme built in Bootstrap.

    It's updated for 2.3.2 but I'm still in the process of fixing a few things up and making some adjustments for better 2.7 support but pull requests always welcome.

    Thanks,

    1. Hi Rob Baker, I was wondering if you still have your deployment demo. I tried to use the url below (found looking at your page) but says it is offline.

       

      http://crowdglobe.net/

      1. Hi, thanks for your comment.  I do, but unfortunately Internews holds all the licensing and ownership of this domain.  Best to contact them at the email address provided.  I'm sorry to see it offline and apologies that we couldn't be more of a help here.