Development | Release 0.20 - 23/04/21

[johanjanssens]

It's been a productive few weeks again, after spending the start of 2021 on stabilising and bug fixing the 0.19 release we are back on track with with feature releases.

Releases

Joomlatools Pages

• v0.20.0: https://github.com/joomlatools/joomlatools-pages/releases/tag/v0.20.0
• v0.20.1: https://github.com/joomlatools/joomlatools-pages/releases/tag/v0.20.1

Joomlatools Framework

• v3.5.0: https://github.com/joomlatools/joomlatools-framework/releases/tag/v3.5.0

Changelog

Joomlatools Pages v0.20

Pages v0.20 brings some exciting new features that allow you to turn Joomla into a Hybrid CMS. Pages now offers 2 decoration flows:

• menu item based decoration
• component based decoration

And best of all you can mix and match as you wish. You can mix decorated menu items, with normal pages, running through Joomla templates or Pages themes in any way the works best for you.

Decoration Improvements

In short, the decorator can now be used as a Joomla menu manager. You can can define menu item settings like title, description, template, modules, and params etc all through it.

The only thing that didn't make it in this release is the ability to inject menu items in Joomla menu modules. This being planned for a later release.

1. Use Pages as Joomla template engine #654

Based on a request from @kbrookes made it possible to use Pages as a template engine.You can now use a Pages theme as a replacement for a Joomla template and wrap it around any menu item. You get all power that comes with Pages:

1. The whole template engine, layouts, filters, helpers, functions, partials etc.
2. Superb caching, you can even make use of the static caching (*)
3. All of the routing magic

(*) Pages caching allows you to cache even pages that include forms, like a login page. Pages handles the the CSRF tokens for you, instead of a session bound token it uses a cache bound token and implements an origin check to ensure you are 100% secure and can still make use of super caching.

---
layout: index
process:
    decorate: true
---

<ktml:content>

Routing support has also been added to the decorator. This means that you get complete control over what url's are decorated and which are not and that per decorator. You can:

• Apply custom Pages themes to Joomla menu items on a per url basis
• Change Joomla template settings on a per url basis.

2. Component decoration #659

You cannot only decorate menu items by url route, you can now also decorate components directly by specifying menu item parameters through the frontmatter. Pages will create a virtual menu item and handle rendering and routing of the component.

---
route: articles/[*:component]?
process:
    decorate:
        component: content
        view: categories
---

Note: Pages will not inject your page into the Joomla menu modules. This is out of scope for this release, but is being planned for a future release

Template filter improvements

Template filters became a lot more powerful, you can now define them per layout or per page, you can set config options through the frontmatter and you can exclude them from child layouts or pages. This gives a whole lot of power and flexibility to yours layouts and keep code clean and re-usable.

3. Allow to pass filter config options in frontmatter #627

It's now possible to define template filter config options in the frontmatter. Example:

---
layout: developper/article
process:
    filters: [toc, highlight: {selector: article, badge_lang: false}]
---

4. Exclude filters #622

Exclude filters in a child layout, or page. The filter is disabled but will still run to make sure it cleans up any tags without filtering the page content.

---
process:
    filters: -toc
---

Javascript behavior improvements

5. Alpine.js added #642

Added a template helper to easily use alpine.js The code is loaded from https://unpkg.com/, the version to load can be configured through the helper. Default version is set at 2.8.2. To include alpine js:

<?= helper('behavior.alpine', ['version' => '2.8.2']); ?>

6. Load assets from cdn #633

All vendor js/css assets are now loaded from CDN's, either unpkg.com or from files.joomlatools.com. Each behavior has a configoption to make it easy to configure the version to be used.

The files.joomlatools.com endpoint is now a full assets CDN that integrates with Github. It's capable of serving release assets, and caching them. For example: https://github.com/joomlatools/joomlatools-pages/releases/tag/v0.19.10

Possible urls:

• https://files.joomlatools.com/pages (will redirect to latest release)
• https://files.joomlatools.com/[email protected] (will download specific release)
• https://files.joomlatools.com/[email protected]/prefetcher.min.js
• https://files.joomlatools.com/pages/prefetcher.min.js

You can use these url's to easily install Pages on into a site. Doing an install by url, just use https://files.joomlatools.com/pages to get the latest pages release, and let Joomla do the rest.

Accessibility improvements

Done a lot of work on improving accessibility for any html markup generated by Pages.

7. Improve pagination #641

The paginator markup is now 100% semantic, accessible, and SEO optimised.

• ARIA: The ARIA implementation is based on https://www.a11ymatters.com/pattern/pagination/ and ensure that screenreaders can properly read the links. A page will read as Go to page 1 or for the current page read as Current page, page 1.

• SEO: Support for link relations has also been added following https://www.contentkingapp.com/academy/pagination/ The paginator will automatically add the related links to the page head and ensure a proper canonical link is present.

• Microdata: added http://schema.org/SiteNavigationElement

8. Remove anchorjs in toc filter #639

Replaced [acnhorjs](https://www.bryanbraun.com/anchorjs/à in the TOC filter with an accessible vanila css/html solution. Anchors are implemented by making the headers links themselves, rather than a separate link for the following reasons:

• it's a bigger tap area for mobile
• it avoids those Google SERP, RSS and Reader Mode issues
• it means you don't need to worry about the label text
• it allows you to hide the anchor icon (inserted with a ::before { content: icon }) on mobile or only when focus/hovered or remove it completely (though there are discoverability issues with some of those options).
• Its accessible with screenreaders. Voice Over reads it out as "This is a heading. Heading Level 2. Visited. In page link."

Reference implementation: https://codepen.io/johanjanssens/pen/PoWObpL

Other improvements

9. Template url for form redirects #637

The redirect parameter defines the location to be redirected to and can be templated using the template URI's standard. When a template URI is used the submitted form data will be used to expand the template url. For example:

form:
   redirect: http://example.com/{id}
   schema:
        name: [string, required]
        email: [email, required]
        id: [string, required]

The id could be from a drop-down list, a hidden parameter, or calculated by javascript on the client, etc.

10. Added 'debug' config option #635

adds a new debugconfig option. By default the value reflects your Joomla debug setting unless configured otherwise.

<?php
return [
    'debug' => true
];

<? $debug = config('debug') ?>

11. Improve cache location handling #648

Improved the cache location and cache file naming making it easy to configure the default cache location for a site. This allows to move the cache outside of the site root, or to alternate the cache location for the same site, for example to setup a content staging environment for the same site.

Joomlatools Framework

We have also released Joomlatools Framework 3.45.0 which brings a number of important improvements.

PDO support

The database layer got a indepth refactor. We added PDO support. All changes ares 100% backwards compatible so no need to worry it all just keeps working:

• you now do Koowa::getObject('database'); to get the database adapter
• you now do Koowa::getObject('database')->getQuery('select'); to get a database query

Both return the active Joomla database connection, databaseis the identifier for the active database singleton. These changes bring PDO support to our framework, which makes it possible for Pages to easily connect to different database, local or remote. Work has already been done in a previous fw release to make sure the framework can use multiple database connections at the same time.

The bigger reason for this is not PDO, but SQLite. Through PDO we can now offer support for SQLite. SQLIite solves a lot of problems we have with datbases, it's flat file, portable, easy to backup and can can be used from the browser and the edge.
Worth reading https://antonz.org/sqlite-is-not-a-toy-database

There is a lot of cool things happening with SQLite:

• https://github.com/lspgn/edge-sql
• https://litestream.io/blog/why-i-built-litestream/
• https://sql.js.org/#/

If a database is required, for example for caching purposes, SQLite will be what we will be using in Pages as out go to solution.

CSRF protection

The approach used in Joomla is to include a token in any form. The token is stored in the users session and checked when the form is submitted. This approach is no longer required, all modern browser support origin headers now, and you can use them to prevent CSRF.

This change has two very nice side-effects:

• Since we no longer use a token to secure the form, the forms become cacheable.
• Since we no longer need a session to handle forms, it becomes possible to run Joomla without sessions for none logged in users.

Sessions can have a big performance impact especially on high traffic sites, as they make multiple db calls per request and can generate a lot of db row. So, better cache-ability and better performance.

Related note:

This also works for pages that use forms not created by pages. Pages replaces Joomla CSRF session tokens on the fly by a cache token which is unique per page. The cache token is re-generated each time the cache is refreshed and replaced with the session form token when a form submission is received to allow Joomla to validate the request. More info: #422

See: joomlatools/joomlatools-framework#464

Exceptions

Exceptions in Joomlatools Framework are exposed as events, meaning that you they can be easily intercepted through event handlers, in Joomla's case through plugins. This allows for a whole lot of flexibility. Based on the type of exception different event handlers could do different things, for example;

• handling 404 not found exceptions
• handling error logging
• rendering debug information

See: joomlatools/joomlatools-framework#468

Explicitly pass database adapter to queries

We have improved the flexibility of the database adapter to allow to use multiple adapters and different database connections. This will allow in a next step to have different collection that connect to different local and or remote databases.

See: joomlatools/joomlatools-framework#459

Koowa::getObject

We added a new $object = Koowa::getObject([identifier]); static method that makes it very easy to instantiate any framework and or extension object through it's identifier anywhere once the framework is bootstrapped. To learn more about object identifiers please check our framework internals docs

See: joomlatools/joomlatools-framework#471