Changes between Version 51 and Version 52 of TagsPlugin


Ignore:
Timestamp:
Nov 29, 2011 3:12:10 AM (3 years ago)
Author:
AdrianFritz
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]]