- one macro to create issue lists
- with existing issue queries
- with parameters (without issue queries)
This is a fork of redmine_wiki_lists, which reduce functionality to just one macro - ref_issues
- Redmine
>= 6.1.0 - Ruby
>= 3.2
-
Clone this repository into
redmine/plugins/redmine_ref_issues.cd redmine git clone https://github.com/alphanodes/redmine_ref_issues.git plugins/redmine_ref_issues bundle config set --local without 'development test' bundle install
if you have older Redmine version (5.0 - 6.0), use:
cd redmine git clone -b stable https://github.com/alphanodes/redmine_ref_issues.git plugins/redmine_ref_issues bundle config set --local without 'development test' bundle install
-
Restart your Redmine application server.
Syntax
{{ref_issues([option].., [column]..)}}Options
-s[=WORD[｜WORD]..]
select issues that contain WORDs in subject.
-d[=WORD[｜WORD]..]
select issues that contain WORDs in description.
-w[=WORD[｜WORD]..]
select issues that contain WORDs in subject or description.
-p[=IDENTIFIRE]
Specify the project by identifire.
-i=CUSTOM_QUERY_ID
Use custom query by id.
-q=CUSTOM_QUERY_NAME
Use custom query by query name.
-0
Do not display the table If query result is 0.
f:<ATTRIBUTE>␣<OPERATOR>␣<[VALUE[|VALUE...]]>
filter. Attributes are shown below.
e.x. {{ref_issues(-f:tracker_id = 3)}}
[ATTRIBUTE]
issue_id,tracker_id,project_id,subject,description,
due_date,category_id,status_id,assigned_to_id,priority_id,
fixed_version_id,author_id,lock_version,created_on,updated_on,
start_date,done_ratio,estimated_hours,parent_id,root_id,
lft,rgt,is_private,closed_on,
cf_*,
tracker,category,status,assigned_to,version,project,
treated, author
[OPERATOR]
=:is, !:is not, o:open, c:closed, !*:none,
*:any, >=:>=, <=:<=, ><:between, >t+:in more than,
>w:this week, lw:last week, l2w:last 2 weeks, m:this month, lm:last month,
y:this year, >t-:less than days ago, ~:contains, !~:doesn't contain,
=p:any issues in project, =!p:any issues not in project, !p:no issues in project,
**Note:** Multiple filter options for different fields create AND conditions. See the "AND/OR Logic" section below for detailed examples.
If you use this macro in a Issue, you can use the field value of the issue as VALUE by writing to the following field(column) name in the [] (brackets).
> Besides [<column>], You can use [id], [current_project_id], [current_user], [current_user_id], [<number> days_ago] .
-l[=column]
Put linked text.
-t[=column]
Put markup text.
-sum[=column]
Sum of specified column for issues.
-c
number of issues.
Understanding how filters combine is important for creating the right queries:
AND logic (multiple filter fields):
When you specify multiple -f: options with different fields, they are combined with AND logic:
{{ref_issues(-f:tracker = Bug, -f:status = New)}}This finds issues where tracker is "Bug" AND status is "New".
OR logic (pipe separator within one filter):
Use the pipe | separator to create OR conditions within a single field:
{{ref_issues(-f:tracker = Bug|Feature)}}This finds issues where tracker is "Bug" OR "Feature".
Limitation with contains operator (~):
When using the contains operator ~ on the same field multiple times, you cannot achieve AND logic:
# This does NOT work as expected (will not find issues containing BOTH words):
{{ref_issues(-f:cf_51 ~ oracle, -f:cf_51 ~ linux)}}
# Use pipe for OR instead:
{{ref_issues(-f:cf_51 ~ oracle|linux)}}This is a limitation of Redmine's Query system. To search for multiple words in a custom field where ALL words must be present, consider using Redmine's built-in search or a custom query instead.
OR logic between different fields (Workaround):
Currently, OR logic between different fields is not supported directly in the macro syntax:
# This does NOT work (will use AND logic, not OR):
{{ref_issues(-f:author = [current_user], -f:assigned_to = [current_user])}}Workaround using Custom Queries:
To achieve OR logic between different fields (e.g., "author OR assigned_to"), create a custom query in Redmine's web interface with the desired OR filters, then reference it by name or ID:
# Create a custom query in Redmine UI with OR filters, then:
{{ref_issues(-q=MyOrQuery)}}
# or
{{ref_issues(-i=42)}}This is a limitation of Redmine's Query API which does not support OR conjunctions between different filter fields programmatically.
You can choose columns that you want to display. If you do not specify the columns, same columns with customquery are displayed.
- project
- tracker
- parent
- status
- priority
- subject
- author
- assigned_to
- updated_on
- category
- fixed_version
- start_date
- due_date
- estimated_hours
- done_ratio
- created_on
- closed_on
- relations
-
Use custom query by ID
{{ref_issues(-i=9)}} -
Use custom query by name
{{ref_issues(-q=MyCustomQuery1)}} -
List up issues that contain 'sorting' in subject
{{ref_issues(-f:subject ~ sorting)}} -
List up issues that author_id is 1 and status is not 'To Do'. specify display column(project,subject,author,assigned_to,status)
{{ref_issues(-f:author_id = 1, -f:status ! To Do, project, subject, author, assigned_to, status)}} -
List up tickets that tracker is Support(3) or Question(6), and restrict by project=Wiki Lists
{{ref_issues(-f:tracker == Question | Support, -f:project = Wiki Lists)}} -
Pickup issues that have subject=Sample, and put linked ID
{{ref_issues(-f:subject = Sample, -l=id)}} -
Pickup issues that have subject=Sample, and put markuped description
{{ref_issues(-f:subject = Sample, -t=description)}} -
Put number of issues that contain 'sorting' in subject
{{ref_issues(-f:subject ~ sorting, -c)}} -
Filter by issue_id (between)
{{ref_issues(-f:issue_id >< 1389|1391)}} -
Filter by issue_id (or)
{{ref_issues(-f:issue_id == 1389|1391)}} -
Do not display the table If query result is 0.
{{ref_issues(-0,-f:subject = Sample2)}} -
OR condition by name
{ref_issues(-f:category == sample|error, subject, category)}} -
Created or updated by user jsmith from 2017-05-01 to yesterday
{{ref_issues(-f:treated jsmith 2017-05-01|[1days_ago])}} -
Put sum of estimated_hours of issues that contain 'sorting' in subject
{{ref_issues(-f:subject ~ sorting, -sum:estimated_hours)}} -
List overdue issues (due date in the past)
{{ref_issues(-f:due_date <t- 0)}} -
List issues due in more than 5 days
{{ref_issues(-f:due_date >t+ 5)}} -
List issues due in less than 3 days
{{ref_issues(-f:due_date <t+ 3)}}
Make sure you have the latest database structure loaded to the test database:
bundle exec rake db:drop db:create db:migrate RAILS_ENV=testRun the following command to start tests:
bundle exec rake redmine:plugins:test NAME=redmine_ref_issues RAILS_ENV=testcd $REDMINE_ROOT
rm -rf plugins/redmine_ref_issuesIf you want to contribute to this plugin, please create a Pull Request.
This plugin is licensed under the terms of GNU/GPL v2. See LICENSE for details.
The redmine_ref_issues is a plugin extension for Redmine Project Management Software, whose Copyright follows. Copyright (C) 2006- Jean-Philippe Lang
Redmine is a flexible project management web application written using Ruby on Rails framework. More details can be found in the doc directory or on the official website http://www.redmine.org
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
The source code is a fork of redmine_wiki_lists
Special thanks to the original author and contributors for making this awesome hook for Redmine.