= 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 = `'''' (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 = `'''' (default: `default_base`):: To provide an different default path for scripts.
`default_style_base = `'''' (default: `default_base`):: To provide an different default path for style files.
`add_scripts = `''''`,`''''`,``...`:: Will add `script` tags for all given names. The mime-type and filename can be defined by:
* ''''`.type = `'''' (default: '`text/javascript`')
* ''''`.filename = `'''' (default: `default_script_base`''''`.js`)
`add_styles = `''''`,`''''`,``...`:: Will add CSS `link` tags for all given names. The mime-type and filename can be defined by:
* ''''`.type = `'''' (default: '`text/css`')
* ''''`.filename = `'''' (default: `default_style_base`''''`.css`)
`add_link = `''''`,`''''`,``...`:: Will add general `link` tags for all given names. There exists no default setting.[[BR]]
[[BR]]The following settings are mandatory:
* ''''`.rel = `''''
* ''''`.href = `''''
[[BR]]The following settings are obtional:
* ''''`.title = `''''
* ''''`.type = `''''
* ''''`.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
}}}
=== 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 ''''`.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:'''