Changes between Version 57 and Version 58 of WikiTicketCalendarMacro


Ignore:
Timestamp:
May 2, 2011 5:56:20 AM (3 years ago)
Author:
AdrianFritz
Comment:

Changes page structure. Format usage. D.R.Y.

Legend:

Unmodified
Added
Removed
Modified
  • WikiTicketCalendarMacro

    v57 v58  
    11[[PageOutline(2-5,Contents,pullout)]]
    22= Calendar view of Milestones and Tickets =
     3
    34== Description ==
    45
    5 Macro for the Trac Wiki to display Milestones and Tickets from the Ticketing system in a calendar view. The original version of the macro was hosted [http://macgeek.dyndns.org/software/Trac_WikiTicketCalendar here].
    6 
    7 [[Image(wikiticketcalendar_screenshot.gif)]][[BR]]
    8 screenshot of WikiTicketCalendarMacro 1.2.0 for Trac 0.12 with different localizations (wikipage links and CSS style ticket tooltip)
    9 
    10 The ticket 'list_condense' feature looks like [attachment:wikiticketcalendar_screenshot_1-2-1.png this]. Comments welcome.
    11 
    12 Available versions are compatible with Trac 0.11, 0.12 and even the old 0.10 (depreciated/unmaintained, security concerns - see #7239).
    13 Get it, enjoy and report back, please.
    14 [[Poll(What do you think of the WikiTicketCalendarMacro?; Great; Useful; Somewhat useful, but could be better; Useless; Horrible; Don't care/don't need such stuff)]]
    15 
    16 == Bugs/Feature Requests ==
    17 
    18 Existing bugs and feature requests for WikiTicketCalendarMacro are
    19 [query:status!=closed&component=WikiTicketCalendarMacro&order=priority here].
    20 
    21 If you have any issue that is not found [query:component=WikiTicketCalendarMacro&order=priority there], create a
    22 [/newticket?component=WikiTicketCalendarMacro&owner=hasienda new ticket].
    23 
    24 == Download ==
    25 
    26 Download the zipped source from [download:wikiticketcalendarmacro here].[[BR]]
    27 Look at the code and just save a file with the Trac repository browser:
    28  * [browser:wikiticketcalendarmacro/branches/0.10 0.10] depreciated, security concerns unresolved
    29  * [browser:wikiticketcalendarmacro/branches/0.11 0.11]/0.12 ''without'' i18n ^1^
    30  * [browser:wikiticketcalendarmacro/branches/0.12 0.12] with [#Abouti18nl10nsupport i18n support]
    31 
    32 ^1^ Note: The 0.11 single-file macro install is significantly smaller than the Python egg with translations,[[BR]]
    33 and there's no visible difference to the genuine 0.12 version, as long as you don't use localization for Trac 0.12.
    34 
    35 Historically the macro code was activated for a long time by
    36 {{{
    37     [components]
    38     WikiTicketCalendarMacro.* = enabled
    39 }}}
    40 and that is still correct for the ''0.11'' branch.
    41 
    42 The new versions from ''0.12'' and ''trunk'' branch with i18n support have a different code structure due to packaging.[[BR]]
    43 See i18n/l10n section for an '''[#Abouti18nl10nsupport important hint on egg creation]'''. The statement required for activation has changed as well:
    44 {{{
    45     [components]
    46     wikiticketcalendar.* = enabled
    47 }}}
    48 
    49 == Source ==
    50 
    51 You can check out WikiTicketCalendarMacro from [http://trac-hacks.org/svn/wikiticketcalendarmacro here] using Subversion, or [source:wikiticketcalendarmacro browse the source] with Trac.
    52 
    53 == Example ==
    54 
    55 See [#Download download section] on how to activate your version.
    56 
    57 The invocation for the screenshot above is {{{[[WikiTicketCalendar(*,*,true,Wochenberatung/%Y-%m-%d,true,Beratung)]]}}}.[[BR]]
    58 Excerpt of the source documentation:
    59 {{{
    60     Simple Usage
    61     ------------
    62     [[WikiTicketCalendar([year,month,[showbuttons,[wiki_page_format,
    63                           [show_ticket_open_dates,[wiki_page_template,
    64                           [query_expression,[list_condense,[cal_width]]]]]]]])]]
    65 
    66     Arguments
    67     ---------
    68     year, month = display calendar for month in year
    69                   ('*' for current year/month)
    70     showbuttons = true/false, show prev/next buttons
    71     wiki_page_format = strftime format for wiki pages to display as link
    72                        (if exist, otherwise link to create page)
    73                        default is "%Y-%m-%d", '*' for default
    74     show_ticket_open_dates = true/false, show also when a ticket was opened
    75     wiki_page_template = wiki template tried to create new page
    76     list_condense = ticket count limit to switch off ticket summary display
    77     cal_width = set calendar table 'min-width', and optionally 'width'
    78                 for surrounding div triggered by prepending '+' to value
    79 
    80     Advanced Use
    81     ------------
     6Macro for the Trac Wiki to display Milestones and Tickets from the Ticketing system in a calendar view. See screenshot (!WikiTicketCalendarMacro 1.2.0 & Trac 0.12) with different localizations (wikipage links and CSS style ticket tooltip) below:
     7
     8
     9[[Image(wikiticketcalendar_screenshot.gif)]]
     10
     11== Usage ==
     12
     13The invocation for the screenshot above is `[[WikiTicketCalendar(*,*,true,Wochenberatung/%Y-%m-%d,true,Beratung)]]`.
     14
     15Macro can be invoked in the following two basic ways:
     16 A. "Simple"
     17{{{
     18    [[WikiTicketCalendar([<year>,<month>,[<nav>,[<wiki>,[<cdate>,[<template>,[<query>,[<short>,[<width>]]]]]]]])]]
     19}}}
     20 B. "Advanced"
     21{{{
    8222    [[WikiTicketCalendar([nav=(0|1)],[wiki=<strftime-expression>],
    83         [cdate=(0|1)],[base=<wiki_page_template>],[query=<TracQuery-expr],
     23        [cdate=(0|1)],[base=<template>],[query=<TracQuery-expr>],
    8424        [short=<integer-value>],[width=[+]<valid-CSS-size>])]]
    85 
     25}}}
    8626     - equivalent keyword-argument available for all but first two arguments
    8727     - mixed use of keyword-arguments with simple arguments permitted,
     
    9131       including multiple expressions grouped by 'and' and 'or'
    9232
    93     Examples
    94     --------
     33=== Arguments ===
     34
     35||'''Argument'''||'''Version'''||'''Description'''||'''Default'''||'''Example'''||
     36|| `year`|| || specifies the year to be shown, '*' current year || * || year=2011 ||
     37|| `month`|| || specifies the month to be shown, '*'  current month || * || month=12 ||
     38|| `nav`|| || (1) show previous/next navigation or (0) not || 1 || nav=1 ||
     39|| `wiki`|| || strftime format for wiki pages to display as link (if exist, otherwise links to a create page) '*' for default. Supports any expression that strftime can handle  || "%Y-%m-%d" || wiki="%Y-%m-%d" ||
     40|| `cdate`|| || (1) show ticket created / open dates [1,0] || 1 || cdate=1 ||
     41|| `template`|| ||wiki template tried to create new page  || "" || base="" ||
     42|| `query`|| ||evaluates a valid TracQuery expression based on any ticket field including multiple expressions grouped by 'and' and 'or' || || query="id!=0" ||
     43|| `short`|| ||total ticket count per day, that'll have ticket list display condensed to just ticket no., 0 = never condense list. This feature looks like [attachment:wikiticketcalendar_screenshot_1-2-1.png this] [0,1,...] || 0 || short=0 ||
     44|| `width`|| ||set calendar table 'min-width', and optionally 'width' for surrounding div triggered by prepending '+' to value || 100% || width=100% ||
     45
     46=== Examples ===
     47{{{
    9548    [[WikiTicketCalendar(2006,07)]]
    9649    [[WikiTicketCalendar(2006,07,false)]]
     
    10659}}}
    10760 
    108 === Found on the web ===
    109  * a heavily modified version used [https://wiki.ctdo.de/#DiesenMonatimCTDO as event calendar], source unknown
    110 
    111 == Advanced configuration ==
    112 
    113 All maintained versions of this plugin support keyword arguments and mixed use of both - simple and keyword arguments - as well. This could make macro invocations more readable and maybe even shorter than before, as long as you largely stick to the defaults and just want to change one or two values. So i.e. the 3rd example from above could be rewritten now as:
     61
     62'''Notes''':
     63
     641. All maintained versions of this plugin support keyword arguments and mixed use of both - simple and keyword arguments - as well. This could make macro invocations more readable and maybe even shorter than before, as long as you largely stick to the defaults and just want to change one or two values. So i.e. the 3rd example from above could be rewritten now as:
    11465{{{
    11566    [[WikiTicketCalendar(wiki=Meeting-%Y-%m-%d)]]
    11667}}}
    117 
    118 Supported keywords are (with default values here):
    119 {{{
    120 nav=1             same as 'showbuttens'
    121 wiki="%Y-%m-%d"   same as 'wiki_page_format', supports any expression that strftime can handle
    122 cdate=1           same as 'show_ticket_open_dates'
    123 draft=""          same as 'wiki_page_template'
    124 query="id!=0"     see below
    125 short=0           same as 'list_condense', total ticket count per day, that'll have
    126                   ticket list display condensed to just ticket no., 0 = never condense list
    127 width=100%;       same as 'cal_width', check '+' prefixed values, if you need more forceful width definition
    128 }}}
    129 The ''query'' keyword supports any expression supported by TracQuery. This is the single new ticket selection logic that can use custom field values as well as expressions chained by AND (OR since 0.12 only). An invalid expression was chosen on purpose to select and show all tickets by default. Use your own query expression to create per-developer or per-component ticket calendars, or you could choose to display tickets only with high/highest priority, tickets with some special content in a custom field, etc.
    130 
    131 The plugin optionally makes use of an own configuration section, that could be placed into 'trac.ini' as follows:
    132 {{{
    133 [wikiticketcalendar]
    134 ticket.due_field.name = due_close
    135 ticket.due_field.format = %y-%m-%d
    136 }}}
    137 Again these are the implicit default values to give backwards compatible behaviour.
    138 
    139 Real configuration examples:
     682. The ''query'' keyword supports any expression supported by TracQuery. This is the single new ticket selection logic that can use custom field values as well as expressions chained by AND (OR since 0.12 only). An invalid expression was chosen on purpose to select and show all tickets by default. Use your own query expression to create per-developer or per-component ticket calendars, or you could choose to display tickets only with high/highest priority, tickets with some special content in a custom field, etc.
     69
     70
     71== Install ==
     72
     73Generic installation guidelines and troubleshooting can be found at TracPlugins.
     74
     75Steps to install and configure this plugin are:
     76
     77 1. '''Install'''
     78   * Dependencies:
     79      1. ExtractUrlPlugin. Install globally with:
     80{{{
     81#!sh
     82$ sudo https://trac-hacks.org/svn/extracturlplugin/0.11/
     83}}}
     84   * Plugin:
     85      1. with easy_install:
     86{{{
     87#!sh
     88$ sudo easy_install https://trac-hacks.org/svn/mindmapmacro/0.11/
     89}}}
     90 1. '''Enable'''
     91    * Update TracIni file (`..../trac.ini`) with:
     92      * Trac <= 0.11
     93{{{
     94    [components]
     95    WikiTicketCalendarMacro.* = enabled
     96}}}
     97      * Trac >= ''0.12'' and ''trunk'' branch with i18n support (have a different code structure due to packaging)
     98        * See i18n/l10n section for an '''[#Abouti18nl10nsupport important hint on egg creation]'''.
     99{{{
     100    [components]
     101    wikiticketcalendar.* = enabled
     102}}}
     103 1. '''Configure'''
     104    * The plugin optionally makes use of an own configuration section, that could be placed into 'trac.ini' as follows:
     105{{{
     106    [wikiticketcalendar]
     107    ticket.due_field.name = due_close
     108    ticket.due_field.format = %y-%m-%d
     109}}}
     110    * Note: these are the implicit default values to give backwards compatible behaviour.
     111    * Real configuration examples:
     112      * for a custom due date field named 'due-date' that holds US style date with 4-digit year:
    140113{{{
    141114[wikiticketcalendar]
     
    143116ticket.due_field.format = %m/%d/%Y
    144117}}}
    145  * for a custom due date field named 'due-date' that holds
    146  * US style date with 4-digit year
    147 
     118      * for a custom due date field named 'due_date' that holds true POSIX microsecond timestamps (see: [t:wiki:TracDev/Proposals/TracTicketsCustomTimeFields custom time fields proposal])
    148119{{{
    149120[wikiticketcalendar]
     
    151122ticket.due_field.format = ts
    152123}}}
    153  * for a custom due date field named 'due_date' that holds
    154  * true POSIX microsecond timestamps (see: [t:wiki:TracDev/Proposals/TracTicketsCustomTimeFields custom time fields proposal])
    155 
    156 == About i18n/l10n support ==
    157 
    158 The 0.12 branch of this plugin is prepared for localization (tooltip customization in calendar navigation).[[BR]]
     124 1. '''Restart''' web server:
     125{{{
     126#!sh
     127$ sudo /etc/init.d/apache2 restart
     128}}}
     129
     130=== About i18n/l10n support ===
     131
     132The 0.12 branch of this plugin is prepared for localization (tooltip customization in calendar navigation).
     133
    159134But English message texts are still the (POSIX) default. If this isn't your preferred language, you can
    160135 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/wikiticketcalendar Transifex] or
    161136 2. do it yourself (see the [t:wiki:CookBook/PluginL10N#Dotranslatorswork l10n cookbook page for Trac plugins] for more details).
    162137
    163 You've done a new translation? Superb! Contributing your translation is highly appreciated.[[BR]]
     138You've done a new translation? Superb! Contributing your translation is highly appreciated.
     139
    164140You could send it to the plugin's maintainer or contribute to [TracPluginTranslation Trac plugin l10n project]
    165141via [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]:
     
    167143Top translations: Trac_Plugin-L10N » [http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/etcalendar-locale-messages-pot_0/ etcalendar-locale-messages-pot_0][[BR]]
    168144 [[Image(http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/etcalendar-locale-messages-pot_0/chart/image_png, title=Go to Trac_Plugin-L10N project page on Transifex.net, link=http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/etcalendar-locale-messages-pot_0/)]]
     145
    169146Kindly provided by [[Image(http://sw.transifex.net/3/static/charts/images/tx-logo-micro.png, link=http://www.transifex.net/, title=the open translation platform, valign=bottom)]]
    170147
     
    175152python ./setup.py bdist_egg
    176153}}}
    177 Complaints about missing `locale` directory are often a side-effect of failure to compile any message catalog for inclusion into Python egg, hence the whole path is missing. Due to a know Trac issue Babel has to be installed prior to Trac, to get it all working as expected.[[BR]]
     154
     155Complaints about missing `locale` directory are often a side-effect of failure to compile any message catalog for inclusion into Python egg, hence the whole path is missing. Due to a known Trac issue, Babel has to be installed prior to Trac, to get it all working as expected.
     156
    178157Again, for more details see the [t:wiki:CookBook/PluginL10N#Compileanduseit l10n cookbook page for Trac plugins].
    179158
    180 
    181 == Recent Changes ==
     159== Bugs/Feature Requests ==
     160
     161Get it, enjoy and report back, please. Comments welcome.
     162
     163Existing bugs and feature requests for !WikiTicketCalendarMacro are
     164[query:status!=closed&component=WikiTicketCalendarMacro&order=priority here].
     165
     166If you have any issue that is not found [query:component=WikiTicketCalendarMacro&order=priority there], create a
     167[/newticket?component=WikiTicketCalendarMacro&owner=hasienda new ticket].
     168
     169[[Poll(What do you think of the WikiTicketCalendarMacro?; Great; Useful; Somewhat useful, but could be better; Useless; Horrible; Don't care/don't need such stuff)]]
     170
     171== Source & Download ==
     172
     173You can:
     174 A. check out !WikiTicketCalendarMacro from [http://trac-hacks.org/svn/wikiticketcalendarmacro here] using Subversion;
     175 B. or [source:wikiticketcalendarmacro browse the source] and just save a file with the Trac repository browser;
     176    * [browser:wikiticketcalendarmacro/branches/0.12 0.12] with [#Abouti18nl10nsupport i18n support]
     177    * [browser:wikiticketcalendarmacro/branches/0.11 0.11]/0.12 ''without'' i18n ^1^
     178    * [browser:wikiticketcalendarmacro/branches/0.10 0.10] depreciated/unmaintained, security concerns unresolved - see #7239.
     179 C. or download the zipped source from [download:wikiticketcalendarmacro here];
     180
     181^1^ Note: The 0.11 single-file macro install is significantly smaller than the Python egg with translations,[[BR]]
     182and there's no visible difference to the genuine 0.12 version, as long as you don't use localization for Trac 0.12.
     183
     184^2^ Note: The original version of the macro was hosted [http://macgeek.dyndns.org/software/Trac_WikiTicketCalendar here] and it's outdated.
     185
     186=== Recent Changes ===
    182187
    183188[[ChangeLog(wikiticketcalendarmacro, 3)]]
     
    188193'''Maintainer:''' [wiki:hasienda][[BR]]
    189194'''Contributors:''' Boris Savelev, [wiki:rjollos]
     195
     196== See also ==
     197
     198=== Found on the web ===
     199
     200 * a heavily modified version used [https://wiki.ctdo.de/#DiesenMonatimCTDO as event calendar], source unknown