HACKING.themes.md 3.36 KB

Noosfero Instructions for Theme Developers

To build Noosfero themes you must to know HTML and CSS. You may also get some advantages with Ruby and Noosfero hacking knowledge because all customizable pieces of the theme's HTML structure are erb files.

Organization Basics

A theme is a directory and must inside noosfero/public/designs/themes, and you will find tis themes in a fresh installation: noosfero, aluminium, base, butter, chameleon, chocolate, orange, plum, scarletred and skyblue. The default is only a link to noosfero and you can change this link to any other.

noosfero is the default theme with a big header. All other are colored themes with a thin header. That colored ones can be used as additional themes for any environment, as they will search for /images/thin-logo.png inside the current environment.theme, to use as top left logo.

Inside a theme we can found:

  • theme.yml — Theme description with some nice configuration options.
  • preview.png — A 100x100 screenshot of this theme to the theme selection UI.
  • style.css — The main file. The magic happens here.
  • errors.css — Change the error page look. (only if this theme is linked by defaut)
  • favicon.ico — The identifier icon for your web site.
  • images — Another name can be found by your CSS, but will not allow to reuse the logo.
    • thin-logo.png — The logo to be reused by the colored themes.
    • many images...
  • site_title.html.erb — A nice place to put your logo, any code here will be placed inside h1#site-title.
  • header.html.erb — That goes inside div#theme-header.
  • navigation.html.erb — That goes inside div#navigation ul, so use <li>s.
  • footer.html.erb — That goes inside div#theme-footer.

You can add more files like javascript and modularized CSS, but you must to refer that by the described files above.

To refer one of this files trough the web the path is <domain>/designs/themes/<thistheme>/<somefile>.


A simple definition file. See this example:

name: "My Cool Theme"
layout: "application-ng"
jquery_theme: "smoothness"
icon_theme: [default, pidgin]
gravatar: "retro"

About non obvious:

  • layout is about the theme structure to use. The application-ng is enough for 99.97358% use cases. If you want to use another structure, you must add a new *.html.erb file at app/views/layouts/.
  • icon_theme point to something inside public/designs/icons/.
  • gravatar set the default gravatar (avatar picture) for people without picture.

Theme Intervention from Environment Theme

Sometimes an environment (as instace http://cirandas.net) wants to allow profiles to set its own theme, but with some environment identification or functions, like a top bar with the social network logo and a top menu (as instace http://cirandas.net/rango-vegan). To make the magic happens you can add some files to the environment theme. All are optional:

  • global.css — this must be used to style all extra html added by your intervention partials. As it is a free form css file you can style anything, but this is a conflict risk.
  • global_header.html.erb — Will add content to #global-header.
  • global_footer.html.erb — Will add content to #global-footer.