Development and FTP

How GRAV stores content

For a full description of GRAV, see GRAV docs. This section is meant to give you a very brief taste of the environment.

The content is written in Markdown (MD) - a language that is mostly text, but includes special syntax for images and links and formatting. MD renders easily into HTML but is much easier to write and to read.

The database consists of files in a structure in the file system.

A user or developer should change only those files that are inside the directory pnhb/user. Most interesting are the subdirectories pages, themes and config.

Each web page is a directory in the pnhb/pages and has the name of the page e.g. "home". The name must be entirely lower case with minus sign in place of spaces - in GRAVspeak this is a valid slugname - very important.

Each page has a type (one of the standard, listing or modular types), which determines the template that is used to render the page in HTML. Each page is a directory containing media files and an MD file containing the textual content written in MD. This file is named .md. The type defines the template that will be used to display the page content and media. For example, text.md is rendered by the template text.html.twig.

The main sections of the PNHB site are all of type modular and the files containing the content are all called modular.md. The name of the directory is the name of the page. Modular pages may containg other pages.

The directory for a page may contain other files, such as images that are to be displayed on the page. Children of the page are directories inside the page directory.

Each MD file contains a header section, called "frontmatter" in GRAVspeak. The items in the frontmatter look like name: value

For example
title: Music Making

Title is mandatory. Pages other than the menu pages must have "visible: false " to prevent them from displaying in the top menu.

Other items may be needed in frontmatter according to context. See GRAV docs.

The PNHB theme uses additional items of frontmatter. In particular, the music making/Conductors page defines the appearance and functionality of the page. Blog items (archive) require several other items in frontmatter to guide the processing.

The templates are rendered by TWIG files. TWIG is an open source template engine used by GRAV. It provides a way to generate HTML with code that combines standard programming logic and HTML Each type of page has its own template, and the name of the template is "page type".html.twig.

There are examples in our website that display pages in two colums or with a sidebar.

The GRAV templates are in pnhb/user/themes/templates/Quark, and customisations and additions are in pnhb/user/themes/templates/pnhbtheme.

Relationship to admin

For development, it is often easier to work directly in the file system using a text file editor such as atom. For a user, it is easier to work in the admin.

When pages are created in admin, the system composes a slug name for the page by replacing blanks in the Title with minus signs and putting all the letters lower case.. The options tab allows the user to set many options: these correspond to items in the frontmatter. The advanced tab allows the user to choose template type, which determines the filename of the content file and also how to display the page. The expert tab allows the user to work with the frontmatter.

When the page template is "item", an extra button "Archive Item" appears in the admin to allow the user to enter header information (frontmatter) needed for blog processing. When the page template is "text-item", a member of a "twosides" page a "Text Item" button appears allowing the user to choose which side the page displays on. These two tricks are accomplished by two "blueprints" in PNHBtheme.

Working in admin and the file system at the same time is extremely dangerous.

Developing on the server

The admin interface accesses only website content (i.e. pages), not the pnhbtheme. Filezilla can be used to edit and replace TWIG files on the server, but editing and testing on the server is rather dangerous. Changes that are more than trivial should not be made on the server.

Development at home

To develop locally, download an Apache server: MAMP for MAC, WAMP for Windows or LAMP for Linux. These simulate a client server relationship inside one computer. Start the servers.

Next, use FTP to download the website from the server to the htdocs folder of WAMP or MAMP. Downloading the entire site is not recommended on account of its size. Better is to download the latest version of GRAV and then use FTP to replace the "user" directory and the PNHBtheme. The admin interface on the server can show which plugins are needed. The GRAV manual explains how to install the admin, and the admin interface conveniently installs plugins.

Be very careful to use no capital letters in filenames because they are treated differently by MAMP and some servers.

Make your changes and test locally.

Then upload the users directory by FTP.