wiki:AddHeadersPlugin

Version 14 (modified by martin_s, 4 years ago) (diff)

--

Add HTML Headers to Trac Pages in a simple way

Description

This plug-in allows Trac server admins to add script, link and (with Trac 0.12) also meta headers into all trac pages without having to create a Chrome template file. This allows the easy usage of own JavaScript and CSS files. Also all other kinds of link headers can be added.

Installation

Install as normal and enable this plug-in by adding the following into the config file (normally 'conf/trac.ini'):

[components]
tracaddheaders.* = enabled

Usage

The plugin is controlled over settings the Trac config file (normally 'conf/trac.ini'). All settings must be put in the section [addheaders].

Settings

default_base = <path relative to base URL> (default: 'site/')
This is used as default base of the files relative to the base URL (which is e.g. http://trac.example.org/project1/). Please note that URL paths not local file paths are used. The default is site/ which is the relative URL for the htdocs directory in your $TRAC_PROJECT_DIR.
default_script_base = <path relative to base URL> (default: default_base)
To provide an different default path for scripts.
default_style_base = <path relative to base URL> (default: default_base)
To provide an different default path for style files.
default_meta_lang = default language> (default: None)
Default language for meta tags (i.e. lang and xml:lang attributes)
add_scripts = <name1>,<name2>,...
Will add script tags for all given names. The mime-type and filename can be defined by:
  • <name>.mimetype = <MIME-type> (default: 'text/javascript')
  • <name>.filename = <filename incl. path> (default: default_script_base<name>.js)
add_styles = <name1>,<name2>,...
Will add CSS link tags for all given names. The mime-type and filename can be defined by:
  • <name>.mimetype = <MIME-type> (default: 'text/css')
  • <name>.filename = <filename incl. path> (default: default_style_base<name>.css)
add_link = <name1>,<name2>,...
Will add general link tags for all given names. There exists no default setting.

The following settings are mandatory:
  • <name>.rel = <Relation of the link>
  • <name>.href = <Relative URL of the link>

The following settings are optional:
  • <name>.title = <Link title>
  • <name>.type = <MIME-type of linked content>
  • <name>.class = <(CSS?) class of link>
add_meta = <name1>,<name2>,...
Will add `meta` tags for all given names. There exists no default setting.

One and only one of the following settings must be given:
  • <name>.http_equiv = <equivalent HTTP header>
  • <name>.name = Name of meta tag, defaults to <name>
  • <name>.scheme = <scheme>

The content is set using:
  • <name>.content = <content of meta tag>

Optionally the language can be set using:
  • <name>.lang = <language of meta tag>

See also the example below.

Bugs/Feature Requests

Existing bugs and feature requests for AddHeadersPlugin are here.

If you have any issues, create a new ticket.

Download

Download the zipped source from here.

Source

You can check out AddHeadersPlugin from here using Subversion, or browse the source with Trac.

Examples

Multi-Style

The following example shows how to add files for a multi-style implementation, i.e. the user can select between different graphics styles: The JavaScript file is located at $TRAC_PROJECT_DIR/htdocs/js/multistyle.js and all CSS files are located at $TRAC_PROJECT_DIR/htdocs/css/. A general style file 'common.css' is included which holds all common style definition. The default style is in 'default.css' and the alternative styles in 'theme1.css' and 'theme2.css'. Please note that general CSS files are added using add_styles while the others using add_links. This has HTML and Trac API related reasons.

# in trac.ini
[addheaders]
default_style_base  = site/css/
default_script_base = site/js/

add_scripts  = multistyle
add_styles   = common
add_links    = style0,style1,style2

style0.rel   = stylesheet
style0.type  = text/css
style0.title = default
style0.href  = /chrome/site/default.css

style1.rel   = alternate stylesheet
style1.type  = text/css
style1.title = theme1
style1.href  = /chrome/site/theme1.css

style2.rel   = alternate stylesheet
style2.type  = text/css
style2.title = theme2
style2.href  = /chrome/site/theme2.css

add_metas = keywords conttype
keywords.content = "Trac Wiki page"

conttype.name = Content-Type
conttype.content = text/html

This will result in the following added headers (not necessary in that order):

<link title="default" type="text/css" href="/chrome/site/style.css" rel="stylesheet" />
<link title="theme1" type="text/css" href="/chrome/site/theme1.css" rel="alternate stylesheet"/>
<link title="theme2" type="text/css" href="/chrome/site/theme2.css" rel="alternate stylesheet"/>
<meta http-equiv="keywords" content="Trac Wiki page" />
<meta http-equiv="Content-Type" content="text/html" />

Adding custom JavaScript and CSS

The following example shows how to add some custom JavaScript and CSS files. Here they all start with a common prefix. The JS files (abc_one.js,abc_two.js,abc_tree.js) are positioned in the $TRAC_PROJECT_DIR/htdocs/js/ and the CSS files (style_print.css,style_screen.css) $TRAC_PROJECT_DIR/htdocs/css/ directory.

# in trac.ini
[addheaders]
default_style_base  = site/css/
default_script_base = site/js/

add_scripts  = abc_one,abc_two,abc_tree
add_styles   = style_print,style_screen

or, even shorter:

# in trac.ini
[addheaders]
default_style_base  = site/css/abc_
default_script_base = site/js/style_

add_scripts  = one,two,tree
add_styles   = print,screen

Weird filenames

While the names given by add_scripts or add_styles is used to build the default filename, it becomes just an arbitrary string when the real filename is set explicitly using <name>.filename. This can be used when the real filename is quit weird, e.g. has commas included or is very long. Make sure to use an UTF-8 capable editor when adding non-ASCII letters.

# in trac.ini
[addheaders]

add_scripts  = short

short.filename = /site/somewhere/Very,weird,filename @;'öäßÖÄß¼€.js
# Also possible to change the MIME-type (default is 'text/javascript')
short.mimetype = text/something

# Same for style files
# General link files must always be set explicitly

General link tag

The link tags are used to define relations between the page and other pages, e.g. 'My startpage is at ..., the next page is at ...'. Trac itself adds a couple of link tags for help, up, prev, etc. for some pages.

The following example would add a linked copyright notice (written plain text) and a shortcut icon to every Trac page. Please note that the information is not displayed by default to the user in any way and most browsers are ignoring link tags which aren't used for style sheets an shortcut icons.

# in trac.ini
[addheaders]
add_links    = cpyrght,icon

cpyrght.rel   = copyright
cpyrght.type  = text/plain
cpyrght.title = Copyright notice
cpyrght.href  = /chrome/site/copyright.txt

icon.rel  = shortcut icon
icon.type = image/x-icon
icon.href = /chrome/site/favicon.ico

This will result in the following added header:

<link title="Copyright notice" type="text/plain" href="/chrome/site/copyright.txt" rel="copyright">
<link type="image/x-icon" href="/chrome/site/icon.ico" rel="shortcut icon">

Recent Changes

[9844] by martin_s on 2011-02-08 18:33:08
tracaddheaders/plugin.py
Made meta name attribute default to the name used in the config file.
[9843] by martin_s on 2011-02-08 18:17:42
0.12
Added 0.12 branch
0.12/tracaddheaders/plugin.py
Added support for meta tags.
[8540] by martin_s on 2010-08-30 23:57:16
Added encoding meta-comment and declared SVN keywords as unicode to avoid issues with non-english locales.

Author/Contributors

Author: martin_s
Contributors: