Changes between Version 25 and Version 26 of AddHeadersPlugin


Ignore:
Timestamp:
May 15, 2022, 7:09:38 AM (2 years ago)
Author:
figaro
Comment:

Move examples to functional description

Legend:

Unmodified
Added
Removed
Modified

  • AddHeadersPlugin

    v25 v26  
    55== Description
    66
    7 This plugin 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.
     7This plugin allows Trac server administratorss to add `script`, `link` and `meta` headers into all Trac pages without having to create a Chrome template file.
    88This allows the easy usage of own !JavaScript and CSS files. Also all other kinds of `link` headers can be added.
    99
    10 See below for examples.
     10The following are some examples of the plugins usage.
     11
     12=== Multi-Style
     13
     14The following example shows how to add files for a multi-style implementation, so that the user can select between different graphics styles:
     15The !JavaScript file is located at `$TRAC_PROJECT_DIR/htdocs/js/multistyle.js` and all CSS files are located at `$TRAC_PROJECT_DIR/htdocs/css/`.
     16A 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`.
     17
     18Note that general CSS files are added using `add_styles`, while the others are using `add_links`. This has HTML and Trac API related reasons.
     19
     20{{{#!ini
     21[addheaders]
     22default_style_base  = site/css/
     23default_script_base = site/js/
     24
     25add_scripts  = multistyle
     26add_styles   = common
     27add_links    = style0,style1,style2
     28
     29style0.rel   = stylesheet
     30style0.type  = text/css
     31style0.title = default
     32style0.href  = /chrome/site/default.css
     33
     34style1.rel   = alternate stylesheet
     35style1.type  = text/css
     36style1.title = theme1
     37style1.href  = /chrome/site/theme1.css
     38
     39style2.rel   = alternate stylesheet
     40style2.type  = text/css
     41style2.title = theme2
     42style2.href  = /chrome/site/theme2.css
     43
     44add_metas = keywords conttype
     45keywords.content = "Trac Wiki page"
     46
     47conttype.name = Content-Type
     48conttype.content = text/html
     49}}}
     50
     51This will result in the following added headers, not necessarily in that order:
     52{{{#!html
     53<link title="default" type="text/css" href="/chrome/site/style.css" rel="stylesheet" />
     54<link title="theme1" type="text/css" href="/chrome/site/theme1.css" rel="alternate stylesheet" />
     55<link title="theme2" type="text/css" href="/chrome/site/theme2.css" rel="alternate stylesheet" />
     56<meta http-equiv="keywords" content="Trac Wiki page" />
     57<meta http-equiv="Content-Type" content="text/html" />
     58}}}
     59
     60=== Adding custom !JavaScript and CSS
     61
     62The 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.
     63
     64{{{#!ini
     65# in trac.ini
     66[addheaders]
     67default_style_base = site/css/
     68default_script_base = site/js/
     69
     70add_scripts = abc_one,abc_two,abc_tree
     71add_styles = style_print,style_screen
     72}}}
     73
     74or, even shorter:
     75
     76{{{#!ini
     77# in trac.ini
     78[addheaders]
     79default_style_base = site/css/abc_
     80default_script_base = site/js/style_
     81
     82add_scripts = one,two,tree
     83add_styles = print,screen
     84}}}
     85
     86=== Unusual filenames
     87
     88While 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`.
     89This can be used when the real filename is unusual, eg has commas included or is very long. Make sure to use an UTF-8 capable editor when adding non-ASCII letters.
     90{{{#!ini
     91# in trac.ini
     92[addheaders]
     93
     94add_scripts = short
     95
     96short.filename = /site/somewhere/Very,weird,filename @;'öäßÖÄß¼€.js
     97# Also possible to change the MIME-type (default is 'text/javascript')
     98short.mimetype = text/something
     99
     100# Same for style files
     101# General link files must always be set explicitly
     102}}}
     103
     104=== General `link` tag
     105
     106The `link` tags are used to define ''relations'' between the page and other pages, for example '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.
     107
     108The following example would add a linked copyright notice (written in plain text) and a shortcut icon to every Trac page. 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 or shortcut icons.
     109
     110{{{#!ini
     111# in trac.ini
     112[addheaders]
     113add_links    = cpyrght,icon
     114
     115cpyrght.rel   = copyright
     116cpyrght.type  = text/plain
     117cpyrght.title = Copyright notice
     118cpyrght.href  = /chrome/site/copyright.txt
     119
     120icon.rel  = shortcut icon
     121icon.type = image/x-icon
     122icon.href = /chrome/site/favicon.ico
     123}}}
     124
     125This will result in the following added header:
     126{{{
     127<link title="Copyright notice" type="text/plain" href="/chrome/site/copyright.txt" rel="copyright">
     128<link type="image/x-icon" href="/chrome/site/icon.ico" rel="shortcut icon">
     129}}}
    11130
    12131== Bugs/Feature Requests
    … …  
    42161== Configuration
    43162
    44 The plugin is controlled through settings in the TracIni file. All settings must be put in the section `[addheaders]`.
    45 
    46  `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 eg `http://trac.example.org/project1/`. Note that URL paths are used, not local file paths. The default is `site/` which is the relative URL for the `htdocs` directory in your `$TRAC_PROJECT_DIR`.
    47 
    48  `default_script_base = `''<path relative to base URL>'' (default: `default_base`):: To provide a different default path for scripts.
    49 
    50  `default_style_base = `''<path relative to base URL>'' (default: `default_base`):: To provide a different default path for style files.
     163The plugin is controlled through settings in the TracIni file. All settings must be placed in the section `[addheaders]`.
     164
     165 `default_base = `''<path relative to base URL>'' (default: '`site/`'):: Default base of the files relative to the base URL, which is eg `http://trac.example.org/project1/`. Note that URL paths are used, not local file paths. The default is `site/` which is the relative URL for the `htdocs` directory in your `$TRAC_PROJECT_DIR`.
     166
     167 `default_script_base = `''<path relative to base URL>'' (default: `default_base`):: Provide a different default path for scripts.
     168
     169 `default_style_base = `''<path relative to base URL>'' (default: `default_base`):: Provide a different default path for style files.
    51170
    52171 `default_meta_lang = `''default language>'' (default: None):: Default language for meta tags, ie `lang` and `xml:lang` attributes.
    53172
    54  `add_scripts = `''<name1>''`,`''<name2>''`,``...`:: Will add `script` tags for all given names. The mime-type and filename can be defined by:
     173 `add_scripts = `''<name1>''`,`''<name2>''`,``...`:: Adds `script` tags for all given names. The mime-type and filename can be defined by:
    55174   * ''<name>''`.mimetype = `''<MIME-type>'' (default: '`text/javascript`')
    56175   * ''<name>''`.filename = `''<filename incl. path>'' (default: `default_script_base`''<name>''`.js`)
    57176
    58  `add_styles = `''<name1>''`,`''<name2>''`,``...`:: Will add CSS `link` tags for all given names. The mime-type and filename can be defined by:
     177 `add_styles = `''<name1>''`,`''<name2>''`,``...`:: Adds CSS `link` tags for all given names. The mime-type and filename can be defined by:
    59178   * ''<name>''`.mimetype = `''<MIME-type>'' (default: '`text/css`')
    60179   * ''<name>''`.filename = `''<filename incl. path>'' (default: `default_style_base`''<name>''`.css`)
    61180
    62  `add_link = `''<name1>''`,`''<name2>''`,``...`:: Will add general `link` tags for all given names. There exists no default setting.[[BR]]
     181 `add_link = `''<name1>''`,`''<name2>''`,``...`:: Adds general `link` tags for all given names. There exists no default setting.[[BR]]
    63182  [[BR]]The following settings are mandatory:
    64183   * ''<name>''`.rel = `''<Relation of the link>''
    … …  
    69188   * ''<name>''`.class = `''<(CSS?) class of link>''
    70189
    71  `add_meta = `''<name1>''`,`''<name2>''`,``...`:: Will add [wikipedia:Meta_element `meta` tags] for all given names. There is no default setting.[[BR]]
     190 `add_meta = `''<name1>''`,`''<name2>''`,``...`:: Adds [wikipedia:Meta_element `meta` tags] for all given names. There is no default setting.[[BR]]
    72191  [[BR]]One and only one of the following settings must be given:
    73192   * ''<name>''`.http_equiv = `''<equivalent HTTP header>''
    … …  
    79198   * ''<name>''`.lang = `''<language of meta tag>''
    80199
    81 == Examples
    82 
    83 === Multi-Style
    84 
    85 The following example shows how to add files for a multi-style implementation, so that the user can select between different graphics styles:
    86 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/`.
    87 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`.
    88 
    89 Note that general CSS files are added using `add_styles`, while the others are using `add_links`. This has HTML and Trac API related reasons.
    90 
    91 {{{#!ini
    92 [addheaders]
    93 default_style_base  = site/css/
    94 default_script_base = site/js/
    95 
    96 add_scripts  = multistyle
    97 add_styles   = common
    98 add_links    = style0,style1,style2
    99 
    100 style0.rel   = stylesheet
    101 style0.type  = text/css
    102 style0.title = default
    103 style0.href  = /chrome/site/default.css
    104 
    105 style1.rel   = alternate stylesheet
    106 style1.type  = text/css
    107 style1.title = theme1
    108 style1.href  = /chrome/site/theme1.css
    109 
    110 style2.rel   = alternate stylesheet
    111 style2.type  = text/css
    112 style2.title = theme2
    113 style2.href  = /chrome/site/theme2.css
    114 
    115 add_metas = keywords conttype
    116 keywords.content = "Trac Wiki page"
    117 
    118 conttype.name = Content-Type
    119 conttype.content = text/html
    120 }}}
    121 
    122 This will result in the following added headers, not necessarily in that order:
    123 {{{#!html
    124 <link title="default" type="text/css" href="/chrome/site/style.css" rel="stylesheet" />
    125 <link title="theme1" type="text/css" href="/chrome/site/theme1.css" rel="alternate stylesheet" />
    126 <link title="theme2" type="text/css" href="/chrome/site/theme2.css" rel="alternate stylesheet" />
    127 <meta http-equiv="keywords" content="Trac Wiki page" />
    128 <meta http-equiv="Content-Type" content="text/html" />
    129 }}}
    130 
    131 === Adding custom !JavaScript and CSS
    132 
    133 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.
    134 
    135 {{{#!ini
    136 # in trac.ini
    137 [addheaders]
    138 default_style_base = site/css/
    139 default_script_base = site/js/
    140 
    141 add_scripts = abc_one,abc_two,abc_tree
    142 add_styles = style_print,style_screen
    143 }}}
    144 
    145 or, even shorter:
    146 
    147 {{{#!ini
    148 # in trac.ini
    149 [addheaders]
    150 default_style_base = site/css/abc_
    151 default_script_base = site/js/style_
    152 
    153 add_scripts = one,two,tree
    154 add_styles = print,screen
    155 }}}
    156 
    157 === Unusual filenames
    158 
    159 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`.
    160 This can be used when the real filename is unusual, eg has commas included or is very long. Make sure to use an UTF-8 capable editor when adding non-ASCII letters.
    161 {{{#!ini
    162 # in trac.ini
    163 [addheaders]
    164 
    165 add_scripts = short
    166 
    167 short.filename = /site/somewhere/Very,weird,filename @;'öäßÖÄß¼€.js
    168 # Also possible to change the MIME-type (default is 'text/javascript')
    169 short.mimetype = text/something
    170 
    171 # Same for style files
    172 # General link files must always be set explicitly
    173 }}}
    174 
    175 === General `link` tag
    176 
    177 The `link` tags are used to define ''relations'' between the page and other pages, for example '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.
    178 
    179 The following example would add a linked copyright notice (written in plain text) and a shortcut icon to every Trac page. 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 or shortcut icons.
    180 
    181 {{{#!ini
    182 # in trac.ini
    183 [addheaders]
    184 add_links    = cpyrght,icon
    185 
    186 cpyrght.rel   = copyright
    187 cpyrght.type  = text/plain
    188 cpyrght.title = Copyright notice
    189 cpyrght.href  = /chrome/site/copyright.txt
    190 
    191 icon.rel  = shortcut icon
    192 icon.type = image/x-icon
    193 icon.href = /chrome/site/favicon.ico
    194 }}}
    195 
    196 This will result in the following added header:
    197 {{{
    198 <link title="Copyright notice" type="text/plain" href="/chrome/site/copyright.txt" rel="copyright">
    199 <link type="image/x-icon" href="/chrome/site/icon.ico" rel="shortcut icon">
    200 }}}
    201 
    202200== Recent Changes
    203201