[Bps-public-commit] rtx-calendar branch multiple-days-events-pod-update updated. 1.05-29-g56025f0
BPS Git Server
git at git.bestpractical.com
Mon Nov 27 19:40:10 UTC 2023
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "rtx-calendar".
The branch, multiple-days-events-pod-update has been updated
via 56025f0787059539981847e4c89ea9dcc08cdeee (commit)
from f2ad7f45ad5e7f34fddfb9a5e5d63e8925754e16 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 56025f0787059539981847e4c89ea9dcc08cdeee
Author: Jim Brandt <jbrandt at bestpractical.com>
Date: Mon Nov 27 14:39:19 2023 -0500
Additional POD updates
diff --git a/META.yml b/META.yml
index fe5224e..06c8e4e 100644
--- a/META.yml
+++ b/META.yml
@@ -1,5 +1,5 @@
---
-abstract: 'Calendar for RT due dates'
+abstract: 'Calendar view for RT ticket dates and custom fields'
author:
- 'Best Practical Solutions, LLC <modules at bestpractical.com>'
build_requires:
diff --git a/README b/README
index 3e23eb1..323206c 100644
--- a/README
+++ b/README
@@ -1,25 +1,19 @@
NAME
- RTx::Calendar - Calendar for RT due dates
+ RTx::Calendar - Calendar view for RT ticket dates and custom fields
DESCRIPTION
- This RT extension provides a calendar view for your tickets and your
- reminders so you see when is your next due ticket. You can find it in
- ticket search sub navigation menu.
-
- Date fields in the search results are displayed/used in the calendar,
- for example if you have a ticket with a due date, it won't be displayed
- on that date unless the Due field is included in the search result
- format.
-
- There's a portlet to put on your home page (see Prefs/MyRT.html), see
- the CONFIGURATION section below for details on adding it.
+ RTx::Calendar provides a calendar view to display tickets and reminders
+ based on selected dates. Once the extension is installed, if you perform
+ a ticket search using the Query Builder, you will see a new Calendar
+ entry in the page menu. You can click that menu to see the calendar view
+ of your search. A portlet is also available to add to any dashboard,
+ including on the RT home page.
RT VERSION
Works with RT 5.
- If you need to install this for RT 4.4.x, install version 1.05:
-
- cpanm RTx::Calendar at 1.05
+ For older versions of RT, see the CHANGES file for compatible earlier
+ versions.
INSTALLATION
perl Makefile.PL
@@ -37,32 +31,89 @@ INSTALLATION
Restart your webserver
+USAGE
+ To view a Calendar, first perform a ticket search in the ticket Query
+ Builder and load the search results. Then click the Calendar item in the
+ page menu to see the calendar view based on the results from that
+ search.
+
+ By default, RTx::Calendar will display the Starts and Due date fields of
+ each ticket from your search results as events on the Calendar.
+
+ Other date fields are added to the Format of a ticket search are
+ displayed on the Calendar as events. You can also display events based
+ on Date or DateTime custom fields by adding them to the Format of a
+ ticket search as well.
+
+ Hover over events in the calendar to see additional details for that
+ event. You can click on entries to go to the ticket.
+
+ Displaying Other Date Fields
+ You can show other date fields as events on the Calendar by adding them
+ to the Format section at the Advanced tab of your query. You can add and
+ remove dates from search results using the Display Columns section at
+ the bottom of the Query Builder.
+
+ Changes made using the Display Columns settings automatically update the
+ search Format. You can also edit the Format directly on the Advanced
+ page.
+
+ Calendar Portlet Saved Searches
+ As described above, you can see a calendar for any ticket search using
+ the calendar link in the search results.
+
+ You can also create a saved search for the calendar to be used in
+ calendar portlets on dashboards. See "CONFIGURATION" for details on
+ adding the calendar portlets.
+
+ By default, the calendar looks for a saved search with the name
+ "calendar" and will use that search for calendar portlets. Saved
+ searches can be saved with different privacy settings, so your system
+ can have multiple saved "calendar" searches. For a given user, the
+ calendar first checks for a user-level saved search (personal to that
+ user), then for a group-level saved search for groups the user is in,
+ and finally, for a system-level saved search.
+
+ Displaying Reminders
+ Reminders are displayed on the Calendar only if you explicitly add the
+ following clause to your query:
+
+ AND ( Type = 'ticket' OR Type = 'reminder' )
+
CONFIGURATION
- Use the calendar on Dashboard
- The calendar comes with 3 different portlets that can be added to your
+ Use the Calendar on Dashboard
+ The Calendar comes with 3 different portlets that can be added to your
RT dashboards:
- MyCalendar, a summary of the events for the current week.
- Calendar, a full month of the calendar view, without sidebar.
- CalendarWithSidebar, a full month of the calendar view, with sidebar
- which includes an extra status filter and legends of the calendars.
+ MyCalendar
+ A summary of the events for the current week.
- $HomepageComponents in etc/RT_SiteConfig.pm:
+ Calendar
+ A full-month view of the Calendar.
- Set($HomepageComponents, [qw(QuickCreate Quicksearch
- MyCalendar Calendar CalendarWithSidebar
- MyAdminQueues MySupportQueues MyReminders RefreshHomepage)]);
+ CalendarWithSidebar
+ A full-month view of the Calendar, with a sidebar that includes an
+ extra status filter and legends of the Calendar events.
- Display configuration
- Displaying the owner
- You can show the owner in each day box by adding this line to your
- etc/RT_SiteConfig.pm:
+ To make these portlets available in RT, add them to the
+ $HomepageComponents configuration in your etc/RT_SiteConfig.pm:
+
+ Set($HomepageComponents, [qw(QuickCreate Quicksearch
+ MyAdminQueues MySupportQueues MyReminders RefreshHomepage
+ MyCalendar Calendar CalendarWithSidebar)]);
+
+ Users can then select them when building dashboards.
+
+ Display Configuration
+ Display Owner
+ You can show the owner of the ticket in each event box by adding this
+ line to your etc/RT_SiteConfig.pm:
Set($CalendarDisplayOwner, 1);
- Choosing the fields to be displayed in the popup
- You can change which fields show up in the popup display when you mouse
- over a date in etc/RT_SiteConfig.pm:
+ Event Popup Fields
+ You can change which fields appear in the popup display when you mouse
+ over an event in etc/RT_SiteConfig.pm:
Set(@CalendarPopupFields,
('Status',
@@ -70,61 +121,109 @@ CONFIGURATION
'DueObj->ISO',
'CustomField.{Maintenance Estimated Start Date/Time - ET}'));
- Event colors
- It's also possible to change the color of the events in the calendar by
- adding the $CalendarStatusColorMap setting to your etc/RT_SiteConfig.pm:
+ Event Colors
+ The Calendar shows events in different colors based on the ticket
+ status. Use $CalendarStatusColorMap to set alternate colors or add
+ custom statuses. The following is the default configuration:
Set(%CalendarStatusColorMap, (
- 'new' => 'blue',
- 'open' => 'blue',
- 'approved' => 'green',
- 'rejected' => 'red',
- 'resolved' => '#aaa',
+ '_default_' => '#5555f8',
+ 'new' => '#87873c',
+ 'open' => '#5555f8',
+ 'rejected' => '#FF0000',
+ 'resolved' => '#72b872',
+ 'stalled' => '#FF0000',
));
You can use any color declaration that CSS supports, including hex
codes, color names, and RGB values.
- Event filtering by status
- You can change the statuses available for filtering on the calendar by
- adding the @CalendarFilterStatuses setting to your etc/RT_SiteConfig.pm:
+ The _default_ key is used for events that don't have a status in the
+ $CalendarStatusColorMap hash. The default color is a dark tone of blue.
+
+ Filter on Status
+ The Calendar has a Filter on Status section that allows you to filter
+ events by status without having to change the original query. The
+ @CalendarFilterStatuses setting controls which statuses are available
+ for filtering. The following is the default:
Set(@CalendarFilterStatuses, qw(new open stalled rejected resolved));
- Default selected status on Filtering on Status field
- You can change the default selected statuses by adding them to the
- @CalendarFilterDefaultStatuses setting to your etc/RT_SiteConfig.pm:
+ You can change the default selected statuses of the Filter On Status
+ section by defining @CalendarFilterDefaultStatuses. The following is the
+ default:
Set(@CalendarFilterDefaultStatuses, qw(new open));
- Custom icons
- Custom Icons can be defined for the events in the calendar by adding the
- $CalendarIcons setting to your etc/RT_SiteConfig.pm:
+ Custom Icons
+ The calendar shows different icons for events based on the date fields
+ used to display the event on that day. The %CalendarIcons setting
+ controls which icons are used for each date field. The following is the
+ default using provided icons:
Set(%CalendarIcons, (
- 'CF.{Maintenance Estimated Start Date/Time - ET}'
- => 'maint.png',
+ 'Reminder' => 'reminder.png',
+ 'Resolved' => 'resolved.png',
+ 'Starts, Due' => 'starts_due.png',
+ 'Created, Due' => 'created_due.png',
+ 'Created' => 'created.png',
+ 'Due' => 'due.png',
+ 'Starts' => 'starts.png',
+ 'Started' => 'started.png',
+ 'LastUpdated' => 'updated.png',
));
- The images should be placed on local/static/images.
+ You can also define icons for custom fields by using the following
+ format:
+
+ 'CF.{Maintenance Start}' => 'maintstart.png',
+ 'CF.{Maintenance Stop}' => 'maintstop.png',
- Multiple days events
- You can define multiple days events by adding the
- %CalendarMultipleDaysEvents setting to your etc/RT_SiteConfig.pm:
+ To add custom images, create a directory local/static/images in your
+ installed RT directory (usually /opt/rt5) and copy images files there.
+
+ You can use any image format that your browser supports, but PNGs and
+ GIFs with transparent backgrounds are recommended because they will
+ display better to the background color of the events. The recommended
+ size is 10 pixels wide and 7 pixels in high.
+
+ Multiple Days Events
+ By default, calendars display individual events on each day based on the
+ dates in the query.
+
+ To display events that span multiple days, such as the full expected
+ duration of a change blackout period, define the fields using the
+ %CalendarMultipleDaysEvents configuration. This option accepts named
+ keys that each define the field to reference for the start (Starts) and
+ end (Ends) of multi-day events. For example:
Set( %CalendarMultipleDaysEvents, (
- 'Maintenance' => {
- 'Starts' => 'Starts',
- 'Ends' => 'Due',
- },
- )
- );
+ 'Project Task' => {
+ 'Starts' => 'Starts',
+ 'Ends' => 'Due',
+ },
+ ));
- Note that the Starts and Ends fields must be included in the search
- result Format in order the event to be displayed on the calendar.
+ The keys, like Project Task, are arbitrary labels to group each set, so
+ you can use a name that helps you identify the entry.
-USAGE
- A small help section is available in /Search/Calendar.html
+ You can also define multiple day events for custom fields by using the
+ following format:
+
+ Set( %CalendarMultipleDaysEvents, (
+ 'Maintenance' => {
+ "Starts" => "CF.{Maintenance Start}",
+ "Ends" => "CF.{Maintenance Stop}",
+ },
+ 'Project Task' => {
+ 'Starts' => 'Starts',
+ 'Ends' => 'Due',
+ },
+ ));
+
+ As with all calendar entries, the date fields referenced in the
+ configuration must be included in the search result Format to display
+ the event on the Calendar.
AUTHOR
Best Practical Solutions, LLC <modules at bestpractical.com>
diff --git a/lib/RTx/Calendar.pm b/lib/RTx/Calendar.pm
index 5b28717..0889798 100644
--- a/lib/RTx/Calendar.pm
+++ b/lib/RTx/Calendar.pm
@@ -317,25 +317,16 @@ __END__
=head1 NAME
-RTx::Calendar - Calendar for RT Ticket Dates and Custom Fields
+RTx::Calendar - Calendar view for RT ticket dates and custom fields
=head1 DESCRIPTION
-This RT extension provides a calendar view that allows you to see important
-events of your tickets and reminders. You can find it in the ticket search
-actions menu or in one of the available Calendar portlets.
-
-Date fields that are added to the Format of a ticket search are displayed
-on the Calendar as events.
-
-You can also display events based on Date or DateTime custom fields on the
-Calendar by adding them to the Format of a ticket search as well.
-
-It can also show multiple-day events, such as a maintenance window that
-starts on one day and ends on another.
-
-Finally, you can see event details by hovering over the event in the
-Calendar.
+C<RTx::Calendar> provides a calendar view to display tickets and
+reminders based on selected dates. Once the extension is installed,
+if you perform a ticket search using the Query Builder, you will see
+a new Calendar entry in the page menu. You can click that menu to see
+the calendar view of your search. A portlet is also available to add
+to any dashboard, including on the RT home page.
=begin HTML
@@ -343,75 +334,11 @@ Calendar.
=end HTML
-
-=head1 USAGE
-
-In order to use the Calendar, you need to create a search in the Query
-Builder and click on the Calendar link in the actions menu of the search.
-
-By default, RTx::Calendar will display the Starts and Due date fields of
-each ticket from your search results as events on the Calendar.
-
-
-=head2 Displaying other date fields
-
-You can show other date fields as events on the Calendar by adding them
-to the Format section at the Advanced tab of your query.
-
-The following format will display the two default date fields (Starts and Due)
-and, additionally, the field LastUpdated and a custom field called
-Maintenance Date:
-
- '__Due__',
- '__Starts__',
- '__LastUpdated__',
- '__CustomField.{Maintenance Date}__'
-
-If you want to display only one custom field, you can use the following
-format:
-
- '__CustomField.{Maintenance Date}__'
-
-
-=head2 Creating a default query for the Calendar
-
-As described above, you can see the Calendar by creating a search in the
-Query Builder and clicking on the Calendar link.
-
-However, it is also possible to create a default query for the Calendar that
-will be used to display events if no search is selected, as well as on the
-Calendar portlets (see the CONFIGURATION section below for details on adding
-the Calendar portlets to your RT).
-
-You can change the default query used by Calendar.html and Calendar portlets
-by saving a query with the name C<calendar> in the Query Builder.
-
-Note that first, the calendar will check for a user-level saved search, then
-for a group-level saved search, and finally, for a system-level saved search.
-
-In other words, if your RT has a system-level saved search called C<calendar>,
-the Calendar will use it to display events on the Calendar portlets. Still, if
-the user belongs to a group and this group has a group-level saved search
-called C<calendar>, the Calendar will use it instead of the system-level
-one. Finally, if the user has a user-level saved search called C<calendar>,
-the Calendar will use it instead of the group-level or system-level saved
-search to display events on the Calendar portlets.
-
-
-=head2 Displaying reminders
-
-Reminders are displayed on the Calendar only if you explicitly add the
-following clause to your query:
-
- AND ( Type = 'ticket' OR Type = 'reminder' )
-
=head1 RT VERSION
Works with RT 5.
-If you need to install this for RT 4.4.x, install version 1.05:
-
- cpanm RTx::Calendar at 1.05
+For older versions of RT, see the CHANGES file for compatible earlier versions.
=head1 INSTALLATION
@@ -439,6 +366,56 @@ Add this line:
=back
+=head1 USAGE
+
+To view a Calendar, first perform a ticket search in the ticket Query
+Builder and load the search results. Then click the Calendar item in the
+page menu to see the calendar view based on the results from that search.
+
+By default, RTx::Calendar will display the Starts and Due date fields of
+each ticket from your search results as events on the Calendar.
+
+Other date fields are added to the Format of a ticket search are displayed
+on the Calendar as events. You can also display events based on Date or
+DateTime custom fields by adding them to the Format of a ticket search as well.
+
+Hover over events in the calendar to see additional details for that event.
+You can click on entries to go to the ticket.
+
+=head2 Displaying Other Date Fields
+
+You can show other date fields as events on the Calendar by adding them
+to the Format section at the Advanced tab of your query. You can add and
+remove dates from search results using the Display Columns section at
+the bottom of the Query Builder.
+
+Changes made using the Display Columns settings automatically update the
+search Format. You can also edit the Format directly on the Advanced page.
+
+=head2 Calendar Portlet Saved Searches
+
+As described above, you can see a calendar for any ticket search using
+the calendar link in the search results.
+
+You can also create a saved search for the calendar to be used in
+calendar portlets on dashboards. See L</"CONFIGURATION"> for details on
+adding the calendar portlets.
+
+By default, the calendar looks for a saved search with the name "calendar"
+and will use that search for calendar portlets. Saved searches can be
+saved with different privacy settings, so your system can have multiple
+saved "calendar" searches. For a given user, the calendar first checks
+for a user-level saved search (personal to that user), then for a group-level
+saved search for groups the user is in, and finally, for a system-level saved
+search.
+
+=head2 Displaying Reminders
+
+Reminders are displayed on the Calendar only if you explicitly add the
+following clause to your query:
+
+ AND ( Type = 'ticket' OR Type = 'reminder' )
+
=head1 CONFIGURATION
=head2 Use the Calendar on Dashboard
@@ -463,23 +440,25 @@ status filter and legends of the Calendar events.
=back
-In order to use those portlets, you need to add them to the
-C<$HomepageComponents> config in your F<etc/RT_SiteConfig.pm>:
+To make these portlets available in RT, add them to the
+C<$HomepageComponents> configuration in your F<etc/RT_SiteConfig.pm>:
+
+ Set($HomepageComponents, [qw(QuickCreate Quicksearch
+ MyAdminQueues MySupportQueues MyReminders RefreshHomepage
+ MyCalendar Calendar CalendarWithSidebar)]);
- Set($HomepageComponents, [qw(QuickCreate Quicksearch
- MyCalendar Calendar CalendarWithSidebar
- MyAdminQueues MySupportQueues MyReminders RefreshHomepage)]);
+Users can then select them when building dashboards.
-=head2 Display configuration
+=head2 Display Configuration
-=head3 Displaying the owner
+=head3 Display Owner
You can show the owner of the ticket in each event box by adding this line
to your F<etc/RT_SiteConfig.pm>:
Set($CalendarDisplayOwner, 1);
-=head3 Choosing the fields to be displayed in the popup
+=head3 Event Popup Fields
You can change which fields appear in the popup display when you
mouse over an event in F<etc/RT_SiteConfig.pm>:
@@ -490,13 +469,11 @@ mouse over an event in F<etc/RT_SiteConfig.pm>:
'DueObj->ISO',
'CustomField.{Maintenance Estimated Start Date/Time - ET}'));
-=head3 Event colors
-
-The Calendar shows events in different colors based on the status of their
-tickets.
+=head3 Event Colors
-The C<$CalendarStatusColorMap> setting allows you to change the colors of
-the events in the Calendar. The following is the default:
+The Calendar shows events in different colors based on the ticket status.
+Use C<$CalendarStatusColorMap> to set alternate colors or add custom statuses.
+The following is the default configuration:
Set(%CalendarStatusColorMap, (
'_default_' => '#5555f8',
@@ -507,47 +484,33 @@ the events in the Calendar. The following is the default:
'stalled' => '#FF0000',
));
-You can change the colors by copying the above configuration to your
-F<etc/RT_SiteConfig.pm> and adding or changing new statuses or color values.
-
You can use any color declaration that CSS supports, including hex codes,
color names, and RGB values.
-Note that the C<_default_> key is used for events that don't have a status
+The C<_default_> key is used for events that don't have a status
in the C<$CalendarStatusColorMap> hash. The default color is a dark tone of
blue.
=head3 Filter on Status
-The Sidebar of the Calendar has a Filter on Status section that allows
-you to filter the events by status without having to change the original
-query.
-
+The Calendar has a Filter on Status section that allows you to filter
+events by status without having to change the original query.
The C<@CalendarFilterStatuses> setting controls which statuses are available
for filtering. The following is the default:
Set(@CalendarFilterStatuses, qw(new open stalled rejected resolved));
-If you want to change the available statuses, you can copy the above
-configuration to your F<etc/RT_SiteConfig.pm> and add or remove statuses.
-
-
-=head3 Default selected statuses on Filter on Status section
-
You can change the default selected statuses of the Filter On Status section
-by adding the C<@CalendarFilterDefaultStatuses> setting to your
-F<etc/RT_SiteConfig.pm>. The following is the default:
+by defining C<@CalendarFilterDefaultStatuses>. The following is the default:
Set(@CalendarFilterDefaultStatuses, qw(new open));
-=head3 Custom icons
-
-The Calendar shows different icons for events based on the date fields
-that originated them.
-
+=head3 Custom Icons
-The C<%CalendarIcons> setting controls which icons are used for each date
-field. The following is the default:
+The calendar shows different icons for events based on the date fields
+used to display the event on that day. The C<%CalendarIcons> setting
+controls which icons are used for each date field. The following is the
+default using provided icons:
Set(%CalendarIcons, (
'Reminder' => 'reminder.png',
@@ -561,37 +524,23 @@ field. The following is the default:
'LastUpdated' => 'updated.png',
));
-You can customize the icons by copying the above configuration to your
-F<etc/RT_SiteConfig.pm> and adding or changing new date fields or icons.
-
You can also define icons for custom fields by using the following format:
- Set(%CalendarIcons, (
- 'Reminder' => 'reminder.png',
- 'Resolved' => 'resolved.png',
- 'Starts, Due' => 'starts_due.png',
- 'Created, Due' => 'created_due.png',
- 'Created' => 'created.png',
- 'Due' => 'due.png',
- 'Starts' => 'starts.png',
- 'Started' => 'started.png',
- 'LastUpdated' => 'updated.png',
'CF.{Maintenance Start}' => 'maintstart.png',
'CF.{Maintenance Stop}' => 'maintstop.png',
- ));
-The images should be placed in the F<local/static/images> folder of your RT.
+To add custom images, create a directory F<local/static/images> in your installed
+RT directory (usually F</opt/rt5>) and copy images files there.
You can use any image format that your browser supports, but PNGs and GIFs
-with transparent backgrounds are recommended because they will adapt better
-to the background color of the events.
-
-The recommended size is 10 pixels in width and 7 pixels in height.
+with transparent backgrounds are recommended because they will display better
+to the background color of the events. The recommended size is 10 pixels wide
+and 7 pixels in high.
-=head3 Multiple days events
+=head3 Multiple Days Events
-By default, the Calendar will only display individual day events without
-any connection between them.
+By default, calendars display individual events on each day based on
+the dates in the query.
=begin HTML
@@ -599,16 +548,11 @@ any connection between them.
=end HTML
-This can be useful if you want only to display the Due date of a ticket
-or only a single-day information of the ticket.
-
-However, if you want to display multiple-day events, such as the full expected
-duration of a ticket or a maintenance window, you can do so by connecting
-the Starts and Ends fields of the event.
-
-In order to achieve that, you need to add the C<%CalendarMultipleDaysEvents>
-setting to your F<etc/RT_SiteConfig.pm>, and the Calendar will automatically
-show the full duration of the event.
+To display events that span multiple days, such as the full expected
+duration of a change blackout period, define the fields using the
+C<%CalendarMultipleDaysEvents> configuration. This option accepts
+named keys that each define the field to reference for the start (Starts)
+and end (Ends) of multi-day events. For example:
Set( %CalendarMultipleDaysEvents, (
'Project Task' => {
@@ -623,10 +567,10 @@ show the full duration of the event.
=end HTML
-Note that C<Project Task> is the name of the multiday event, and for now,
-it is only used to connect the Starts and Ends fields.
+The keys, like C<Project Task>, are arbitrary labels to group each
+set, so you can use a name that helps you identify the entry.
-You can also define multiple days events for custom fields by using the
+You can also define multiple day events for custom fields by using the
following format:
Set( %CalendarMultipleDaysEvents, (
@@ -640,8 +584,9 @@ following format:
},
));
-Note that the Starts and Ends fields must be included in the search result
-Format in order to display the event on the Calendar.
+As with all calendar entries, the date fields referenced in the
+configuration must be included in the search result Format to
+display the event on the Calendar.
=head1 AUTHOR
-----------------------------------------------------------------------
Summary of changes:
META.yml | 2 +-
README | 229 ++++++++++++++++++++++++++++++++--------------
lib/RTx/Calendar.pm | 255 +++++++++++++++++++++-------------------------------
3 files changed, 265 insertions(+), 221 deletions(-)
hooks/post-receive
--
rtx-calendar
More information about the Bps-public-commit
mailing list