Pico 2.0

[PhrozenByte]

At the moment this PR is "the mother of WORK IN PROGRESS"... 😄

Actually I don't have much to show yet, I'm primarily trying to point to PhrozenByte/pico-admin. I decided to start with development of the admin plugin, because it may give us some more ideas for Pico 1.1 2.0 (renamed 2016-12-12). Please use this PR to give feedback about the plugin (otherwise the discussion may get a bit fragmented).

@theshka: Do you think it makes sense to ask @picocms once again to convert his/her account to an GitHub Organization? This will allow us to use picocms/pico-admin instead... This is particularly meaningful when bearing in mind that I'm planning to create multiple repositories (picocms/pico-composer, picocms/pico-pagination, picocms/pico-tags, picocms/pico-feeds, picocms/pico-i18n, picocms/pico-search)...

Most importantly we have to make a decision about replacing Pico's default theme (see #297) with Pico 2.0 or to defer this until Pico 3.0. What are your opinions about this? (especially, but not solely, @theshka) My objections are primarily related to BC, but I have not formed a opinion about this yet. Please also refer to the "Decisions to make" section below.

Refer to http://picocms.org/phpDoc/pico-1.1/ for updated phpDoc class docs.

Plannings for the more distant future (i.e. Pico 3.0) can be found in #317. At the moment it's planned to let Pico 3.0 follow Pico 2.0 (i.e. no Pico 2.1).

As always, feedback is highly appreciated!

#edit: This release has been renamed to Pico 2.0 (previously Pico 1.1) on 2016-12-12, however we can't rename the branch, thus development will still happen on the pico-1.1 branch.

Planned changes to Pico's core

• Add Pico::VERSION constant
• Add includePico() function to prevent access to $this/Pico object in config/plugin files (use composer's includeFile() function instead?)
• [Feature Idea] Modular Config #330: Implement a modular config
  • 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.
• Allow Markdown configuration (Parsedown doesn't support much configuration, probably it will be limited to the optional usage of Parsedown instead of ParsedownExtra, Parsedown::setBreaksEnabled(), Parsedown::setMarkupEscaped() and Parsedown::setUrlsLinked())
• Create a (de facto never updated) pico-composer project to allow composer users to install Pico as dependency and benefit from composer's update mechanism; see @gilbitron's BaunCMS/Baun repo
  • Think about how users can easily install plugins with dependencies when they aren't using composer, but a pre-bundled release
• [Feature Idea] Internal 404 document #299: Integrated 404 Not Found page
• Add Pico::is404Content() method returning true when Pico::$requestFile doesn't exist (i.e. on404ContenLoading has been triggered)
• Remove PicoParsePagesContent
• Remove PicoExcerpt
• Don't sort pages when a unknown $config['pages_order_by'] is specified -- breaks BC
• Trigger the onMetaHeaders event only once, cache results of Pico::getMetaHeaders().
• Update README.md to use a screenshot hosted on our website
• Let users sort pages by arbitrary meta values (like Pico's sort_by Twig filter)
• Overhaul Pico::parseFileMeta(). Preserve BC with PicoDeprecated.
  • Don't lower unregistered meta headers on the first level unsolicited (e.g. SomeNotRegisteredKey: foobar in the YAML Frontmatter should result in $meta['SomeNotRegisteredKey'], not $meta['somenotregisteredkey']).
  • Don't compare registered meta headers case insensitive, rather allow registering multiple meta headers to result in the same meta value by flipping Pico::$metaHeaders
  • Let users explicitly set the formatted date in the YAML Frontmatter (e.g. date_formatted: Friday, 1st of December, 2000)
• Add a tree structure for all known pages

Planned changes to Pico's plugin system

• Allow Pico plugins to trigger custom events
• Add onSinglePageLoading event (new preliminary event to onSinglePageLoaded)
• When changing the $page parameter of the onSinglePageLoaded event to null, don't add this page to $pages (keeping $page['sub/page'] = null makes no sense, thus no BC break)
• Add plugin API versioning (new DummyPlugin::API_VERSION constant with Pico's major.minor version describing which API version the plugin expects; if the constant doesn't exist, assume 1.0); this allows us to overhaul the plugin event system in the future without breaking BC
  • parsedown extension #318: Add onParsedownRegistered event and pass $parsedown (instance of Parsedown) to allow extending erusev/parsedown
  • Replace onTwigRegistration event with onTwigRegistered and pass $twig (instance of Twig_Environment), remove $twig parameter from onPageRendering event
• Let PicoDeprecate differentiate between legacy levels (i.e. always enable the plugin to e.g. read config.php in Pico's root dir, but trigger deprecated events only when plugins of a specific legacy level are present)
• Allow to manually load plugins (i.e. add Pico::loadPlugin() method)
• Allow Pico plugins to be installed through composer.json
• Support multiple plugin dirs
• Add hook/event for Pico::getPageUrl()
• Add more events to Pico::readPages(), similar to the events of the current page
• Order plugins (execution order matters!) by evaluating their dependencies. Older plugins implicitly depend on PicoDeprecated. See tsort, marcj/topsort.php, haberco/topological-sort-php.
• Add a event between onPagesLoading and onPagesLoaded passing the unsorted pages array (e.g. onPagesDiscovered).
  • Also remove the $currentPage, $nextPage and $previousPage parameters from the onPagesLoaded event, fire a separate event to "publish" them
• Load plugins from plugins/<plugin name>.php (non-recursive) and plugins/<plugin name>/<plugin name>.php (the class file must be named after the directory) only. Plugins with multiple classes may need to register an autoloader on their own. Also see Should load_plugins() only load plugin_name.php? #203 -- breaks BC

Planned changes to Pico's UI (themes, Twig, routing, …)

• No "/index" in links in html code to index.md files #347: Drop the "index" part of URLs
• Support multiple theme dirs
• Make theme_url configurable; the default value should support that Pico::$themesDir is a arbitrary deep sub path of dirname($_SERVER['SCRIPT_FILENAME']) (i.e. index.php resp. httpdocs folder); otherwise fallback to themes (and not basename(Pico::$themesDir))
• Use Twig blocks in default theme (i.e. {% block replace_or_extend_me %}...{% endblock %})
• [Feature Idea] Pass $_GET to Twig template #305: Allow access to query string in Twig templates (i.e. $_GET superglobal)
• Support REQUEST_URI-based URL rewriting to allow a much simpler webserver configuration
• Use flexbox in Pico's default theme to pin the footer to the bottom of the window
• Drop {{ site_title }} and {{ rewrite_url }} in favour of their its {{ config.* }} equivalents. Rename {{ current_page }} to {{ page }}. Drop {{ is_front_page }} (use {% if page.id == "index" %} instead). Preserve BC with PicoDeprecated.
• Calculate the previous and next page for all pages (doesn't increase calculation time, array_search() in Pico::discoverCurrentPage() walks through all pages anyway). Drop {{ next_page }} and {{ previous_page }} in favor of their resulting {{ page.* }} equivalents (see above). Preserve BC with PicoDeprecated.
• Add only pages of the first level to the page navigation by default (e.g. page.md and sub/index.md, but not sub/page.md) -- breaks BC (more or less...)
• Ignore all pages starting with a _ for the page navigation by default (e.g. _meta.md and all files in _collection/ are skipped) -- breaks BC (more or less...)

Website & Documentation

See picocms/picocms.github.io#18

• Add Bountysource (merge enhancement/bountysource branch)

New official plugins/themes

The following plugins won't defer the release of Pico 2.0:

• Blog features
  • ☐ Pagination
  • ☐ Tags
  • ☐ RSS Feeds
  • ☑ Add hidden identifier in blog posts file naming #365: File Prefixes
• ☑ Robots (serve a robots.txt and sitemap.xml)
• ☐ Contact form
• ☐ Article Excerpts and Twig Filter #376 (comment): Excerpts
• ☐ Use Twitter Bootstrap 4 for Pico default theme. #297: Bootstrap 4 theme
• ☐ Editor/Page Admin

[mayamcdougall]

👍

Also, glad to see some of my ideas in that list. 😉 😄

[mayamcdougall]

I like the modular config implementation (988a23f) (the concept of it, can't really critique the php).

My only concern would be that .config.php is an odd naming convention / file extension. There isn't really anything wrong with it, it just struck me as odd.

In practice, it would probably work well though. NotePaper.config.php is just as good, if not better than NotePaper-Config.php. 😒 It just seemed like a weird thing to require.

I suppose it'll help enforce a unified naming scheme between developers though. 😆

Anyway, nice work with it. I was expecting a feature like that to take more than one commit! 👍

[PhrozenByte]

Pico v2.0.0 is out now! (yes, the stable release!) 🎉

See #401 (comment)