Changes between Version 51 and Version 52 of TagsPlugin


Ignore:
Timestamp:
Nov 29, 2011, 2:12:10 AM (12 years ago)
Author:
Adrian Fritz
Comment:

Page refactor

Legend:

Unmodified
Added
Removed
Modified

  • TagsPlugin

    v51 v52  
    1 [[PageOutline]]
    2 
    3 {{{
    4 #!html
    5 <div style="background: #afa; padding: 1em; margin: 2em; width: 50%; border: 1px solid green;">
    6 <strong>Note:</strong> Version 0.6 is a complete rewrite for Trac 0.11. This page documents that version. Refer to <a href="TagsPlugin/0.5">this page</a> for information on older versions of the plugin. Also works on Trac 0.12.
    7 </div>
    8 }}}
     1[[PageOutline(2-5,Contents,pullout)]]
     2
     3[[html(<div id="newsflash" style="clear:right">)]]
     4'''News'''
     5 2011-07-06:: Version 0.6 is a complete rewrite for Trac 0.11. This page documents that version. Refer to ["TagsPlugin/0.5"] for information on older versions of the plugin. Also works on Trac 0.12.
     6'''!ToDo'''
     7 * T.B.D.
     8[[html(</div>)]]
    99
    1010= A Tagging System for Trac =
    … …  
    1212The TagsPlugin implements both a generic tagging engine, and frontends for the Wiki and ticket systems. An extra text entry box is added to the Wiki edit page for tagging Wiki pages, and ticket fields (you can configure which ones) are treated as tags for the ticket system.
    1313
    14 The TagsPlugin was originally created by [wiki:muness Muness Alrubaie] but has since been completely rewritten by [wiki:athomas Alec Thomas].
     14The TagsPlugin was originally created by [wiki:muness Muness Alrubaie] but has since been completely rewritten by [wiki:athomas Alec Thomas], and now maintained by hasienda.
    1515
    1616See also: KeywordSuggestPlugin, LoomingCloudsPlugin
    1717
    18 == Bugs/Feature Requests ==
    19 Check the
    20 [query:?status=new&status=assigned&status=reopened&group=&component=TagsPlugin&order=priority existing bugs and feature requests]. If you have additional issues, create a
    21 [/newticket?component=TagsPlugin&owner=hasienda new ticket].
    22 
    23 == Download ==
    24 
    25 Download the zipped source from [download:tagsplugin here].
    26 
    27 == Source ==
    28 
    29 You can check out TagsPlugin from [http://trac-hacks.org/svn/tagsplugin here] using Subversion, or [source:tagsplugin browse the source] with Trac.
    30 
    31 == Installing ==
    32 
    33   1. install
    34     * By hand:
    35       1. Download tags: [download:tagsplugin/tags/0.6 tags-0.6.zip] or grab
    36          [/svn/tagsplugin/tags/0.6 the source] from SVN.
    37       2. [trac:wiki:TracPlugins Build and install an egg] from this source.
    38     * Using easy_install:
    39       {{{
    40       easy_install http://trac-hacks.org/svn/tagsplugin/tags/0.6
    41       }}}
    42   4. Configure appropriately for your version of Trac.
    43     Update your [wiki:TracIni trac.ini] with this:
    44     {{{
    45     [components]
    46     tractags.* = enabled
    47     }}}
    48     Be sure to remove any previous TagsPlugin configuration changes. In  particular `trac.wiki.web_ui.wikimodule = disabled` and `default_handler = TagsWikiModule` '''must be removed'''.
    49   5. Run `trac-admin <env> upgrade` on your Trac environment.
    50   6. Restart your web server.
    51   7. Grant `TAGS_VIEW` and `TAGS_MODIFY` permissions to your users according to the policies that you'd like to implement.
    52 
    53 At this stage the plugin should be working and you should see a text control for
    54 tags in your Wiki edit page. You should also see an entry in the main navigation
    55 bar labeled ''Tags''.
    56 
    57 == Configuring TagsPlugin ==
    58 
    59 Tags 0.6 has vastly simplified the configuration to the point where there are only two options, both of which are under the `[tags]` section:
    60 
    61 `ignore_closed_tickets = <bool>`
    62   Whether to gather tags from closed tickets.
    63 
    64 `ticket_fields = <field>[, <field> ...]`
    65   eg. `ticket_fields = component, keywords`.
    66 
    67   Ticket fields from which to gather tags. Defaults to `keywords`. Custom fields are currently not supported.
    68 
    69 
    70 == What are tags? ==
     18=== What are tags? ===
     19
    7120Tags are like hierarchically organized wiki entries, however with them you can categorize a wiki entry under multiple tags and not just under one hierarchy.  You can then search for wiki entries categorized under a tag or a collection of tags.  In other words, tags provide a [http://en.wikipedia.org/wiki/Faceted_classification faceted classification system] for the Trac wiki.
    7221
    … …  
    7928This implementation of wiki tagging is specific to [wiki:TracGuide Trac]. To stay consistent with the way Trac names wiki entries, tags are case sensitive. Trac Hacks itself makes extensive use of tagging and is a good example of their use.
    8029
    81 === How do I apply tags? ===
     30== Usage ==
     31
     32=== Apply tags ===
     33
    8234To create a tag, follow these steps:
    8335
    … …  
    8941The wiki entry you edit is now categorized under the tags you specified.
    9042
    91 === How do I remove a tag from a wiki entry? ===
     43=== Remove tags ===
    9244
    9345To remove a tag from a wiki entry
    … …  
    9749 4. Click ''Save changes''.
    9850
    99 == Using the tags ==
    100 
    101 Querying is implemented through the /tags uri handler, `the tag:<tag>` syntax or [http://projects.edgewall.com/trac/wiki/WikiMacros Trac Macros] as follows
    102 
    103 === /tags handler ===
    104 
    105 Going to /tags under your project will show a list of all tags in the wiki.  /tags/?q=<expression> will show all the objects matching ''<expression>''.  e.g. [http://trac-hacks.org/tags/?q=plugin]. This accepts all the parameters that the !ListTagged macro does.  e.g. [http://trac-hacks.org/tags?q=plugin%20or%20macro].
    106 
    107 
    108 
    109 == `tag:<tag>` or `tagged:<expr>` Usage ==
    110 
    111 Both forms are identical and link to the tag search results for the expression.
    112 
    113 e.g. `tagged:todo` or `tagged:"plugin macro"`.
    114 
    115 == Tag expressions ==
     51=== Searching tags ===
     52
     53Querying is implemented through the /tags uri handler, `the tag:<tag>` syntax or [http://projects.edgewall.com/trac/wiki/WikiMacros Trac Macros] as follows.
     54
     55==== Tags expressions ====
    11656
    11757Both the `ListTagged` macro and the `/tags` handler use a basic expression language for filtering tagged objects.
    … …  
    12969Expressions and individual tags can be quoted with single `'` or double `"` quotes.
    13070
    131 === Examples ===
    132 
    133 Intersection of `macro` and `plugin` tags:
    134         `tagged:"macro plugin"`
    135 
    136 Union of `macro` and `plugin` tags:
    137         `tagged:"macro or plugin"`
    138 
    139 Objects tagged `macro` or `plugin`, ''and'' `example`
    140         `tagged:"(macro or plugin) example"`
    141 
    142 == Macro Usage ==
    143 
    144 === !ListTagged ===
    145 
    146 `[[ListTagged(<expr>)]]`
    147 
    148 This will display a list of resources whose tags match `<expr>`.
    149 
    150 ==== Examples ====
    151 
    152 Intersection of `macro` and `plugin` tags:
    153         `[[ListTagged(macro plugin)]]`
    154 
    155 All resources tagged  `macro` but not `plugin`:
    156         `[[ListTagged(macro -plugin)]]`
    157 
    158 Tickets tagged with `macro`:
    159         `[[ListTagged(realm:ticket macro)]]`
    160 
    161 Pages tagged with `macro`:
    162         `[[ListTagged(realm:wiki macro)]]`
    163 
    164 === !TagCloud ===
     71 Examples::
     72   1. Intersection of `macro` and `plugin` tags:        `tagged:"macro plugin"`
     73   1. Union of `macro` and `plugin` tags:       `tagged:"macro or plugin"`
     74   1. Objects tagged `macro` or `plugin`, ''and'' `example`     `tagged:"(macro or plugin) example"`
     75
     76==== /tags handler ====
     77
     78Going to /tags under your project will show a list of all tags in the wiki.  /tags/?q=<expression> will show all the objects matching ''<expression>''.  e.g. [http://trac-hacks.org/tags/?q=plugin]. This accepts all the parameters that the !ListTagged macro does.  e.g. [http://trac-hacks.org/tags?q=plugin%20or%20macro].
     79
     80==== `tag:<tag>` or `tagged:<expression>` Usage ====
     81
     82Both forms are identical and link to the tag search results for the expression.
     83
     84 Example::
     85  * `tagged:todo` or `tagged:"plugin macro"`.
     86
     87==== !ListTagged macro ====
     88
     89`[[ListTagged(<expression>)]]`
     90
     91This will display a list of resources whose tags match `<expression>`.
     92
     93 Examples::
     94  * Intersection of `macro` and `plugin` tags:  `[[ListTagged(macro plugin)]]`
     95  * All resources tagged  `macro` but not `plugin`:     `[[ListTagged(macro -plugin)]]`
     96  * Tickets tagged with `macro`:         `[[ListTagged(realm:ticket macro)]]`
     97  * Pages tagged with `macro`:         `[[ListTagged(realm:wiki macro)]]`
     98
     99==== !TagCloud macro ====
    165100
    166101`[[TagCloud(-Dummy)]]`
    … …  
    168103Display a cloud of all  tags, assuming you do not use the  '''Dummy''' tag.
    169104
     105
     106== Install ==
     107
     108Generic installation guidelines are troubleshooting can be found at TracPlugins.
     109
     110Steps to install and configure this plugin are:
     111
     112 1. '''Install'''
     113   * Dependencies:
     114      1. None:
     115   * Plugin:
     116      1. Manually:
     117         1. Download tags: [download:tagsplugin/tags/0.6 tags-0.6.zip] or grab
     118            [/svn/tagsplugin/tags/0.6 the source] from SVN.
     119         2. [trac:wiki:TracPlugins Build and install an egg] from this source.
     120      1. with easy_install:
     121{{{
     122#!sh
     123$ sudo easy_install https://trac-hacks.org/svn/tagsplugin/tags/0.6
     124}}}
     125 1. '''Configure'''
     126    * Tags 0.6 has vastly simplified the configuration to the point where there are only two options, both of which are under the `[tags]` section:
     127      1. `ignore_closed_tickets = <bool>`
     128          * Whether to gather tags from closed tickets.
     129      1. `ticket_fields = <field>[, <field> ...]`
     130          * eg. `ticket_fields = component, keywords`.
     131          * Ticket fields from which to gather tags. Defaults to `keywords`. Custom fields are currently not supported.
     132      * Note:: Be sure to remove any previous TagsPlugin configuration changes. In  particular `trac.wiki.web_ui.wikimodule = disabled` and `default_handler = TagsWikiModule` '''must be removed'''.
     133 1. '''Enable'''
     134    * Update your TracIni file (`..../trac.ini`) with:
     135{{{
     136[components]
     137tractags.* = enabled
     138}}}
     139 1. '''Run''' on your Trac environment
     140    {{{
     141    #!sh
     142    $ trac-admin <env> upgrade
     143    }}}
     144 1. '''Restart''' web server:
     145    {{{
     146    #!sh
     147    $ sudo /etc/init.d/apache2 restart
     148    }}}
     149 1. '''Grant''' `TAGS_VIEW` and `TAGS_MODIFY` permissions to your users according to the policies that you'd like to implement.
     150 
     151
     152At this stage the plugin should be working and you should see a text control for
     153tags in your Wiki edit page. You should also see an entry in the main navigation
     154bar labeled ''Tags''.
     155
    170156=== About i18n/l10n support ===
    171157
    172 The development version of this plugin is prepared for localization.[[BR]]
     158The development version of this plugin is prepared for localization.
     159
    173160But English message texts are still the (POSIX) default. If this isn't your preferred language, you can
    174161 1. look, if it's already available from the [TracPluginTranslation Trac plugin l10n project] at [http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/tractags Transifex] or
    175162 2. do it yourself (see the [http://trac.edgewall.org/wiki/CookBook/PluginL10N#Dotranslatorswork l10n cookbook page for Trac plugins] for more details).
    176163
    177 You've done a new translation? Superb! Contributing your translation is highly appreciated.[[BR]]
     164You've done a new translation? Superb! Contributing your translation is highly appreciated.
     165
    178166You could send it to the plugin's maintainer or contribute to [TracPluginTranslation Trac plugin l10n project]
    179167via [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]:
    … …  
    192180Again, for more details see the [t:wiki:CookBook/PluginL10N#Compileanduseit l10n cookbook page for Trac plugins].
    193181
    194 === Change Log ===
    195 
    196 [[ChangeLog(/tagsplugin, 3)]]
    197 
    198 === Author/Contributors ===
     182== Bugs & Feature Requests ==
     183
     184Check the [query:?status=new&status=assigned&status=reopened&group=&component=TagsPlugin&order=priority existing bugs and feature requests]. If you have additional issues, create a [/newticket?component=TagsPlugin&owner=hasienda new ticket].
     185
     186== Source & Download ==
     187
     188You can check out !TagsPlugin from [http://trac-hacks.org/svn/tagsplugin here] using Subversion, or [source:tagsplugin browse the source] with Trac.
     189
     190You can also download the zipped source from [download:tagsplugin here].
     191
     192=== Most Recent Changes ===
     193
     194[[ChangeLog(/tagsplugin, 2)]]
     195
     196== Author/Contributors ==
    199197
    200198'''Author:''' athomas [[BR]]