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

<<TableOfContents>>

= ScheduledPages =

== Background and rationale ==

The [[schedule.py|schedule]] parser provides a method to set release and withdrawal dates of pages for read-only users, however, maintaining a moderate number of scheduled pages could prove troublesome. For example, resource pages for a training course might need to have their schedules updated each time the course is run. So, a page listing macro would help in the maintenance of these schedules. This macro was based on the Wanted``Pages macro of Juergen Hermann, which has a similar intent.

== Description ==

This macro creates a list of pages that have been scheduled using processing instructions, either as '#format schedule' (see plugin parser [[schedule.py]]) or '#schedule' (also see [[PiSchedule]] and modified `page.py` with new the processing instruction, `#schedule`, and special page type `hidden`).

The numbered list includes a link to the scheduled page followed by scheduling arguments and status. If it is currently viewable by read-only users, then 'show = True'. If it is set to silent (i.e. users are not warned the page is not visible by of the scheduling, then 'silent = True'). If the scheduling arguments have a syntax error, then a warning is given. In such cases, the [[schedule.py|schedule]] parser makes the conservative decision to set 'show = False'. However, if not scheduling arguments were given the list says, 'schedule = none' and 'show = True'.

If the page has been indirectly scheduled by pointing to a Schedule page (e.g., #schedule `SomethingSchedule`), then the schedule is preceded by this information as 'source = !SomethingSchedule' with the Schedule page name as an active link to that page.

The list can be sorted either alphabetically by page name (default) or chronolocially by the schedule arguments, i.e. the release ('after') date.

== Usage ==

=== <<ScheduledPages>> ===

{{{

<ScheduledPages>> - produces a list of pages that have scheduled for release by invoking this parser via processing instructions.

}}}

== Example ==

Assume the date is after 3 Jan 2019 and before 1 Jan 2020, and the wiki has the pages as tabulated below.

||'''Page'''||'''Processing instructions'''||
||<style="color: blue;">Sand``Box/Schedule``Correct||#format schedule 2018-01-03 2020-01-01||
||<style="color: blue;">Sand``Box/Schedule``Error||#format schedule 2018-01-01 2020-01-01a||
||<style="color: blue;">Sand``Box/Schedule``PI||#format wiki<<BR>>#schedule 2019-01-01 2019-01-03||
||<style="color: blue;">Sand``Box/Schedule``Page||#format wiki<<BR>>#schedule Test``Schedule||
||<style="color: blue;">Sand``Box/Un``Schedule``Page||#format wiki<<BR>>#schedule Test``Schedule||

And, there is a Schedule page `TestSchedule` containing the following.

 * Sand``Box/Scheduled``Page 2018-01-03 2020-01-01

 * Sand``Box/Un``Scheduled``Page

Then, `<<ScheduledPages>>` would produce the following lists. The first is the default alphabetical listing, second is the chronological listing.

||{{attachment:ScheduledPagesListAlphabetical.png||height=240px}}||

||{{attachment:ScheduledPagesListChronological.png||height=240px}}||

== Download & Release Notes ==

|| Download || Release Version || Moin Version || Release Notes ||
|| [[attachment:ScheduledPages-1.0.py]] || 1.0 || 1.9.8  ||  ||

== Copyright ==

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

 . Based on:
  . Wanted``Pages macro 
  . @copyright: 2001 Juergen Hermann <jh@web.de>

== License ==

GNU GPL, see COPYING for details.

== Known issues and limitations ==

 * Currently scheduled sections are not listable, however these could be found but search for the text `{{{#!schedule`. Also, these provide a admonition message when not longer displayable, so the user is warned (unless the keyword `silent` as included).

-----

 Hits:: <<Hits>>