[Bps-public-commit] rtx-calendar branch multiple-days-events-pod-update created. 1.05-28-gf2ad7f4
BPS Git Server
git at git.bestpractical.com
Wed Nov 22 14:51:53 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 created
at f2ad7f45ad5e7f34fddfb9a5e5d63e8925754e16 (commit)
- Log -----------------------------------------------------------------
commit f2ad7f45ad5e7f34fddfb9a5e5d63e8925754e16
Author: Ronaldo Richieri <ronaldo at bestpractical.com>
Date: Wed Nov 22 11:50:16 2023 -0300
Update POD with new features
Add information about custom field based events, multiple days events
and new calendar portlets.
Also bring the help section information from the UI to the POD in the
usage section.
diff --git a/lib/RTx/Calendar.pm b/lib/RTx/Calendar.pm
index 4e00fb7..5b28717 100644
--- a/lib/RTx/Calendar.pm
+++ b/lib/RTx/Calendar.pm
@@ -317,20 +317,93 @@ __END__
=head1 NAME
-RTx::Calendar - Calendar for RT due dates
+RTx::Calendar - Calendar for RT Ticket Dates and Custom Fields
=head1 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.
+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 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.
+Date fields that are added to the Format of a ticket search are displayed
+on the Calendar as events.
-There's a portlet to put on your home page (see Prefs/MyRT.html), see the
-CONFIGURATION section below for details on adding it.
+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.
+
+=begin HTML
+
+<p><img src="https://static.bestpractical.com/images/calendar/calendar.png" alt="Calendar Overview" /></p>
+
+=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
@@ -368,23 +441,30 @@ Add this line:
=head1 CONFIGURATION
-=head2 Use the calendar on Dashboard
+=head2 Use the Calendar on Dashboard
-The calendar comes with 3 different portlets that can be added to your
+The Calendar comes with 3 different portlets that can be added to your
RT dashboards:
=over
-=item C<MyCalendar>, a summary of the events for the current week.
+=item C<MyCalendar>
+
+A summary of the events for the current week.
+
+=item C<Calendar>
+
+A full-month view of the Calendar.
-=item C<Calendar>, a full month of the calendar view, without sidebar.
+=item C<CalendarWithSidebar>
-=item C<CalendarWithSidebar>, a full month of the calendar view, with
-sidebar which includes an extra status filter and legends of the calendars.
+A full-month view of the Calendar, with a sidebar that includes an extra
+status filter and legends of the Calendar events.
=back
-C<$HomepageComponents> in F<etc/RT_SiteConfig.pm>:
+In order to use those portlets, you need to add them to the
+C<$HomepageComponents> config in your F<etc/RT_SiteConfig.pm>:
Set($HomepageComponents, [qw(QuickCreate Quicksearch
MyCalendar Calendar CalendarWithSidebar
@@ -394,15 +474,15 @@ C<$HomepageComponents> in F<etc/RT_SiteConfig.pm>:
=head3 Displaying the owner
-You can show the owner in each day box by adding this line to your
-F<etc/RT_SiteConfig.pm>:
+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
-You can change which fields show up in the popup display when you
-mouse over a date in F<etc/RT_SiteConfig.pm>:
+You can change which fields appear in the popup display when you
+mouse over an event in F<etc/RT_SiteConfig.pm>:
Set(@CalendarPopupFields,
('Status',
@@ -412,66 +492,156 @@ mouse over a date in F<etc/RT_SiteConfig.pm>:
=head3 Event colors
-It's also possible to change the color of the events in the calendar by
-adding the C<$CalendarStatusColorMap> setting to your F<etc/RT_SiteConfig.pm>:
+The Calendar shows events in different colors based on the status of their
+tickets.
+
+The C<$CalendarStatusColorMap> setting allows you to change the colors of
+the events in the Calendar. The following is the default:
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 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.
-=head3 Event filtering by status
+Note that 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.
-You can change the statuses available for filtering on the calendar by
-adding the C<@CalendarFilterStatuses> setting to your
-F<etc/RT_SiteConfig.pm>:
+The C<@CalendarFilterStatuses> setting controls which statuses are available
+for filtering. The following is the default:
Set(@CalendarFilterStatuses, qw(new open stalled rejected resolved));
-=head3 Default selected status on Filtering on Status field
+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.
-You can change the default selected statuses by adding them to the
-C<@CalendarFilterDefaultStatuses> setting to your F<etc/RT_SiteConfig.pm>:
+
+=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:
Set(@CalendarFilterDefaultStatuses, qw(new open));
=head3 Custom icons
-Custom Icons can be defined for the events in the calendar by adding the
-C<$CalendarIcons> setting to your F<etc/RT_SiteConfig.pm>:
+The Calendar shows different icons for events based on the date fields
+that originated them.
+
+
+The C<%CalendarIcons> setting controls which icons are used for each date
+field. The following is the default:
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 F<local/static/images>.
+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.
+
+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.
=head3 Multiple days events
-You can define multiple days events by adding the C<%CalendarMultipleDaysEvents>
-setting to your F<etc/RT_SiteConfig.pm>:
+By default, the Calendar will only display individual day events without
+any connection between them.
+
+=begin HTML
+
+<p><img src="https://static.bestpractical.com/images/calendar/calendar-disconnected-events.png" alt="Calendar Disconnected Events" /></p>
+
+=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.
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.
+=begin HTML
-=head1 USAGE
+<p><img src="https://static.bestpractical.com/images/calendar/calendar-multiple-days-events.png" alt="Calendar Multi-days Events" /></p>
-A small help section is available in /Search/Calendar.html
+=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.
+
+You can also define multiple days 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',
+ },
+ ));
+
+Note that the Starts and Ends fields must be included in the search result
+Format in order to display the event on the Calendar.
=head1 AUTHOR
-----------------------------------------------------------------------
hooks/post-receive
--
rtx-calendar
More information about the Bps-public-commit
mailing list