Editing WikiCalendarMacro

[[PageOutline(2-5,Contents,pullout)]] = Small calendar with days linking to wiki pages == Description {{{#!comment The functional description and a screenshot from WikiTicketCalendarMacro has been added to this page and therefore requires cleanup to match with what the plugin actually offers. (2016-11-22). }}} This plugin inserts a small calendar where each day links to a wiki page whose name matches the `wiki-page-format` argument. The current day is highlighted, and days with Milestones are marked in bold. It can be used for maintaining a calendar of meeting minutes or any situation where the wiki page name is based on the date. It is designed to work well with the [trac:MacroBazaar#Blog Blog] macro, so if a previous month is selected from the Blog, the calendar will display the selected month. Non-existent pages link directly to the edit form for the requested page to make it easy to add new meeting minutes pages. It uses the time format syntax from the Python [http://python.org/doc/current/lib/module-time.html time module]'s {{{strftime}}} method. Resolution of relative wiki paths is available. A heavily modified version is used [https://wiki.ctdo.de/#DiesenMonatimCTDO here as event calendar], source unknown. == Usage Enter `[[WikiTicketCalendar(*,*,true,Wochenberatung/%Y-%m-%d,true,Beratung)]]` in your wiki page to achieve the following: [[Image(wiki-calendar-screen.2.png, border=2​)]] The calendar can be invoked in the following two basic ways: '''Simple''' {{{ [[WikiTicketCalendar([<year>,<month>,[<nav>,[<wiki>,[<cdate>,[<template>,[<query>,[<short>,[<width>]]]]]]]])]] }}} '''Advanced''' {{{ [[WikiTicketCalendar([nav=(0|1)],[wiki=<strftime-expression>], [cdate=(0|1)],[base=<template>],[query=<TracQuery-expr>], [short=<integer-value>],[width=[+]<valid-CSS-size>])]] }}} - equivalent keyword-argument available for all but first two arguments - mixed use of keyword-arguments with simple arguments permitted, but strict order of simple arguments (see above) still applies while keyword-arguments in-between do not count for that positional mapping, - query evaluates a valid TracQuery expression based on any ticket field including multiple expressions grouped by 'and' and 'or' === Arguments ||'''Argument'''||'''Description'''||'''Default'''||'''Example'''|| || `year`|| specifies the year to be shown, '*' current year || * || year=2011 || || `month`|| specifies the month to be shown, '*' current month || * || month=12 || || `nav`|| (1) show previous/next navigation or (0) not || 1 || nav=1 || || `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" || || `cdate`|| (1) show ticket created / open dates [1,0] || 1 || cdate=1 || || `base`|| wiki template tried to create new page || "" || base="" || || `query`|| evaluates a valid TracQuery expression based on any ticket field including multiple expressions grouped by 'and' and 'or' || || query="id!=0" || || `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 || || `width`|| set calendar table 'min-width', and optionally 'width' for surrounding div triggered by prepending '+' to value || 100% || width=100% || === Examples {{{ [[WikiTicketCalendar(2006,07)]] [[WikiTicketCalendar(2006,07,false)]] [[WikiTicketCalendar(*,*,true,Meeting-%Y-%m-%d)]] [[WikiTicketCalendar(2006,07,false,Meeting-%Y-%m-%d)]] [[WikiTicketCalendar(2006,07,true,*,true)]] [[WikiTicketCalendar(2006,07,true,Meeting-%Y-%m-%d,true,Meeting)]] [[WikiTicketCalendar(wiki=Talk-%Y-%m-%d,base=Talk)]] equivalent to [[WikiTicketCalendar(*,*,true,Talk-%Y-%m-%d,true,Talk)]] [[WikiTicketCalendar(wiki=Meeting-%Y-%m-%d,query=type=task&owner=wg1)]] [[WikiTicketCalendar(wiki=Meeting_%Y/%m/%d,short=6)]] [[WikiTicketCalendar(*,*,true,Meeting-%Y%m%d,width=+75%;)]] }}} '''Notes''': 1. All maintained versions of this macro 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: {{{ [[WikiTicketCalendar(wiki=Meeting-%Y-%m-%d)]] }}} 1. 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 for expressions chained by AND (OR since 0.12 only). An always-true 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. Usage: {{{ [[WikiCalendar([year, [month, [show-buttons, [wiki-page-format]]]])]] }}} Arguments: 1. `year` (4-digit year) - defaults to `*` (current year) 1. `month` (2-digit month) - defaults to `*` (current month) 1. `show-buttons` (boolean) - defaults to `true` 1. `wiki-page-format` (string) - defaults to `%Y-%m-%d` {{{ [[WikiCalendar(2006,07)]] [[WikiCalendar(2006,07,false)]] [[WikiCalendar(*,*,true,Meeting-%Y-%m-%d)]] [[WikiCalendar(2006,07,false,Meeting-%Y-%m-%d)]] }}} Relative wiki paths are supported as well, which is especially relevant if you later change position of the wiki page containing the !WikiCalendarMacro relative to the stack of related wiki pages: {{{ [[WikiCalendar(*,*,true,../Meeting/%Y-%m-%d)]] }}} The calendar will be displayed as follows (border added for visibility): [[Image(20130421_wikicalendar_screenshot.gif, border=2)]] Screenshots using `[[WikiCalendar(w)]]` (for week numbers) with different browser locale settings. '''New:''' Since wikicalendar-2.1 both macros are able to display week numbers. Just add a 'w' to your macro arguments (argument position doesn't matter). With `Babel` installed you even get Sunday as first day of the week and week numbers localized according to your browser settings. == Bugs/Feature Requests Existing bugs and feature requests for WikiCalendarMacro are [report:9?COMPONENT=WikiCalendarMacro here]. If you have any issues, create a [/newticket?component=WikiCalendarMacro new ticket]. [[TicketQuery(component=WikiCalendarMacro&group=type,format=progress)]] == Download Download the zipped source from [export:wikicalendarmacro here]. == Source You can check out the source for !WikiCalendarMacro from Subversion [/svn/wikicalendarmacro here] or [source:wikicalendarmacro browse the source] with Trac. == Installation Requires Trac >= 0.11.3. After [11741] you should be able to use the plugin even with Trac 0.11. If you experience strange results (see #8818 for an [attachment:ticket:8818:wtc.jpg example]), you may want to force CSS definitions into the HTML page with the following option: {{{#!ini [wikicalendar] internal_css = True ticket.due_field = due_close ticket.due_field.format = %y-%m-%d }}} Available since [11746], WikiTicketCalendarMacro options supported since [11749]. To upgrade this plugin, rename your old `[wikiticketcalendar]` section, and the required option name change `ticket.due_field.name --> ticket.due_field.name` will be done automatically for you. == About i18n/l10n support These macros are prepared for localization (tooltip customization in calendar navigation and localized macro description). But English message texts are still the (POSIX) default. If this isn't your preferred language, you can 1. check if it's already available from the [TracPluginTranslation Trac plugin l10n project] at [https://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/wikicalendar Transifex] or 1. do it yourself, see the [t:wiki:CookBook/PluginL10N#Dotranslatorswork l10n cookbook page for Trac plugins] for more details. Contributing your translation is highly appreciated.[[BR]] You could send it to the plugin's maintainer or contribute to [TracPluginTranslation Trac plugin l10n project] via [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]: Top translations: Trac_Plugin-L10N » [https://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/wikicalendar/ wikicalendar] [[Image(http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/wikicalendar/chart/image_png, title=Go to Trac_Plugin-L10N project page on Transifex.net, link=https://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/wikicalendar/)]] Preparing the plugin from source requires '''no additional steps''' for compiling message catalog files. Only to include translations marked as `# fuzzy` by the translator, you'll want to do a manual message catalog compilation with the extra `-f` argument before packaging: {{{ cd wikicalendarmacro/ python ./setup.py compile_catalog -f python ./setup.py bdist_egg }}} 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 known Trac issue, Babel has to be installed prior to Trac, to get it all working as expected. Again, for more details see the [t:wiki:CookBook/PluginL10N#Compileanduseit l10n cookbook page for Trac plugins]. == Recent Changes [[ChangeLog(wikicalendarmacro, 3)]] == Author/Contributors '''Author:''' [wiki:mgood mgood] [[BR]] '''Maintainer:''' [[Maintainer]] [[BR]] '''Contributors:''' JoshuaH, [mailto:alexander.klimetschek@hpi.uni-potsdam.de Alexander Klimetschek], YouLi, fjruiz, [wiki:jun66j5], [wiki:rjollos]