Edgewall Software

Opened 9 years ago

Closed 7 years ago

Last modified 7 years ago

#10487 closed enhancement (fixed)

TicketQuery documentation improvement proposal

Reported by: AdrianFritz Owned by: AdrianFritz
Priority: low Milestone: 1.0.2
Component: query system Version: 0.13dev
Severity: trivial Keywords:
Cc: Branch:
Release Notes:

Documented col parameter in TicketQuery macro.

API Changes:
Internal Changes:


I believe this can improve a little bit TicketQuery documentation (rendered from source code found at http://trac.edgewall.org/browser/trunk/trac/ticket/query.py?rev=10750#L1178)


TicketQuery macro lets you display lists of tickets matching certain criteria anywhere you can use WikiFormatting.

This macro accepts a comma-separated list of keyed parameters, in the form "key=value", as follws:


If the key is the name of a ticket field, the value must use the syntax of a filter specifier as defined in TracQuery#QueryLanguage.

  • Note that this is not the same as the simplified URL syntax used for query: links starting with a ? character.
  • Commas (,) can be included in field values by escaping them with a backslash (\).

The date keys created and modified can also constrain the criteria. Again, see TracQuery#QueryLanguage.

In addition to filters, several other named parameters can be used to control how the results are presented. All of them are optional.

KeyDescription & DetailsDefault
col Pipe-separated list of columns and its order to show (requires format=table). col=id|summary
desc Reverse (true) the natural display order of the tickets. desc=false
format1 Sets how the list of tickets is displayed:
* list — ticket id next to the summary, each ticket on a separate line.
* compact — comma-separated list of ticket ids.
* count — the count of matching tickets
* table — similar to the custom query view (but without the controls)
* progress — a view similar to the milestone progress bars.
group Sets the ticket field for grouping tickets. None
groupdesc Reverse (true) the natural display order of the groups. groupdesc=false
max Sets the limit number of tickets to display (max=0 means no maximum). max=0
order Sets the ticket field for ordering tickets. order=id
rows Pipe-separated list of ticket fields to be viewed as a row, e.g. rows=description|summary (requires format=table) None
verbose Get the description for the listed tickets (true). Use with format=table only. Deprecated (< 0.12) in favor of the rows key. verbose=false
Note 1
For compatibility with Trac 0.10, if there's a last positional parameter given to the macro, it will be used to specify the format.
Also, for compatibility with Trac 0.10, using "&" as a field separator still works (except for order) but is deprecated.

Attachments (0)

Change History (16)

comment:1 by AdrianFritz, 9 years ago

Other improvements should be expected here, like:

  1. better identify since which Trac version every key is available or deprecated
  2. check if is it expected to be shown a non specified row (formatted as "Reported by nononon, x years ago.") when only used rows=description
    • I think this probably is a bug (maybe to be filed under a new ticket after confirmed)
  3. Help needed to understand this sentence: "Groups of field constraints to be OR-ed together can be separated by a litteral or argument."
  4. col key default settings might require some more adjusts for proper rendering

comment:2 by Remy Blank, 9 years ago

Feel free to edit the wiki here with your changes. The pages bundled with Trac are synchronized from this wiki. Just make sure you edit the right version for the features you document (i.e. if it's for 0.13, you should edit 0.13/TicketQuery (or create the page first, using a copy of the content of TicketQuery).

comment:3 by AdrianFritz, 9 years ago

Thanks for guidelines Remy. First round at wiki:0.13/TicketQuery@1. Probably you will have to perform manually synchronization because original wiki page (TicketQuery) has part of its contents rendered by [[MacroList(TicketQuery)]] macro.

comment:4 by Remy Blank, 9 years ago

I wasn't all too clear in comment:2, sorry about that. What I meant is that for pages belonging to TracGuide, we create the "versioned" page with the latest version from the "live" guide, and only then do we add modifications. This allows keeping track of the differences between versions and sometimes even to forward-merge changes.

I have done that now in 0.13/TicketQuery, by removing the page, re-creating it with a copy of TicketQuery and re-applying your changes.

comment:5 by AdrianFritz, 9 years ago

Nice, learnt one more procedure today :-).

comment:6 by Remy Blank, 8 years ago

Milestone: 1.01.0-triage

Preparing for 1.0.

comment:7 by Christian Boos, 8 years ago

Milestone: next-stable-1.0.x1.0
Resolution: fixed
Status: newclosed

Looks like this is "done", no?

comment:8 by Remy Blank, 8 years ago

Owner: set to AdrianFritz

in reply to:  8 comment:9 by AdrianFritz, 8 years ago

Yes, it´s done.

comment:10 by anonymous, 8 years ago

Were these improvements lost somehow?

comment:11 by Christian Boos, 8 years ago

Milestone: 1.0next-stable-1.0.x
Resolution: fixed
Status: closedreopened

Looks like that 0.13 page hasn't yet been moved to the default TicketQuery page, as it's not part of the set of default wiki pages.

I reopen so that we can take the time to review the changes again.

comment:12 by Peter Suter, 7 years ago

#9549 was closed as a duplicate.

I moved some of the examples from 0.13/TicketQuery to TicketQuery.

comment:2:ticket:9549 hinted that the docstring is also missing the col parameter, and I think the other changes of 0.13/TicketQuery that replace [[MacroList(TicketQuery)]] should also go there instead.

Last edited 7 years ago by Peter Suter (previous) (diff)

comment:13 by Peter Suter, 7 years ago

Actually the only part I really miss is the added col parameter. (Using a complex table doesn't work so well in the docstring.)

I therefore propose:

  • trac/ticket/query.py

    diff -r 57b0256a39d3 trac/ticket/query.py
    a b  
    12611261    The `rows` parameter can be used to specify which field(s) should
    12621262    be viewed as a row, e.g. `rows=description|summary`
     1264    The `col` parameter can be used to specify which fields should
     1265    be viewed as columns. For '''table''' format only.
    12641267    For compatibility with Trac 0.10, if there's a last positional parameter
    12651268    given to the macro, it will be used to specify the `format`.
    12661269    Also, using "&" as a field separator still works (except for `order`)

(The default seems too complex to describe here.)

comment:14 by Peter Suter, 7 years ago

Milestone: next-stable-1.0.x1.0.2

comment:15 by Peter Suter, 7 years ago

Release Notes: modified (diff)
Resolution: fixed
Status: reopenedclosed

Committed in [12613] and merged in [12614].

comment:16 by Ryan J Ollos, 7 years ago

Release Notes: modified (diff)

Modify Ticket

Change Properties
Set your email in Preferences
as closed The owner will remain AdrianFritz.
The resolution will be deleted. Next status will be 'reopened'.
to The owner will be changed from AdrianFritz to the specified user.

Add Comment

E-mail address and name can be saved in the Preferences .
Note: See TracTickets for help on using tickets.