= Add HTML Headers to Trac Pages in a simple way =

== Description ==

This plug-in allows Trac 0.11 server admins to add `script` and `link` 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 ==
Copy the single python file into the '`plugins`' directory of your trac installation and add the following into the config file (normally '`conf/trac.ini`'):

{{{
[components]
addheaders.* = 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.

 `add_scripts = `''<name1>''`,`''<name2>''`,``...`:: Will add `script` tags for all given names. The mime-type and filename can be defined by:
   * ''<name>''`.type = `''<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>''`.type = `''<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.[[BR]]
  [[BR]]The following settings are mandatory:
   * ''<name>''`.rel = `''<Relation of the link>''
   * ''<name>''`.href = `''<Relative URL of the link>''
  [[BR]]The following settings are obtional:
   * ''<name>''`.title = `''<Link title>''
   * ''<name>''`.type = `''<MIME-type of linked content>''
   * ''<name>''`.class = `''<(CSS?) class of link>''


See also the [#Examples example] below.

== Bugs/Feature Requests == 

Existing bugs and feature requests for AddHeadersPlugin are 
[report:9?COMPONENT=AddHeadersPlugin here].

If you have any issues, create a 
[http://trac-hacks.org/newticket?component=AddHeadersPlugin&owner=martin_s new ticket].

== Download ==

Download the zipped source from [download:addheadersplugin here].

== Source ==

You can check out AddHeadersPlugin from [http://trac-hacks.org/svn/addheadersplugin/0.11 here] using Subversion, or [source:addheadersplugin/0.11 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
}}}

This will result in the following added headers:
{{{
<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"/>
}}}

=== 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.type     = text/something

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


== Recent Changes ==

[[ChangeLog(addheadersplugin, 3)]]

== Author/Contributors ==

'''Author:''' [wiki:martin_s] [[BR]]
'''Contributors:'''