Skip to content

Getting Started

Jump to bottom Edit New page
Johan Janssens edited this page Apr 19, 2020 · 20 revisions

Getting started is very easy, first install the component in Joomla following the installation guide and then you can start creating your first page.

Pages, not a static site generator!

Pages is not a static site generator (SSG), it's a page generator for Joomla inspired by the ideas and concepts of flat-file CMS systems like Grav and Statamic and static site generators like Jekyll, Hugo, Gatsby, etc.

An SSG is a compromise between using a hand-coded static site and a full CMS. You generate an HTML-only website using raw data (such as Markdown files) and templates. The resulting build is transferred to your live server.

SSG have lots of drawbacks Pages implements some of the concepts found in SSG's, for example the collections concept of Jekyll or the use of YAML based frontmatter but without any of the drawbacks.

That doesn't make Pages a static site generator. The big difference between an SSG and Pages is that Pages only dynamically re-generates a page when its layout or content has changed.

  • In Joomla a page is generated each time it's requested, Joomla doesn't cache the page, which means it needs to generate it on each request.

  • In an SSG all pages for the whole site are generated each time the site is being built. Ones build all pages making up the site are uploaded to a web server.

Pages however works in a dynamic, smart and lazy way it re-generates cached pages only if the layout, or the data on the page as changed. This means pages are re-generated less frequent the using a SSG and there are no additional drawbacks or complexity in needing to re-upload it to a server. Its just works!

How does Pages work?

At the core of Pages everything evolves around data. Pages offers support for 4 different data sources:

  1. Filesystem
  2. Database
  3. Webservice
  4. PHP (Joomla Component)

Pages data layer can interface with any other component in 3 different ways:

  • By directly getting data out of the database tables from those components
  • By creating a database view that joins different database tables
  • By creating a custom collection (using PHP code) to interface with the API of a component.

The build in webservice layer offers out of the box support for JSONAPI v1 with full CRUD support making it very easy to connect to external applications, or even making a pages setup into a Headless CMS.

What can Pages do?

Pages can do a lot, with more functionality and features being added every new release. Here is an overview of some of the things it can do already.

1. Creating a custom page (without using an article)

Instead of using the Joomla article manager to create a page you can create the page in a file using either markdown or html, and Pages will render it nicely in your Joomla template on your site.

In your page there is a header block that is called the frontmatter in which you can define all sorts of settings for the page, like the title, meta description, open graph tags: https://github.com/joomlatools/joomlatools-pages/wiki/Page

2. Including a existing (remote) html page

Sometimes you want to be able to include custom html in your site. This is very hard to do in Joomla right now and a problem that often comes back. In Pages this is very simple: https://github.com/joomlatools/joomlatools-pages/wiki/Page-Examples#html-page

But that is not all, Pages takes this a step further and you can now include a page by it's url. For example, you can include parts of a published Google document in a site: https://github.com/joomlatools/joomlatools-pages/pull/264#example

3. Working with a collection of data

Often you don't just want to render an individual page, but you want to be able to show a list of data coming from a database. Pages has a collection mechanism for that. Defining a collection is very easy: https://github.com/joomlatools/joomlatools-pages/wiki/Collection#frontmatter

Pages can get data from different sources: other pages, or filesystem, database, webservice. And you can create your own custom collections using the API. So you can easily integrate it with any third party extension for example.

4. Decorating an existing component

Site developers and integrators often need to put blocks of content around a component. Right now we use the modules for that, but that is often very hard. You need a module position in the right location, create the module, assign it, etc etc.

Pages solves this by offering a decorator, https://github.com/joomlatools/joomlatools-pages/wiki/Decoration Basically this works as a wrapper, allowing you to add custom content around any component/menu item without needing modules

5. Modules on steroids

Modules are great tools though, but you have limited control over them. With Pages further improves modules API in Joomla to allow you to:

  • inject content into any module position by creating a virtual module
  • instantiate an existing module on the fly
  • define your own module positions

More info https://github.com/joomlatools/joomlatools-pages/wiki/Modules

6. Creating forms

Often you want to create a simple form on your site, for example a contact form. Pages makes that super simple, no code required just a form definition: https://github.com/joomlatools/joomlatools-pages/issues/168 with spam filtering included.

Forms submissions can be sent through email, stored in a .csv or .json file, or they can be sent to a webservice using a webhook, all of this can be configured through the frontmatter.

7. Going more advanced

Previous: Roadmap | Next: Installation

Got a question or need help? We have a forum on Github Discussions where you can get in touch with us.

Clone this wiki locally