[[PageOutline(2-5,Contents,pullout)]] = 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 = `'''' (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. `default_meta_lang = `''default language>'' (default: None):: Default language for meta tags (i.e. `lang` and `xml:lang` attributes) `add_scripts = `''''`,`''''`,``...`:: Will add `script` tags for all given names. The mime-type and filename can be defined by: * ''''`.mimetype = `'''' (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: * ''''`.mimetype = `'''' (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 optional: * ''''`.title = `'''' * ''''`.type = `'''' * ''''`.class = `''<(CSS?) class of link>'' `add_meta = `''''`,`''''`,``...`:: Will add [http://en.wikipedia.org/wiki/Meta_element `meta` tags] for all given names. There exists no default setting.[[BR]] [[BR]]One and only one of the following settings must be given: * ''''`.http_equiv = `'''' * ''''`.name = ` Name of meta tag, defaults to '''' * ''''`.scheme = `'''' [[BR]]The content is set using: * ''''`.content = `'''' [[BR]]Optionally the language can be set using: * ''''`.lang = `'''' 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 here] using Subversion, or [source:addheadersplugin 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): {{{ }}} === 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.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: {{{ }}} == Recent Changes == [[ChangeLog(addheadersplugin, 3)]] == Author/Contributors == '''Author:''' [wiki:martin_s] [[BR]] '''Maintainer:''' [wiki:martin_s] [[BR]] '''Contributors:'''