## Please edit system and help pages ONLY in the master wiki!
## For more information, please see MoinMoin:MoinDev/Translation.
##master-page:None
##master-date:None
#acl -All:write Default
#format wiki
#language en
= Themes =
<<TableOfContents>>
MoinMoin has a theme plugin system that makes it easy to change the look and feel without touching the core code. As a user you can choose between different themes that are pre-installed<<FootNote(On a standard !MoinMoin 1.9 installation these are "classic", "modern", "modernized", "modernized_cms" and "rightsidebar" )>> As a user you may be able to change the theme you can view by going to the user preferences (it does not work if the wiki administrator has forced a specific theme, disabling the ability to change the theme).

== Installing Themes ==

You can find additional themes if you visit MoinMoin:ThemeMarket and download the archives there. Please make sure that the theme you choose is compatible with your version of !MoinMoin!

You can not just copy the whole directory to a themes directory. That will not work. To install a new theme follow the instructions by the theme author. Generally you have two different locations:

 1. The directory where all the static files of the themes reside
  * Unpack the archive and put the theme directory here (containing two directories: `css/` and `img/`).
 1. The `data/plugin/theme` directory where theme code can reside
  * move the theme script here (that has the same name as the theme but with a `.py` ending).

Your theme should be available now. Maybe you have to relogin or clear the cache to see it. For configuration options please go to HelpOnConfiguration. 

== Customize Themes ==

You can customize the pre-installed theme but it is much better to start with a copy. To do this make the following steps (we take theme `modern` as an example):

 1. Make a copy of the 'modern' theme in the static files directory and call it 'mytheme' 
 1. Copy the script of this theme `MoinMoin/theme/modern.py' to `data/plugin/theme/mytheme.py'
 1. Edit the file 'mytheme.py' and change at least the variable {{{name = "modern"}}} to {{{{name ="mytheme"}}}
 1. Then you should be able to see your new theme. If not, restart the web server.
 1. After that start editing the files in the theme's static files directory.

Where the static files directory is located depends on the installation of the wiki:
 * either your web server serves url_prefix_static, then consult it's configuration (usually an Alias will be there that maps the url_prefix_static URL to some filesystem directory)
 * or moin serves the url_prefix_static with its builtin static server - see the place where you create the WSGI application:
  * `shared=True` means it will serve the builtin static files from `MoinMoin/web/static/htdocs/`
  * `shared=somepath` mean it will serve the static files from somepath

The best way to change the visual appearance of your wiki site is by inherting the default MoinMoin styles and only changing those things you want to adapt to your likings. This avoids the work involved in copying new styles added during development to your own stylesheets. To do this, we use the CSS `@import`  mechanism like this:
{{{#!highlight css
@import url("/moin_static190/modern/css/common.css");

h1,h2,h3,h4,h5 {
    background-color: #88CCFF;
}
}}}

In the first line, we import the default common styles as distributed with MoinMoin.
You may have to change the URL to fit your system setup and/or MoinMoin version.

In the following lines, we change the background color of headlines. And that's it.

For more see the [[http://css-discuss.incutio.com/|css-discuss]] wiki.

For a very clever idea to make CSS ''wiki editable'', see [[http://esw.w3.org/topic/plain.css|plain.css]].


== Modify wiki configuration  ==
||<rowbgcolor="#ffffcc"> '''Parameter''' || '''Default value'''        || '''Description''' ||
|| `page_footer1`                        || `""`                       || Custom HTML markup sent ''before'' the system footer. ||
|| `page_footer2`                        || `""`                       || Custom HTML markup sent ''after'' the system footer. ||
|| `page_header1`                        || `""`                       || Custom HTML markup sent ''before'' the system header / title area but ''after'' the body tag. ||
|| `page_header2`                        || `""`                       || Custom HTML markup sent ''after'' the system header / title area (and body tag). ||
|| `stylesheets`                         || `[(media, csshref), ...]`  || List of tuples (media, csshref) to insert after theme css, before user css. ||
|| `html_head`                           || `""`                       || Additional <HEAD> tags for all pages ||
|| `html_head_posts`                     || `robots: noindex,nofollow` || Additional <HEAD> tags for POST requests ||
|| `html_head_index`                     || `robots: index,follow`     || Additional <HEAD> tags for some few index pages ||
|| `html_head_normal`                    || `robots: index,nofollow`   || Additional <HEAD> tags for most normal pages ||
|| `html_head_queries`                   || `robots: noindex,nofollow` || Additional <HEAD> tags for requests with query strings, like actions ||

You can customize your wiki by modifying the wiki configuration as follows:

 1. head
  * `config.html_head` is added into the <head> element for ''all'' pages
  * `config.html_head_index`, `config.html_head_normal`, `config.html_head_queries`, `config.html_head_posts` are added for different types of pages (see above)
 1. body
  . you can use some html fragments to customize moin's output (we are referring to standard themes, others could differ) – here is the sequence how stuff is output:
  * header:
   * `config.page_header1`
   * `config.logo_string` – use this to modify the logo (usually at top left)
   * search form
   * username (on side panel in `rightsidebar` theme), interwiki, title
   * trail
   * iconbar (used inly in `classic` theme)
   * `config.navi_bar` – is a list of page names that are added to the title area, if None, add no navigation bar. In `rightsidebar` theme it is placed on side panel.
   * msg
   * `config.page_header2` (in `rightsidebar` theme this markup is placed before side bar and msg string)
  * wiki page
  * footer:
   * Page information
   * `config.page_footer1`
   * edit bar (on `rightsidebar` it is on side panel), search forms (only in `classic` theme), actions (only in `classic` theme)
   * `config.credits`
   * version
   * `config.page_footer2`

 1. as a wiki user, you can override theme CSS settings by putting your own user CSS URL into your user preferences – this CSS is loaded after the theme CSS, so you can override all you want changed. Your CSS file must be in UTF-8 encoding (ASCII is OK, too, as it is a subset of UTF-8).

`page_header1`, `page_header2`, `page_footer1` and `page_footer2` can now be callables and will be called with the "request" object as a single argument (note that you should accept any keyword arguments in order to be compatible to future changes).

== Make a new Theme ==

If you wish you can also create a new theme. The best way is to copy an existing theme like `modern`. You will also have to rename the theme script and change the variable `name` inside this script. If you are a Python programmer you can also start writing a new user interface by writing a new theme script for your theme. When you upgrade MoinMoin, your own themes are not touched - it will work with the new version, or needs only small changes due to theme API changes. (For more see also MoinMoin:MoinDev/ThemeDevelopment)
