Joomla, Custom Fields and external data ● powerful overrides made easy with Joomlatools Pages

by Marc Dechèvre

Woluweb

Marc

all presentations on https://slides.woluweb.be

1 JoomlaDay USA

This presentation which could alternatively be named
Joomlatools Pages - a beginner’s guide
was made especially for

JoomlaDay USA | 24 April 2021 | #jdayusa
The video content will only be available to paid registrants of https://jdayusa.com
JoomlaDay France | 18 June 2021 #jd21fr
The video will be available for the members of https://www.joomla.fr

2 Introduction

2.1 Demo site

We have built a demo site so that you can see the results of all the actions explained step by step in this presentation

https://pages.joomlacustomfields.org/

The corresponding code is - directly visible on the demo site: https://pages.joomlacustomfields.org/code - can be downloaded directly from the demo website (full backup of the website) - and also on Github (probably an older version): https://github.com/woluweb/Joomlatools-Pages-Demo

2.2 Joomlatools Pages - useful links

Joomlatools Pages is free and open source (feel free to contribute/give back!)

Example taken from the Wiki: https://github.com/joomlatools/joomlatools-pages/wiki/Functions

Joomlatools Pages comes out-of-the-box with template functions that help you to easily customise your template. Functions are only supported for the PHP engine. Of course, you can also use any PHP function in your templates.

page()
collection()
data()
route()
snippet()
state()
attributes()
helper()
import()
date()
slug()
json()
format()
replace()
url()
user()
empty()
config()
element()
unbox()
Custom Functions

Note:

https://files.joomlatools.com/pages
https://files.joomlatools.com/pages/ext_joomla.zip

will download the latest versions of Pages and the Joomla Extension

2.3 Joomlatools Pages - presentations by the author himself

Johan Janssens, the father of Joomlatools Pages, has already made three general presentations: - JoomlaDay USA | 24 April 2021 | Building a Joomla site with Joomlatools Pages - JoomlaShack Conference | 14 Dec 2020 | The Evolution of Web Publishing from 1990 to 2020 - JoomlaShack Conference | 11 May 2020 | An Interview with Johan Janssens about Joomlatools Pages

2.4 Why this presentation

I share two qualities with Johan Janssens : - we are both Belgians 😀 - we are both Joomla fans 😉

Johan, who is also one of the cofounders of Joomla itself, is of course an excellent developer.

I don’t consider myself as a developer (I don’t code extensions, even if I play a lot with overrides which entails some PHP knowledge).

I am more an integrator and what could be called an power user: I know Joomla by heart and like to use its full capabilities.

And I am definitely a Joomla Custom Fields ‘evangelist’ since it was released with J!3.7 thanks to Allon Moritz aka Laoneo.

Custom Fields are indeed a game changer and has made Joomla much more powerful, especially if you use overrides in order to customise the Layout.

So when I discovered Joomlatools Pages, I immediately saw a great opportunity because - it makes overrides much easier - it integrates the Custom Fields - it allows to filter - it gives new possibilities like fetching data from external sources (json files for example) - and even non-coders or coders who don’t know Joomla can immediately use it

So why this presentation?

Simply because I am always happy to share my enthousiasm a.o. about everything related to Joomla Custom Fields.

And also because I like to learn by doing. So I thought a good way of showing some of the features offered by Joomlatools Pages would be to make a step by step demo.

2.5 Focus on Pages to make overrides including Custom Fields and fetching external data

Joomlatools Pages can already do so many things (plus the fact that features are regularly added/improved) that it would probably take a full day to cover them all…

So in this presentation we will ‘only’ see how to make (blog view and article view) overrides including Custom Fields and fetching external data because even so there is already so much to tell!

As you will see, Pages is so powerful and yet so easy…

In particular, Joomlatools Pages allows to fetch and display collections from - Pages (default) - a collection will be retrieved from within the pages folder. If a model is not specified in the frontmatter, the collection is automatically pages. - Filesystem - a collection will be created from one or more data files in the filesystem. - Database - a collection will be created from any database table. - Web Service - a collection will be created from any URL as long as the URL returns structured data.

3 The initial setup

Before playing with our new tool, let’s prepare Joomlatools Pages and our website

3.1 Install

Go to https://github.com/joomlatools/joomlatools-pages/releases
Download the latest package
Install the ZIP file the usual way :
- Go to your YOURSITE.COM/administrator > Extensions > Manage > Install
- Upload the package.

When you see “Installation successfully completed!” you are done
(don’t worry if the interface is a bit different from usual after installation: Pages uses its own installer)

For other installation methods, see https://github.com/joomlatools/joomlatools-pages/wiki/Installation

3.2 Nothing new in the administration interface…

Now that Pages is installed (together with the Joomlatools Framework), you will notice… that nothing has changed in the backend 🙂

No new Component, no Configuration, no anything.

Actually this is totally normal…

3.3 Updating Pages

3.3.1 Joomla Update Manager

Note:

Pages is now a Joomlatools Framework component, it’s no longer a Joomla component and it’s not “installed” in Joomla. This approach allows Pages to also be run standalone
therefore Pages does not use the Joomla Update Manager bc the updater is too basic for the way the framework works (it manages the dependencies, which is not the case of the regular updater)
If you want to be notified of new versions of Pages, go to the Github page and simply click on the Watch button

3.3.2 What is the process to update Pages

See this explanation (which also covers When to update Pages):

https://github.com/joomlatools/joomlatools-pages/discussions/760

Don’t forget to also replace your extension(s) if they were updated (which you see in the release’s changelog for example with a fixed - ext:joomla

3.4 Before starting: SEF

Do not run Joomla sites anymore with SEF disabled, this setting should be enabled at all times. The only reason it was allowed not to turn SEF on in Joomla 1.5 was to allow for a solid migration path from 1.0 to 1.5, we are now 15 years later, every Joomla site should have SEF enabled by default.

So if you have not already done so - go to System > Global Configuration > tab ‘Site’ > block ‘SEO Settings’ > set option ‘Search Engine Friendly URLs’ to ‘Yes’

3.5 Before starting: URL Rewriting

Oh btw nobody wants to see that /index.php/ in the url, right?

So if you have not already done so - go to System > Global Configuration > tab ‘Site’ > block ‘SEO Settings’ > set option ‘Use URL Rewriting’ to ‘Yes’ - at the root of your website be sure htacces.txt was renamed into .htaccess

Then the url https://pages.joomlacustomfields.org/index.php/step1 simply becomes https://pages.joomlacustomfields.org/step1

Note: Pages requires ‘SEF’ to be enabled but it can work without ‘SEF rewrite on’. Then of course you need to keep the /index.php/ in the url and do http://example.com/index.php/[page]

3.6 Before starting: default configuration

Pages is build using a “no configuration required, everything has a default” approach.

This means that you do not require anything in your config.php to get started. Anything you add there would override a default.

3.7 Create the folder

Using your File Manager or your FTP connexion, create the following folder and subfolder

/joomlatools-pages/pages/

3.8 Let’s create some content with Custom Fields

create an Article Category with Alias: organizations
create 3 articles in that Category with an image (intro or full)
create a Custom Field (of type Text for example) with the following Name: socialbrusselsid
create a Custom Field (of type URL) with the following Name: youtube
assign those Custom Fields to the Article Category ‘organizations’
assign the following values to the Custom Field ‘socialbrusselsid’: 13817, 3322, 10600 (for example)
assign the following values to the Custom Field ‘youtube’: https://www.youtube.com/watch?v=g21IiNrkhXA, https://www.youtube.com/watch?v=Gooof6e6BvQ, https://www.youtube.com/watch?v=LXeaDPmHP18 (or any other YouTube video of course 🙃 I simply chose those ones bc my daughter plays drums with her progressive rock band)

The socialbrusselsid Custom Field will allow us to combine our articles with information fetched from an external website via webservices.

Example: - https://social.brussels/organisation/13817 (‘human’ format) - https://social.brussels/rest/organisation/13817 (json format)

3.9 See the latest version of the source code on the website itself

To make it easy, I have copied the source of each page in the slides of this presentation itself.

But regularly I bring improvements. So if you want to be sure to get the latest version, they are directly visible on the demo website:

https://pages.joomlacustomfields.org/code

Note: how can I display the source code automatically on the website? Txs to Joomlatools Pages itself.

All I have to do is to create a file

code.html.php

with the following content

 ---
@process:
    filters: [highlight]
 ---

<?= source('step6') ?>

where step6 refers to my file step6.html.php which is created later in this presentation.

Note: in this example and on most of the following ones, I have added

@process: filters: [highlight]

in the Frontmatter. This gives automatic code highlighting.

On a production site you would probably remove it, but here I have included it bc I display on purpose the whole array of articles with

<pre><code><?= var_dump(collection()); ?></code></pre>

See https://github.com/joomlatools/joomlatools-pages/discussions/668 for more information.

Note: to change the style from light atom-one-light.min.css to dark atom-one-dark.min.css, simply adapt /components/com_pages/template/filter/highlight.php accordingly

4 Updating from 0.19 to 0.21

JoomlaTools Pages 0.21 was released in June 2021 and came with plenty of improvements and new features.

It can now also run in Standalone mode.

4.1 Release notes

For an overview (and also for more information on a few breaking changes) see https://github.com/joomlatools/joomlatools-pages/discussions/738

4.2 My own checklist for upgrade

if you created Menu Items of type Pages, those don’t exist any more => simply use Menu Items of type System Links > URL instead (one exception to that at the moment: the Home menu item. See https://github.com/joomlatools/joomlatools-pages/discussions/758)
delete the /cache/ directory
create a /templates/ and move the /partials/ directory into it
in all frontmatters where it applies
4.1. add a @ in order to have respectively @route, @layout, @collection, @form, @process
4.2. change extend: path : add a slash before the path to get extend: /path
4.3. change data: items into data_path: items

all routes and paths need to start with / both in frontmatter and in route calls
change <?= import('/partials/embeds/myfile') ?> into <?= partial('/embeds/myfile') ?>
change <?= $item->getRoute() ?> into <?= route($item) ?>

5 A step by step demo

The idea of this step by step demo is to onboard everybody, even completely non technical persons.

5.1 Joomlatools Pages with HTML input

Let’s start with something super easy: a little HTML file.

5.1.1 Create the file

In the folder /joomlatools-pages/pages/ create a file named

step1.html

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step1)

 ---
title: A HTML page
summary: This page is a static HTML page.
 ---

%INCLUDE code/step1.html%

5.1.2 See the result

Go to https://pages.joomlacustomfields.org/step1 and see the result: step1.html is displayed as if it were a regular Joomla article!

So actually, so far we already have a kind of Flat File CMS 🙂

But the nice thing is that you still benefit from - your template with its design (CSS, …), its modules, … - and all the other Joomla features

5.1.3 Metadata

Do you want to customize the Title and the Description of the page ?

This can also be done very easily by adding this at the beginning of your file

 ---
title: A HTML page
summary: This page is a static HTML page.
 ---

See https://github.com/joomlatools/joomlatools-pages/wiki/Metadata for more information

Note: the part between — and — is called the Frontmatter

5.1.4 Creating a menu item - optional

The following step is not required, however if you want Joomla to show a menu item for your page you can do so by creating one.

In the administrator interface, go to your menu manager and create a new menu item. Strictly speaking the Menu Item Type could be anything: if Pages has a file named after the alias of the menu item, it will take precedence.

So a typical choice would be to create a Menu Item of type ‘System Links > URL’ and set the Link field to /step1

5.1.5 Multilingual websites

Once you have played with Joomlatools Pages it will seem obvious to you: if you have a multilingual website and the url of a page in English is YOURSITE.COM/en/step1 then the corresponding file should be

/joomlatools-pages/pages/en/step1.html

and not

/joomlatools-pages/pages/step1.html

5.2 Joomlatools Pages with MarkDown input

You don’t know what MarkDown is ? - see https://en.wikipedia.org/wiki/Markdown - in a few words, it is a lightweight markup language for creating formatted text using a plain-text editor

5.2.1 Create the file

In the folder /joomlatools-pages/pages/ create a file named

step2.html.md

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step2)

 ---
title: A Markdown page
summary: This page is rendered by the Markdown engine.
 ---

 ## Hello World!

Welcome to my new page in **MarkDown** format.

5.2.2 See the result

Go to https://pages.joomlacustomfields.org/step2 and see the result: step2.html.md is displayed as if it were a regular Joomla article!

All my presentations (including this one) are written in MarkDown format (.md file). This means that I could now very easily display on my website a nice HTML version of those Presentations.

5.3 Joomlatools Pages with PHP input

Let’s start with a simple PHP example

5.3.1 Create the file

In the folder /joomlatools-pages/pages/ create a file named

step3.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step3)

 ---
title: A PHP page
summary: This page is rendered by the PHP engine.
 ---

%INCLUDE code/step3.html.php%

Note the short syntax
<h2><?= $title ?></h2>
instead of what we usually have in Joomla files
<h2><?php echo $title; ?></h2>

5.3.2 See the result

Go to https://pages.joomlacustomfields.org/step3 and see the result.

5.3.3 Insert markdown directly in your PHP file

With Pages you can also insert directly markdown (or other types of file) in your PHP file with the following syntax:

<ktml:partial format="md">
**Why not** put some *markdown* written directly in our file?
</ktml:partial>

5.4 Joomlatools Pages with PHP input fetching external data

And now a killing feature: how to get data from an external website (in this case in json format) in 1 (one!) line of code.

For this demo, let’s use the open data made from https://social.brussels/ which gives all the details (name, address, phone number, …) of all Social organizations in Brussels.

5.4.2 Create the file

In the folder /joomlatools-pages/pages/ create a file named

step4.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step4)

 ---
title: A PHP page fetching external data from json file
summary: This page is rendered by the PHP engine.
 ---

%INCLUDE code/step4.html.php%

5.4.3 See the result

Go to https://pages.joomlacustomfields.org/step4 and see the result.

5.4.4 Caching

And the good news is: external data can be easily cached and you can choose the duration easily.

For more info see: https://github.com/joomlatools/joomlatools-pages/pull/512

By default caching is enabled and the data will not be revalidated.

But thanks to the data([url], [cache]) template function you can customize this.

Example if you want to cache for 24 hours:

<? $data = data([url], '1day'); ?>

In this example we make multiple calls to the same resources.

So the question is: what does happen with the Cache ?

Each time you make a call to data, Pages will check if the resource it has cached is still valid. If it is it will use it from cache, if not it will update. So multiple data() functions to the same url with a diff cache time the lowest time wins.
One caveat here: if you call it with a higher cache time first that call might result in data not being updated, while data lower on the same page with a call with a lower cache time is updated. This would happen only on the first refresh of the page, the second time you render the same page since the data was updated in cache you get the correct results for all calls

5.5 Blog view using table=content from database

It is now time to build a simple Blog view.

Pages allow indeed to query directly any Joomla table

5.5.1 Create the file

In the folder /joomlatools-pages/pages/ create a file named

step5.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step5)

 ---
@collection:
    model: database?table=content
 ---

%INCLUDE code/step5.html.php%

5.5.2 See the result

Go to https://pages.joomlacustomfields.org/step5 and see the result.

5.5.3 Images options are stored in JSON format in Joomla

If you have already seen Joomla’s native code or made overrides, you know about this: the Article Image’s options are stored in the database in JSON format. So to get the path/name of an image, we must first json_decode it:

<? $article_images  = json_decode($article->images);?>
<img src="<?= $article_images->image_intro; ?>

5.6 Blog view using ext:joomla.model.articles and links with the Joomla router

Accessing directly a table from the database was already nice but it is possible to do much more thanks to Joomlatools Pages’ Joomla Extensions

For more information see https://github.com/joomlatools/joomlatools-pages/pull/363

5.6.1 Install Joomlatools Pages’ Joomla Extensions

go to https://github.com/joomlatools/joomlatools-pages > Releases (latest)
in the Assets, download extension-joomla.zip
create the following folder joomlatools-pages/extensions/
upload the zip file as such into that newly created folder (no need to even rename the file)

So actually with Pages ‘installing’ extensions is just ‘uploading’ them…

For more information, see https://github.com/joomlatools/joomlatools-pages/discussions/738#Overview

5.6.2 Create the file

In the folder /joomlatools-pages/pages/ create a file named

step6.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step6)

 ---
@collection:
    model: ext:joomla.model.articles
    state:
        published: 1
        category: [organizations]
        sort: date
        order: asc
        limit: 3
 ---

%INCLUDE code/step6.html.php%

Note:

The ext:joomla.model.articles is available also with the alias articles, so you can do collection('articles')

5.6.3 See the result

Go to https://pages.joomlacustomfields.org/step6 and see the result.

5.6.4 Filtering and sorting

In the Frontmatter we can very easily filter and sort our content thanks to the state: - we filtered on published articles: 1 - we filtered on the category: alias or ID will do - we sort by ascending date - we can also limit the number of articles: 3

Very easy to visualize and write…

Note: if you want to filter on multiple categories, simply use the following syntax:

category: [organizations, uncategorised]

5.6.5 Some customized styling with CSS Grid and/or Flexbox

For the HTML/CSS of this demo, we did not want to bother with Bootstrap because - most of the recent templates use BS4 - some websites’templates still use BS3 - Protostar is based on BS2 - … and Joomla4 will use BS5

So if I had used Bootstrap, you could not necessarily simply copy/paste the code to get the same result if your Bootstrap version is different (or if you are using another framework like UIKit, Tailwind, …).

Instead, to get something easier, lighter and more universal, we simply use here CSS Grid and Flexbox.

If you have no clue what it is, you should definitely have a look at it. Especially for CSS Grid since Joomla4 is based on CSS Grid, which is a (very) good thing.

Note: as you can see, I am using here ‘inline CSS’ with a style tag directly inside my HTML.
You don’t even need to put it in your template ‘custom css’ because Pages will automatically put the CSS into the <header> of your site!

5.6.6 Using the Joomla Router

You want the Title to have a link to the Article itself?

Using the native Joomla Router the following single line will do:

<a href="<?= route($article) ?>"><?= $article->title; ?></a>

5.6.7 A direct access to the image path/name

If you look at the code you will notice that, using ext:joomla.model.articles, we don’t need to play with json_decode to get the image path/name. It is indeed immediately available:

<?= $article->image->url; ?>

Note 1: actually, in the code itself I should first check that there is an image before displaying it. So here is the code to display an Article image (with its Title and Description) only if it exists:

<? if( !empty( $article->image ) ): ?>
    <img src="<?= $article->image->url; ?>" alt="<?= $article->image->alt; ?>" title="<?= $article->image->caption; ?>">
<? endif; ?>

Note 2: is it the intro image or the full text image ? See the answer here: https://github.com/joomlatools/joomlatools-pages/discussions/673

5.6.8 Category title/alias

If you look at the code you will notice that, using ext:joomla.model.articles, we can access the Category title/alias directly:

<?= $article->category->title; ?>

5.6.9 introtext/fulltext

If you look at the code you will notice that, using ext:joomla.model.articles, we don’t use introtext/fulltext but excerpt/text.

For more information, see https://github.com/joomlatools/joomlatools-pages/discussions/667

5.6.10 Custom Fields

Custom Fields are sooooo easy to display:

Custom Field's label: <?= $article->fields->socialbrusselsid->label ?>
Custom Field's rawvalue (ie the value in the database): <?= $article->fields->socialbrusselsid->value ?>
Custom Field's rendering (ie using Joomla's default rendering with the CF's options): <?= $article->fields->socialbrusselsid ?>

Note: using the simple $article->fields->customfieldalias (so without referring to label or value) is very nice because it will use the Joomla’s rendering.

This is particularly useful if you are using third-party Custom Fields allowing to easily display Maps, Videos, Sound etc (see for example those proposed by Tassos: https://www.tassos.gr/joomla-extensions/advanced-custom-fields)

But beware: if you have spaces in the Title of your Custom Fields, Joomla will by default suggest a Name with dashes.

This is OK but then you will have to use one of these syntaxes

$article->fields->get('with-dash')->value
$article->fields->{'with-dash'}->value

instead of the short syntax

$article->fields->withoutdash->value

So to keep things simple I suggest to avoid dashes in the Names of the CF.

5.6.11 External JSON

How do we fetch information from an external website ? - we have a Custom Field with Name ‘socialbrusselsid’ - the value of that CF for a given article is 13817 - the following url contains all the information we want to fetch: https://social.brussels/rest/organisation/13817 - let’s suppose we want to display the Street of that organization in Dutch, namely: ->address->streetNl - and let’s suppose we want to cache that information for 1 day - then the following single line does it all!

<?= data('https://social.brussels/rest/organisation/'. $article->fields->get('socialbrusselsid')->value, '1day')->address->streetNl ?>

5.6.12 More generally, retrieving data from a SAAS service

See https://github.com/joomlatools/joomlatools-pages/discussions/505

Retrieving data from a SAAS service with Pages is very easy. Pages handles data sources in a transparent way. It doesn’t make a difference if you connect to a database, a webservice or a file on the filesystem. They all work in exactly the same way.

To work with data Pages uses collections and specifically for webservices, there is a base webservice collection you can use.

Every collection can be: filtered / sorted / searched / paginated

Pages offers out of the box support for JSON and can even read CSV from a webservice, which is a great way to integrate with things like Google Spreadsheets.

An example would be

 ---
@collection:
   model: webservice?url=http://example.com/api/endpoint
 ---

<? foreach(collection() as $item) : ?>
   <?= $item->title ?>
<? endforeach; ?>

assuming that the service returns a title property

5.6.13 Comparison with a typical native Joomla override

Of course, the scope is not exactly the same (I did not include some Article Options to keep it short for the presentation), but see how simple/concise/readable this code is compared to the code of a typical native Joomla override:

https://github.com/joomla/joomla-cms/tree/staging/components/com_content/views/category/tmpl

See for example blog.php and blog_item.php

5.7 Blog view using ext:joomla.model.articles and links with the Joomla router - and partials for Custom Fields

Let’s put some parts of the code in little files (called partials) so that - they are more readable - they are easier to maintain - they can be reused at different places

This will allow us for example to easily transform - a simple Text Custom Field into a block of text made of many fields taken from an external json - a simple URL Custom Field containing the URL of a YouTube video into a player with the desired options

5.7.1 Create the file

In the folder /joomlatools-pages/pages/ create a file named

step7.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step7)

 ---
@collection:
    model: ext:joomla.model.articles
    state:
        published: 1
        category: [organizations]
        sort: date
        order: asc
@process:
    filters: highlight
 ---

%INCLUDE code/step7.html.php%

5.7.2 Create the partials for the Custom Fields

In Joomla when you want to create a new type of Custom Field you typically have to create a little plugin.

This is fairly easy for someone who can code a bit.

But it becomes even much easier with Pages since all you need to to is to create a little file containing the rendering.

5.7.2.1 A partial for TEXT Custom Field - socialbrusselsid

The main file refers to a partial transforming the socialbrusselsid Custom Field into a block of several informations fetched from the external json file.

/templates/partials/embeds/socialbrussels.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step7-article-embed-socialbrussels)

%INCLUDE code/socialbrussels.html.php%

5.7.2.2 A partial for URL Custom Field - button with YouTube link

The main file refers to a partial transforming the youtube Custom Field into a button.

/templates/partials/embeds/url.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step7-article-embed-url)

%INCLUDE code/url.html.php%

5.7.2.3 A partial for URL Custom Field - YouTube video player

The main file refers to a partial transforming the youtube Custom Field into a customized video player.

/templates/partials/embeds/youtube.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step7-article-embed-youtube)

%INCLUDE code/youtube.html.php%

5.7.3 See the result

Go to https://pages.joomlacustomfields.org/step7 and see the result.

5.7.4 Not necessary any more to create plugins to get new CF Types

So as you can see: it is so easy to create a little file that will take care of transforming a basic native Text field into anything (video player, map, …) that you don’t necessarily need to build a plugin to create a new ‘type of Custom Field’.

5.8 Blog view using ext:joomla.model.articles and links with the Pages router

Pages ships with its own router.

This means you have direct control on the slug/url of your Articles.

5.8.1 Create the files

We will only need two files - one for the Blog View - one for the Article View

Just for fun, in the Article View we will import a partial (ie an external file).

5.8.1.1 The Blog View

In the folder /joomlatools-pages/pages/ create a file named

step8.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step8-blog)

 ---
@collection:
    model: ext:joomla.model.articles
    state:
        published: 1
        category: [organizations]
        sort: date
        order: asc
@process:
    filters: highlight
 ---

%INCLUDE code/step8.html.php%

5.8.1.2 The Article View

In the folder /joomlatools-pages/pages/ create a file named

step8article.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step8-article)

 ---
@collection:
    model: ext:joomla.model.articles
    state:
        published: 1
        category: [organizations]
        sort: date
        order: asc
@process:
    filters: highlight
 ---

%INCLUDE code/step8article.html.php%

5.8.1.3 A partial for TEXT Custom Field - socialbrusselsid

See above

5.8.2 See the result

Go to https://pages.joomlacustomfields.org/step8 and see the result.

5.8.3 Pointing to the Article view

In the Blog view, this is how we point to the file of the Article view (and make sure the slug will be as defined in the Article view):

<a href="<?= route('step8article', ['slug' => $article->slug]) ?>"><?= $article->title; ?></a>

5.8.4 Customizing the slug

In the Article view we define in the Frontmatter what the slug will be.

In this case, /blabla/article-alias:

@route: blabla/[:slug]

5.9 Blog view using ext:joomla.model.articles and links with the Pages router and partials

Last but not least, after having made a simple ‘override’ of the Blog view and of the Article view let us play further with the partials

5.9.1 Create the files

So far we have always has all our xxx.html.php files in the /joomlatools-pages/pages/ folder.

But actually you can of course create subfolders, subsubfolders etc. For more information, see https://github.com/joomlatools/joomlatools-pages/wiki/Folder-Structure#pages

Example: the following two options produce exactly the same result:

/joomlatools-pages/pages/test.html.php

/joomlatools-pages/pages/test/index.html.php

5.9.1.1 the Blog view

In the folder /joomlatools-pages/pages/step9/ create a file named

index.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step9-blog)

 ---
@collection:
    model: ext:joomla.model.articles
    state:
        published: 1
        category: [organizations]
        sort: date
        order: asc
@process:
    filters: highlight
 ---

%INCLUDE code/index.html.php%

5.9.1.2 the Blog partial

As can be seen in the index file, we import a file /templates/partials/myorganizations/liststep8.html Of course, the content of that file could have been placed directly in index.html.php. But putting it in the partials makes it reusable and easier to maintain.

So in the folder /joomlatools-pages/templates/partials/myorganizations create a file named

liststep9.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step9-blog-partial)

%INCLUDE code/liststep9.html.php%

5.9.1.3 the Article view with its router

As can be seen in the partial file, we refer to a file step9/org

In the folder joomlatools-pages/pages/step9/ create a file named

org.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step9-article)

 ---
@route: myslug/[:slug]
@collection:
    extend: articles
@process:
  filters: highlight
 ---

%INCLUDE code/org.html.php%

You can choose whatever you like to replace myslug, which will be visible in the url of Article “Organization 1” as follows:

https://pages.joomlacustomfields.org/myslug/organization-1

5.9.1.4 the partial of the Article view

Just to make things more fun, we create a partial which is imported in the article view.

As can be seen in the article view, we refer to a file /templates/partials/myorganizations/myarticle.html

In the folder /templates/partials/myorganizations/ create a file named

myarticle.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#step9-article-partial)

%INCLUDE code/myarticle.html.php%

5.9.1.5 A partial for the socialbrusselsid Custom Field

Same as in the previous step.

5.9.2 See the result

Go to https://pages.joomlacustomfields.org/step9 and see the result.

5.9.3 Could have been done with 2 files

Of course, what we have made here in 4 files could have been done in just 2 files like seen at the previous Step.

But the idea was to show that snippets of code can be imported and so reused.

And this facilitates the maintenance of the code of course.

5.10 Single Article

With Pages we can also directly call an Article by its ID or Alias.

See https://pages.joomlacustomfields.org/single

5.11 Other features

So I am now done with what I really wanted to share with your about Pages.

But Pages ships with many other features.

5.11.1 Decoration

Let us illustrate one of those features, namely the ability to ‘decorate’ (namely add content before/after/…) the component’s view, whatever it is: article, third-party extension, …

5.11.1.1 Create the file

In the folder /joomlatools-pages/pages/ create a file named

decoration.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#decoration)

 ---
@process: 
    decorate: true
 ---

%INCLUDE code/decoration.html.php%

5.11.1.2 See the result

Go to https://pages.joomlacustomfields.org/decoration and see the result.

5.11.1.3 How to name the decoration file

So actually if the URL of the page I want to decorate is MYSITE.COM/blabla then all I need to do to decorate it is to create a file named

blabla.html.php

and customize it.

5.11.2 Search

Another feature is Searching.

This can be done directly from the Frontmatter… or even via the url if you allow it in the Frontmatter.

For more information see https://github.com/joomlatools/joomlatools-pages/discussions/506

5.11.2.1 Create the file

In the folder /joomlatools-pages/pages/ create a file named

search.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#search)

 ---
@collection:
    model: ext:joomla.model.articles
    state:
        sort: title
    config:
        search: [title, alias, date]
 ---

%INCLUDE code/search.html.php%

5.11.2.2 See the result

Go to https://pages.joomlacustomfields.org/search and see the result.

5.11.3 Filtering

Another feature is Filtering.

This can be done via the Frontmatter, via the url of via the code.

Note: difference between Searching and Filtering: - when you search you start with nothing and you go find something - when you filter you start with everything and you remove items that don’t follow the constraints you provide

5.11.3.1 Create the file

In the folder /joomlatools-pages/pages/ create a file named

filter.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#filter)

 ---
@collection:
    model: ext:joomla.model.articles
    state:
        sort: title
 ---

%INCLUDE code/filter.html.php%

5.11.3.2 See the result

Go to https://pages.joomlacustomfields.org/filter and see the result.

5.11.4 Filtering directly on Custom Fields

Another feature is Filtering directly on Custom Fields.

This can be done directly within your Frontmatter… or even via the url.

5.11.4.1 Create the file

In the folder /joomlatools-pages/pages/ create a file named

filter-cf.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#filter-cf)

 ---
@collection:
    model: ext:joomla.model.articles
    state:
        sort: title
        category: [organizations]
 ---

%INCLUDE code/filter-cf.html.php%

5.11.4.2 See the result

Go to https://pages.joomlacustomfields.org/filter-cf and see the result.

5.11.5 Filter on Tags

You can actually filter on many many things.

Example here with Tags.

For more information, see https://github.com/joomlatools/joomlatools-pages/pull/363 > Filtering a collection for all possibilities

To see some examples see https://pages.joomlacustomfields.org/filter-tags

5.11.6 List of files

Pages is also able to dynamically display a list of files.

See our example on https://pages.joomlacustomfields.org/list

5.11.6.1 Create the file

In the folder /joomlatools-pages/pages/ create a file named

list.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#list)

%INCLUDE code/list.html.php%

5.11.6.2 See the result

Go to https://pages.joomlacustomfields.org/list and see the result.

5.11.7 Table of Content

See https://pages.joomlacustomfields.org/toc

5.11.8 Displaying content from various sources

local json: https://pages.joomlacustomfields.org/local
external json: https://pages.joomlacustomfields.org/ext-json
external json (advanced, with filters): https://pages.joomlacustomfields.org/ext-json-filter
external md: https://pages.joomlacustomfields.org/ext-md
Google Doc (see hereafter)
Google Sheet (see herafter)
Airtable (see hereafter)
…

5.11.9 GDoc

Yet another feature of Joomlatools Pages: it is possible to load any type of structured data file by file by url.

In this example, Pages will extract the content from a published Google Doc and inject it in the page.

For more information see https://github.com/joomlatools/joomlatools-pages/pull/264

5.11.9.1 Create the file

In the folder /joomlatools-pages/pages/ create a file named

gdoc.html.php

having the following content
(latest version on https://pages.joomlacustomfields.org/code#gdoc)

 ---
url: https://docs.google.com/document/d/e/2PACX-1vTK9nkPIsoq6ZJeVm86ns4BX7Q0bOcMHV5jYoaGlsREXUxt22kDW2zt0Zh3wSF9mquuVQKlPFyRw9HK/pub
 ---

%INCLUDE code/gdoc.html.php%

5.11.9.2 See the result

Go to https://pages.joomlacustomfields.org/gdoc and see the result.

5.11.10 GSheet

Go to https://pages.joomlacustomfields.org/gsheet + https://pages.joomlacustomfields.org/gsheet2 and see the result.

You can even filter on a Google Sheet 👍

5.11.11 Airtable

Go to https://pages.joomlacustomfields.org/airtable and see the result based on the corresponding code on https://pages.joomlacustomfields.org/code#airtable

To make this work you first need to add the Airtable Collection Model to JoomlaTools Pages by adding the following code to

/joomlatools-pages/extensions/pages/model/airtable.php

: https://github.com/joomlatools/joomlatools-pages/discussions/623

5.11.12 Sitemap

Pages is able to generate the sitemap automatically.

See https://pages.joomlacustomfields.org/sitemap.xml

5.11.13 Cache

Pages is super-powerful regarding caching.

See https://pages.joomlacustomfields.org/cache

5.11.14 Custom Collection

If you are a coder, you can even create your own collection (similar to ext:joomla.model.articles).

See https://pages.joomlacustomfields.org/custom-collection

5.11.15 Module

Pages is able to inject directly Modules in Joomla in any position.

See https://pages.joomlacustomfields.org/module

6 Recent features

which came along with Pages 0.21 in June 2021

6.1 ACL

Pages also allows to use Joomla’s ACL.

6.1.1 Via the Frontmatter

Simply add the following in the Frontmatter.

You can specify roles (called Access Levels in Joomla) and/or groups :

access:
    roles: [public]
    groups: [public, guest]

6.1.2 Via the code

Since version 0.21 Pages also allows to make it work directly via the code (for example if only a part of the page has restricted access).

And again it is super easy to use:

<h3>Only visible for hasRole or hasGroup</h3>
<? if(user()->hasGroup(['manager', 'administrator'], true)) : ?>
   <p>blabla</p>
<?  endif ?>
<? if(user()->hasRole('special')) : ?>
   <p>blabla</p>
<?  endif ?>

Go to https://pages.joomlacustomfields.org/acl and see the result.

6.2 Transform your site into a webservice

As you might know, Joomla!4 will ship with a Rest API.

But you don’t need to wait: with the next version (0.21) Pages will also allow you to transform your content into json:

Example: - blog version: https://www.joomlatools.com/blog/ - json version: https://www.joomlatools.com/blog.json

The corresponding code: - https://github.com/joomlatools/joomlatools-pages/blob/master/contrib/sites/blog/pages/blog/index.json.php

Pages supports indeed rendering to different machine readable formats: CSV, JSON, RSS, XML. Support for all of those formats is included, and you do not need to write any code. Just create a file with the right format, defined a collection in it and Pages will render the data from the collection in the specific format.

For more informatoin, see https://github.com/joomlatools/joomlatools-pages/discussions/675

See - https://pages.joomlacustomfields.org/webservice - https://pages.joomlacustomfields.org/all

6.3 Standalone

See

https://github.com/joomlatools/joomlatools-pages#standalone
“Pages is now also standalone. What does it imply (or not)?”
https://github.com/joomlatools/joomlatools-pages/discussions/750
(https://pages.joomlacustomfields.org/standalone)

7 Breaking News 2021 05 21

https://github.com/joomlatools/joomlatools-pages/pull/369 Template (layout and partial) location handling and importing got a major overhaul for 0.21, it’s now possible to distribute templates with extensions

This opens a whole world of flexibility, imagine creating a Pages extension that provides re-usable layouts and partials, together with additional template function and or helpers, all that nicely zipped in a phar for easy distribution.

Don’t know what phar format is? See https://en.wikipedia.org/wiki/PHAR_(file_format)

8 Y O U R next steps

Now time to go and play for yourself!

Curious to know even more? Have a look here to have examples of sites built with Joomlatools Pages: - https://github.com/joomlatools/joomlatools-pages/discussions/categories/show-and-tell - https://github.com/joomlatools/joomlatools-pages/tree/master/contrib/sites/blog
demo at Joomladay USA 2021 - https://github.com/johanjanssens/agrea.ph
complete ource code of a website made by Johan with Joomlatools Pages

9 Conclusion

First of all I would like to thank Johan Janssens for different reasons - he has always been very kind/patient with me asking questions (as a non-developer to a developer) 👍 - he has also improved a series of Pages features following our discussions (in particular regarding Custom Fields which is my favourite area in Joomla) 🎉

Second, I should make a confession - this presentation is already pretty long. My first goal was to cover 1 feature of Pages: Blog View ‘overrides’ and Article View ‘overrides’ - eventually, I ended up making tens of menu items to demo Pages - but actually I am pretty sure I only (dis)covered a fraction of Pages is or will be 😀

10 Get in touch

https://slides.woluweb.be

Any suggestion about this presentation ?
Please feel free to contact me. I’ll be happy to keep improving it:)

Marc Dechèvre | woluweb
+32 474 37 13 12 | +32 2 772 58 69

https://www.woluweb.be/contact

1 JoomlaDay USA

2 Introduction

2.1 Demo site

2.2 Joomlatools Pages - useful links

2.3 Joomlatools Pages - presentations by the author himself

2.4 Why this presentation

2.5 Focus on Pages to make overrides including Custom Fields and fetching external data

3 The initial setup

3.1 Install

3.2 Nothing new in the administration interface…

3.3 Updating Pages

3.3.1 Joomla Update Manager

3.3.2 What is the process to update Pages

3.4 Before starting: SEF

3.5 Before starting: URL Rewriting

3.6 Before starting: default configuration

3.7 Create the folder

3.8 Let’s create some content with Custom Fields

3.9 See the latest version of the source code on the website itself

4 Updating from 0.19 to 0.21

4.1 Release notes

4.2 My own checklist for upgrade

5 A step by step demo

5.1 Joomlatools Pages with HTML input

5.1.1 Create the file

5.1.2 See the result

5.1.3 Metadata

5.1.4 Creating a menu item - optional

5.1.5 Multilingual websites

5.2 Joomlatools Pages with MarkDown input

5.2.1 Create the file

5.2.2 See the result

5.3 Joomlatools Pages with PHP input

5.3.1 Create the file

5.3.2 See the result

5.3.3 Insert markdown directly in your PHP file

5.4 Joomlatools Pages with PHP input fetching external data

5.4.1 How does social.brussels work

5.4.2 Create the file

5.4.3 See the result

5.4.4 Caching

5.5 Blog view using table=content from database

5.5.1 Create the file

5.5.2 See the result

5.5.3 Images options are stored in JSON format in Joomla

5.6 Blog view using ext:joomla.model.articles and links with the Joomla router

5.6.1 Install Joomlatools Pages’ Joomla Extensions

5.6.2 Create the file

5.6.3 See the result

5.6.4 Filtering and sorting

5.6.5 Some customized styling with CSS Grid and/or Flexbox

5.6.6 Using the Joomla Router

5.6.7 A direct access to the image path/name

5.6.8 Category title/alias

5.6.9 introtext/fulltext

5.6.10 Custom Fields

5.6.11 External JSON

5.6.12 More generally, retrieving data from a SAAS service

5.6.13 Comparison with a typical native Joomla override

5.7 Blog view using ext:joomla.model.articles and links with the Joomla router - and partials for Custom Fields

5.7.1 Create the file

5.7.2 Create the partials for the Custom Fields

5.7.2.1 A partial for TEXT Custom Field - socialbrusselsid

5.7.2.2 A partial for URL Custom Field - button with YouTube link

5.7.2.3 A partial for URL Custom Field - YouTube video player

5.7.3 See the result

5.7.4 Not necessary any more to create plugins to get new CF Types

5.8 Blog view using ext:joomla.model.articles and links with the Pages router

5.8.1 Create the files

5.8.1.1 The Blog View

5.8.1.2 The Article View

5.8.1.3 A partial for TEXT Custom Field - socialbrusselsid

5.8.2 See the result

5.8.3 Pointing to the Article view

5.8.4 Customizing the slug

5.9 Blog view using ext:joomla.model.articles and links with the Pages router and partials

5.9.1 Create the files

5.9.1.1 the Blog view

5.9.1.2 the Blog partial

5.9.1.3 the Article view with its router