#format wiki
#language en
#pragma section-numbers off
#acl IanRiley:read,write,delete,revert,admin All:read
#pragma supplementation-page on

<<ContentsAndAppendices>>
= schedule =

== Background and rationale ==

Some pages are prepared in advance of the need to release to read-only users, and currently can only be released by editing access control lists on the day of release. However, this locks the content creator into this at a specific time. A better solution would be a parser that checks release and withdrawal dates to determine if the content should be provided to read-only users.

== Description ==

A simple parser that only displays its contents if the current datetime is between two datetimes (`after` and `before`) provided as options in the form YYYY-MM-DD or YYYY-MM-DD@HH:MM (where HH is 00 to 23, i.e. for 24-hour clock).

If only one datetime is provided, it is considered to be the `after` datetime, and `before` is considered to be an unspecified time in the future.

There are no default values for the `after` and `before` datetimes. If neither are specified, the content is displayed.

If the datetimes are not valid or redundant arguments are provided, then a warning is displayed but not the contents.

Rather than have the dates spread across individual pages, it is possible to specify aggregate these in a Schedule page in the form `SomethingSchedule`, in similar way to Group pages. This page must contain a unnumbered first-order list giving the name of the page to be scheduled followed by one or two dates, and any keywords needed for that page. All other content of this page is ignored, just as in Group pages. To avoid recursion, a Schedule page cannot schedule itself. Likewise, the schedules in the list cannot call another Schedule page.

Keywords

silent : suppress message indicating content is outside the scheduled range. This could be useful for scheduled parser sections.

== Usage ==

As a processing instruction (four options)

#format schedule [YYYY-DD-MM[@HH:MM][ YYYY-MM-DD[@HH:MM]]][ silent]

#format schedule `SomethingSchedule`

#schedule [YYYY-DD-MM[@HH:MM][ YYYY-MM-DD[@HH:MM]]][ silent]

#schedule `SomethingSchedule`

where, `SomethingSchedule` is the name of an existing Schedule page.

As parser section

{{{{
{{{#!schedule [YYYY-DD-MM[@HH:MM][ YYYY-MM-DD[@HH:MM]]][ silent]
...
}}}
}}}}

== Prerequisites ==

A new plugin formatter `schedules.py` is needed. This is based on the 'groups.py', which cannot be used because it does not return the schedule put after page links. This is need to use the processing instructions forms #format schedule `SomethingSchedule`  and #schedule `SomethingSchedule`.

== Download & Release Notes ==
|| Download || Release Version || Moin Version || Release Notes ||
|| [[attachment:schedule-1.0.py]] || 1.0 || 1.9.8 ||  ||
|| [[attachment:schedule-1.1.py]] || 1.1 || 1.9.8 || uses send_special ||
|| [[attachment:schedules-1.0.py]] || 1.0 || 1.9.8 || required plugin formatter ||

== Examples ==

See [[schedule.py/Example|Example]]

== Related code ==

The macro [[ScheduledPages.py|ScheduledPages]] produces a list of pages that have scheduled for release by invoking this parser via processing instructions. This is provided to help simplify the maintenance scheduled pages.  

== History ==

Version 1.0 - 12.02.2019: initial version

== Copyright ==

 . @copyright: 2019 Ian Riley <ian@riley.asia>

== License ==

GNU GPL, see COPYING for details.

== Known issues and limitations ==

 * --(The `SomethingSchedule` page must also be readable by the user accessing the scheduled page, otherwise the error message received is not overly helpful. The message should be improved, or the code modified to read the schedule even it not directly accessible to the user.)--
  * Fixed in version 1.1 by sending send_special when retrieving the schedule from a `SomethingSchedule` page.

 * None identified

== Possible improvements ==

 * Allow a Schedule page, `SomethingSchedule` to apply only to particular group, if the the name is given as `SomeGroupSchedule`, i.e. applying the schedule to members of `SomeGroup` with read-only access to the page. Members of other groups with read-only access, would not be affected.

-----

 Hits:: <<Hits>>