omz13 / kirby3-suncyclepages
kirby3 plugin to embargo pages until sunrise date and withdraw at sunset date
Installs: 122
Dependents: 0
Suggesters: 0
Security: 0
Stars: 19
Watchers: 4
Forks: 1
Open Issues: 2
Type:kirby-plugin
Requires
- php: >=7.1
- getkirby/composer-installer: ^1.1
Requires (Dev)
- getkirby/cms: ^3.0.1
- jakub-onderka/php-parallel-lint: ^1.0
- localheinz/composer-normalize: ^0.8.0
- omz13/omz13-coding-standard: ^0.2.0
- phpcompatibility/php-compatibility: ^8.2
- phpmd/phpmd: ^2.6
- phpstan/phpstan: ^0.10.3
- phpstan/phpstan-strict-rules: ^0.10.1
- roave/security-advisories: dev-master
This package is auto-updated.
Last update: 2022-12-19 01:00:21 UTC
README
Requirement: Kirby 3.0
Coffee, Beer, etc.
This plugin is free but if you use it in a commercial project to show your support you are welcome to:
Why call it suncycle?
There are perhaps, with the benefit of hindsight, better names such as 'embargo', 'autopublish', 'schedule', etc. However, when this plugin was developed the notion was to follow the lifecycle of a page: sunrise and sunset are well-known terms within SDLC or ILM (although very much less familiar outside this domain), and 'suncycle' was used. I had my head in software mode not publishing or journalism mode; it could also be argued that unless you are familiar with publishing and journalism, terms such as 'embargo' and 'schedule' are also unusual outside that domain.
Documentation
Purpose
For a kirby3 site, this plugin omz13/suncyclepages allows more granular control over the lifecycle of a page to be achieved vis-à-vis pages becoming generally available at a "sunrise date" and withdrawn at a "sunset date". This enhances the limited lifecycle options provided by kirby3's state
(unpublished, draft, and published) to better match that needed certain editorial or regulatory needs, viz., unpublished, draft, embargoed (waiting "sunrise"), published ("sunny"), and finally withdrawn ("sunset").
When would you use this plugin?
- The main use case is for writing blog posts that you want to publish in the future. Write them now, and schedule them to appear (sunrise) in the future. Ideal for those times when you are away but want to continue a publishing schedule.
- Another use case is for temporary offers or notices. You publish a page, but in the future you want it removed (sunset), or better yet, want it removed and replaced (redirected) to elsewhere that says "too late" (or whatever).
The functional specification:
- Only pages that have a status of "published" are affected, i.e. those with "draft" or "unpublished" behave as usual.
- Pages can be embargoed until being made generally available a specified date ("sunrise"). Any attempt to view the page before that date will yield the standard error page and a
404
[Not Found] code. - Pages can be withdrawn at a specific date ("sunset"). Any attempt to view the page after that date will yield a
410
[Gone] and the standard error page, or, a301
[Moved Permanently] to a specified location on a per-page basis. - A debug mode can be enabled to include a header in the response to indicate that a page was under embargo or has sunset, c.f.
X-SUNCYCLE
.
Roadmap
The non-binding list of planned features and implementation notes are:
- MVP
- Basic debugging
- If the time is not specified (just the date), default sensibly.
- Better debugging
- Blueprints
Installation
Pick one of the following per your epistemological model:
composer require omz13/kirby3-suncyclepages
; the plugin will automagically appear insite/plugins
.- Download a zip of the latest release - master.zip - and copy the contents to your
site/plugins/kirby3-suncyclepages
. git submodule add https://github.com/omz13/kirby3-suncyclepages.git site/plugins/kirby3-suncyclepages
.
Configuration
The following mechanisms can be used to modify the plugin's behavior.
via config.php
-
omz13.suncyclepages.disable
- optional - defaultfalse
- a boolean which, iftrue
, disables the plugin. -
omz13.suncyclepages.embargoCheckWhenTemplateIs
- optional - default[ 'article' ]
: if a page uses a template name that is specified in this option, the embargo check (sunrise) is explicitly performed. -
omz13.suncyclepages.embargoCheckWhenParentIs
- optional - default[ 'blog' ]
: if a page has a parent that is specified in this parameter, the embargo check (sunrise) is explicitly performed.
Use
Content fields
The plugin uses the following content fields. These are all optional; if missing or empty, they are assumed to be not applicable vis-à-via their indicated functionality.
-
date
- date - optional - the date when the page is to be published, i.e. embargo until this date. If the date field is missing or cannot be resolved, the embargo check will not embargo the page, i.e. failsafe is to not embargo but publish. -
skipembargo
- boolean - optional (defaultfalse
) - iftrue
, the embargo check (sunrise) is skipped (not performed) for this page. -
embargo
- boolean - optional (defaultfalse
) - gftrue
, the embargo check (sunrise) should be explicitly performed against this page. This is intended to be used on pages where such checking is not normally done, i.e. not explicitly done due to parent (c.f.omz13.suncyclepages.embargoCheckWhenParentIs
) or template (c.f.omz13.suncyclepages.embargoCheckWhenTemplateIs
). -
sunset
- date - optional - the (future) date after which the page is to be sunset (withdrawn). -
sunsetto
page - optional - the name of a page to be used for301
redirects when the page is sunset; if not specified a404
is given.
Blueprints
This plugin provides the following built-in blueprints (e.g. to make adding fields into the panel's blueprint blueprint/site.yml
easier):
omz13/suncycle
- a group of fields to be used as anextends
to make entering embrgo parameters easy. For example, it would be appened into starterkit'ssite/blueprints/pages/article.yml
so:
sidebar: meta: type: fields fields: date: type: date time: true default: now label: Publication Date author: type: users tags: type: tags options: query query: fetch: site.tags.toStructure.sortBy("name", "asc") text: "{{ structureItem.name }}" value: "{{ structureItem.value }}" extends: omz13/suncycle
This built-in blueprint is localized for en
and fr
; PRs for others are welcome!
Use
Debug mode
If the kirby site is in debug mode:
-
If a page is embargoed (waiting for sunrise), the
404
page will include an additional headerX-SUNCYCLE: isUnderembargo
. -
If a page has been withdrawn (sunset), the
410
response will include an additional headerX-SUNCYCLE: isSunset
, and the301
aX-SUNCYCLE: isSunset <to>
where<to>
is the name of thesunsetto
page.
Example Use in a collection
In the kirby3 StarterKit you don't want the list of blog post to include any that are under embargo (waiting sunrise) or are sunset... it is very simple to implement.
site/collections/articles.php
looks like this:
<?php return function ($site) { return $site->find('blog')->children()->listed()->flip(); };
Change it to:
<?php return function ($site) { return $site->find('blog')->children()->listed()->isunderembargo(false)->issunset(false)->flip(); };
Note the use of false
in the filters for isunderembargo
and issunset
because its the pages that are NOT in this condition that are required.
Methods
This plugin makes the following methods available:
-
page.issunset()
: returns a boolean which istrue
if the page is currently sunset (i.e. withdrawn). -
page.isunderembargo()
: returns a boolean which istrue
if the page is currently under embargo (i.e. waiting for sunrise). -
pages.issunset( $match = true )
: a filter to return the subset of pages in a collection that are ($match = true
) or are not ($match = false
) sunset (i.e. withdrawn). -
pages.isunderembargo( $match = true )
: a filter to return the subset of pages in a collection that are ($match = true
) or are not ($match = false
) under embargo (i.e. waiting for sunrise).
Disclaimer
This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.
License
You are prohibited from using this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.