Use the `Formatted Date` meta header to explicitly set a page's formatted date (i.e. `$meta['date_formatted']`), and `Time` to set `$meta['time']`. Use the `Hidden` meta header to manually hide a page (the page is still accessible, but won't show up in the pages list). Note the difference between `$pageData['hidden']` and `$pageData['meta']['hidden']`.
AbstractPicoPlugin::$enabled now defaults to NULL what leaves the decision whether a plugin should be enabled or disabled by default up to Pico (precisely AbstractPicoPlugin::triggerEvent()). If all dependencies of a plugin are fulfilled, Pico enables the plugin by default. Otherwise the plugin is silently disabled (this was the behavior when AbstractPicoPlugin::$enabled was set to TRUE previously).
If a plugin should never be disabled *silently* (e.g. when dealing with security-relevant stuff like access control, or similar), set AbstractPicoPlugin::$enabled to TRUE. If Pico can't fulfill all the plugin's dependencies, it will throw an RuntimeException.
If a plugin rather does some "crazy stuff" a user should really be aware of before using it, you can set AbstractPicoPlugin::$enabled to FALSE. The user will then have to enable the plugin manually. However, if another plugin depends on this plugin, it might get enabled silently nevertheless.
No matter what, the user can always explicitly enable or disable a plugin in Pico's config.
We recommend plugin developers to use templates when serving HTML contents (like the UI of PicoAdmin), however, by supporting multiple file extensions for themes, we make it pretty hard to overwrite a plugin's template with a theme. As always, we preserve BC using PicoDeprecated.
Pico's page tree is a list of all the tree's branches (no matter the depth). Thus, by iterating a array element, you get the nodes of a given branch. All leaf nodes do represent a page, but inner nodes may or may not represent a page (e.g. if there's a `sub/page.md`, but neither a `sub/index.md` nor a `sub.md`, the inner node `sub`, that is the parent of the `sub/page` node, represents no page itself).
A page's file path describes its node's path in the tree (e.g. the page `sub/page.md` is represented by the `sub/page` node, thus a child of the `sub` node and a element of the `sub` branch). However, the index page of a folder (e.g. `sub/index.md`), is *not* a node of the `sub` branch, but rather of the `/` branch. The page's node is not `sub/index`, but `sub`. If two pages are described by the same node (e.g. if both a `sub/index.md` and a `sub.md` exist), the index page takes precedence. Pico's main index page (i.e. `index.md`) is represented by the tree's root node `/` and a special case: it is the only node of the `` (i.e. the empty string) branch.
A node is represented by an array with the keys `id`, `page` and `children`. The `id` key contains a string with the node's name. If the node represents a page, the `page` key is a reference to the page's data array. If the node is a inner node, the `children` key is a reference to its matching branch (i.e. a list of the node's children). The order of a node's children matches the order in Pico's pages array.
If you want to walk the whole page tree, start with the tree's root node at `$pageTree[""]["/"]`. The root node's `children` key is a reference to the `/` branch at `$pageTree["/"]`, that is a list of the root node's direct child nodes and their siblings.
You MUST NOT iterate the page tree itself (i.e. the list of the tree's branches), its order is undefined and the array will be replaced by a non-iterable data structure with Pico 3.0.
Don't lower unregistered meta headers on the first level unsolicited (e.g. `SomeNotRegisteredKey: foobar` in the YAML Frontmatter should result in `['SomeNotRegisteredKey']`, not `['somenotregisteredkey']`). Furthermore, Pico no longer compares registered meta headers in a case-insensitive manner. However, you can now register multiple search strings that are used to find a registered meta header. This is achieved by flipping the meta headers array: Pico 2.0 uses the array key to search for a meta value and the array value to store the found meta value. Previously it was the other way round (what didn't make much sense...).
The performance vs. error-proneness trade-off doesn't justify this additional complexity. This is Pico 2.0, we always try to minimize BC-breaking changes, but we're breaking BC anyway by loading plugins from plugins/<plugin name>/<plugin name>.php only...
You can now explicitly specify both the `date_formatted` and `time` meta values to overwrite Pico's page date handling. Specifying `time` doesn't make much sense in general, however, specifying `date_formatted` allows you to use `{{ meta.date_formatted }}` on all systems, even those where `strftime()` doesn't work as wished
This is a BC breaking change!
Manipulating Pico's $plugins array is a really bad idea. We've introduced the Pico::loadPlugin() method to safely load plugins at any time, however, Pico might do unexpected things when loading plugins too late. See the class docs of Pico::loadPlugin() for more details. Nevertheless, this change breaks BC to Pico 1.0. However, I don't know a single plugin that relies on manipulating the $plugins array. If you just want to load a plugin manually, use Pico::loadPlugin() instead.
Add new onPagesDiscovered event passing the unsorted pages array, move the $currentPage, $previousPage and $nextPage arguments from the onPagesLoaded event to the new onCurrentPageDiscovered event, remove the $twig argument from the onPageRendering event and rather trigger the new onTwigRegistered event for this. Also add the new onYamlParserRegistered and onParsedownRegistered events passing the YAML parser resp. the Parsedown instance. Allow plugin's to skip a page by setting the $id argument of the onSinglePageLoading event to NULL.
The vendor directory is the installation path of the `picocms/Pico` package. If `picocms/Pico` is the composer root package (as in pre-bundled releases), it should be identical to `Pico::getRootDir()`. However, if `picocms/Pico` was installed as composer dependency (e.g. by `picocms/pico-composer`), the vendor directory usually corresponds to something like `Pico::getRootDir() . "vendor/picocms/pico"`. The vendor directory is currently only used as a last resort to load Pico's sample contents.
Instead of using `*.config.php` files, use `*.yml` files to configure Pico. YAML is much easier to understand, more user friendly and (at least a bit) more error-tolerant, but still very powerful. Don't break BC by letting `PicoDeprecated` still read `config/config.php`.
Currently Pico::getTwigVariables() always returns the default twig variables and ignores all additions/changes made through the onPageRendering event. The method now returns the "real" variables array used by Twig.
Specifying a custom sort method usually means that all pages are sort by a plugin, so Pico's default alphabetical order is overwritten anyway. Letting Pico sort the pages first and discarding the result is burned CPU time...
Execution order matters: if plugin A depends on plugin B, it usually means that plugin B does stuff which plugin A requires. However, Pico loads plugins in alphabetical order, so events might get fired on plugin A before plugin B.
Hence plugins need to be sorted. Pico sorts plugins using a dependency topology, this means that it moves all plugins, on which a plugin depends, in front of that plugin. The order isn't touched apart from that, so they are still sorted alphabetically, as long as this doesn't interfere with the dependency topology. Circular dependencies are being ignored; their behavior is undefiend. Missing dependencies are being ignored until you try to enable the dependant plugin.
This method bases on [Marc J. Schmidt's Topological Sort library](https://github.com/marcj/topsort.php) in version 1.1.0, licensed under the MIT license. It uses the `ArraySort` implementation ([class `\MJS\TopSort\Implementations\ArraySort`](https://github.com/marcj/topsort.php/blob/1.1.0/src/Implementations/ArraySort.php)).
This method can be used to validate and filter input data and can be called via `Pico::getUrlParameter()` (URL GET parameters) and `Pico::getFormParameter()` (HTTP POST parameters). `Pico::filterVariable()` is basically a wrapper for PHP's `filter_var()` function with various compatibility extensions to allow theme developers to use its functionality in Twig templates. Therefore Pico 1.1 adds the `url_param` (`Pico::getUrlParameter()`) and `form_param` (`Pico::getFormParameter()`) Twig functions.
Resolves#305
\Symfony\Component\Yaml\Parser::parse() returns the unchanged value when a 1-liner string which is no valid YAML is passed. Assume this string to be the page title. Thus the following page will work now:
```
---
This is the title
---
# Example page
{{ meta.title }} is going to be "This is the title" - or "%meta.title%" == "This is the title".
```
This allows one to prevent Pico from removing the last "index" path component. Example use case: Pico's official admin plugin. We must distinguish between "content/sub.md" and "content/sub/index.md", otherwise it wouldn't be possible to edit both pages.
With Pico 1.0 you had to setup URL rewriting (e.g. using `mod_rewrite` on Apache) in a way that rewritten URLs follow the `QUERY_STRING` principles. Starting with version 1.1, Pico additionally supports the `REQUEST_URI` routing method, what allows you to simply rewrite all requests to just `index.php`. Pico then reads the requested page from the `REQUEST_URI` environment variable provided by the webserver. Please note that `QUERY_STRING` takes precedence over `REQUEST_URI`.
Symfony YAML interprets ISO-8601 datetime strings and returns timestamps instead of the string. This behavior conforms to the YAML standard, i.e. this is no bug of Symfony YAML.
Fixes#336. Thanks @csholmq for reporting this.
