The following is based on changes made in Ushahidi 2.7 and may not be accurate for earlier versions
CSS and JS in Ushahidi are managed through a combination of the Themes library, and the Requirements library.
Adding your own JS / CSS
In a theme
To add JS and CSS files to a theme, you need to specify the file to be added in you Themes readme.txt file. This is best explained by example
This will include 2 files
- themes/mytheme/css/mystyles.css
- themes/mytheme/js/myscripts.js
These will be included on every page on the frontend.
Special Cases
Older themes / Missing CSS file list
If you don't specify the CSS line in your readme.txt, Ushahidi will look for the following CSS files: base.css, style.css, _default.css
This is to make it easier to use older themes created before the CSS / JS lines were added to readme.txt.
Base Themes
In addition to the CSS / JS files you specify in your themes readme.txt, we will include CSS / JS files from the base theme.
For most themes this is the "default" theme, which includes base.css, accordion.css, slider.css, style.css
IE CSS
The following IE CSS files are included by default:
- themes/default/css/iehacks.css
- themes/default/css/ie7hacks.css
- themes/default/css/ie6hacks.css
These can be overridden by including a file of the same name in your themes css folder. For example "mytheme/css/iehacks.css"
RTL CSS (RTL = Right To Left)
All CSS files can provide a RTL version - this will be used when site language is RTL.
Example
- themes/default/css/base.css would be swapped for themes/default/css/base-rtl.css if it exists
RTL languages are defined based on the translation of the 'core.text_direction' string. If this is translated to 'rtl' then language is RTL.
For testing this can be overridden in config/locale.php: locale.force_text_direction = 'rtl';
In a plugin or theme hook
The easiest way to add JS or CSS is through the Theme config in readme.txt. This adds the CSS/JS to every page on the frontend.
However if you need to add CSS to only some pages, or through a plugin, or to the admin - you can do that using the Requirements library in a Theme/Plugin hook.
See How To Write A Plugin#TheHook for more info on hooks.
Examples of Requirements methods
Configuring the Requirements library
The Requirements library handles actually generating the style / script tags to include CSS/JS in the page.
There are a few settings available in the requirements.php config file
Suffix requirements:
when enabled this adds a modification time the end of URLs like: http://mydeployment.com/media/js/OpenLayers.js?m=1353545029
This means the URL changes when the file is updated and forces the browser to fetch the file again, rather than use a cached version.
This is useful if you are using future Expires headers: http://developer.yahoo.com/performance/rules.html#expires
Combine files:
This will combine some main groups of CSS and JS files into a single file. This reduces the number of HTTP requests and can improve page load speed. http://developer.yahoo.com/performance/rules.html#num_http
- The combine with JSMin/CSSMin option will also compress the combined JS/CSS files.
- If you're are using a CDN you need to enable the CDN store combined files option OR manually upload combined files to the CDN.
Write JS to body
This option will output <script> tags at the end of the page body, instead of in the head. However this option is not yet supported and will break some of the core javascript
Themes library
The Themes library is responsible for several things
- Loading themes into the module path
- Loading themes JS and CSS
- Managing bundled JS libraries and including them as needed
- Generating various bits of HTML, such as the header and footer blocks.
The themes object is created in the Main and Admin controllers, then called in other controllers later.
The following code enables JS mapping and slider libraries, and the timeline if its enabled.
The actually execution and inclusion of CSS / JS happens just before the "layout" view is rendered using the view_pre_render-layout hook:
More details: