Posts

Grav 1.6 Released

Grav is an open source flat-file CMS that we use for client documentation and server healthchecks. Since it requires no calls to a database and has baked in caching, page load speed is very fast and offers a simple search that will quickly search your content for matching strings. We chose Grav as we thought it would be an ideal solution for simple, static, searchable pages such as those used for flow documentation and healthchecks.

Recently, Grav 1.6 was released on 4/11/2019. It is being touted as their “biggest release since Grav 1.0” and there are many new features to potentially take advantage of. This latest update to Grav 1.6 requires upgrading PHP to 7.1.3+ (7.3+ is preferred for optimal performance) and also updates Admin Panel to v1.9 and Form/Login/Email plugins to v3.0.

Full article: (https://getgrav.org/blog/grav-1.6-released)

INSTALLATION

Grav comes with a built-in command-line interface (CLI) which can be found at bin/grav

The simplest way to upgrade would be through CLI as upgrading through the admin panel could result in some error messages.

To upgrade to Grav 1.6 and update all plugins, open a terminal and once in the root directory of the Grav site use:

php bin/gpm self-upgrade (Windows) OR bin/gpm self-upgrade (Mac)

followed by

php bin/gpm update (Windows) OR bin/gpm update (Mac)



NEW FEATURES 

BACKUPS

There is a new backups tab in the Tools section. This can integrate with the new scheduler to create scheduled backups. We now have the ability to create multiple backup profiles each with their own set of files. In our case, this will be useful for creating and keeping track of backups when updating documentation and healthchecks.

 

SCHEDULER

A new scheduler tab is in Tools section of the Admin panel. It allows for scheduling tasks such as cache clear, backups, synchronization, search indexing, etc.

LOGS

This is a new CLI command that can be used to display Grav log entries. In addition, the logs are accessible from the new Logs tab in the Tools section of the Admin panel. This new tool should help us in the future with troubleshooting.

REPORTS

The Reports feature is accessible from a tab in the Tools section of the Admin panel. This section provides information to the site administrator on things such as configuration, server issues, and content issues and can help with troubleshooting.

ASSET MANAGER

One of the most important changes in Grav 1.6 was implemented on the asset manager. Previously, there was an issue with plugins that had their own CSS and JS assets in which the content was rendered in the order encountered and once rendered, could not be modified. The asset manager was rewritten as part of this update and basically solves this issue with custom plugin CSS and JS.

For complete details, please visit the Asset Manager documentation:
(https://learn.getgrav.org/16/themes/asset-manager)

Overview of Flow Documentation Sections

Grav is an open source flat-file CMS that we use for client documentation.

Requirements:

  1. Web Server (Apache, Nginx, LiteSpeed, Lightly, IIS, etc.)
  2. PHP 5.5.9 or higher

Advantages of using a Grav CMS for documentation:

  1. SEARCH bar: Can search entire collection of documentations for a search term instead of going through each doc file individually
  2. Not reliant on database: Flat-file content management system means that the data is stored in folders rather than a database = fast loading
  3. Easy to maintain since all data in local folders
  4. Simple HTML format written with Markdown syntax (http://nogalis.com/docr/how-to-use-docr to learn more about Markdown)
  5. Many useful plugins freely available (http://www.nogalis.com/2018/07/27/grav-a-modern-flat-file-cms for more information on plugins)
  6. User authentication and custom user privileges

Documentation Sections


  1. Introduction – Screenshot of the IPA flow and a short description about what it does
  2. General Data Flow – Box diagram showing step-by-step what is happening in the flow. Also accompanied by a paragraph explanation
  3. Components Table – A table that lists all input/output files, databases, scripts, triggers, jobs, and configuration variables
  4. Dependencies – The files, triggers, jobs, or SQL/server connections required for the flow to function
  5. Scheduling and Triggers – How/when the flow gets triggered
  6. Recovery – This section provides instructions on how to manually execute the steps of the flow if it fails. Each step here represents a box in the General Data Flow box diagram.
  7. Archiving – Table showing archived files and their archived locations
  8. Notifications – Details of the notifications sent by the flow
  9. Troubleshooting – General tips for troubleshooting
  10. Maintenance – Maintenance needed by the flow (usually involves cleanup of archived/done files)
  11. Security – Overview of user permissions and connection credentials needed for the flow
  12. Key Contacts – The person to contact for questions about the flow/documentation
  13. Related Files – File uploads related to the flow (these are able to be viewed/downloaded from the page)

For full examples, please visit http://nogalis.com/docr/demo_documentation

Using GRAV Group-Based Permissions

Upon login, we wanted to present users with just the directories and pages they had access to.
In order to do this, we used GRAV group-based permissions.

First we must modify sidebar.html.twig to display the folders/pages only if the user’s group matches the client in the folder/page header.

Using GRAV admin panel Editor plugin, navigate to sidebar.html.twig and insert the boxed line below:

 

The next step is to create a group and assign permissions to the group. Once this group is made, users can be assigned to the group and will inherit the permissions. This will make the pages only viewable to users with this custom permission. This prevents random users from going to the URL to view the page.

Add a user/config/groups.yaml file with something like this:

cda:

  readableName: ‘CDA’

  description: ‘The group of premium members’

  access:

    site:

      login: true

      cda: true

The user given access must be given group assignment and have site.login set to YES:

 

Once this is done, we can make pages/folders just for this group by creating new folder/page and going to “Expert” section.

For folder/directories, place this in the Expert Frontmatter:

taxonomy:

    client:

        – CDA

For pages, place this in the Expert Frontmatter:

taxonomy:

    client:

        – CDA

access:

    site.cda: true

Creating an Email Contact Form in Grav/Docr

Here is a step-by-step guide for creating an email contact form in Grav/Docr

 

  1. Install “Email” Plugin if not already installed. The simplest way to do this is through the admin panel:

  1. Rename the Markdown file to form.md (instead of chapter.md for example) and include this code snippet (or similar) in the YAML portion at the top of the page below “title”:

Snippet:

form:

name: contact

fields:

–   name: name

label: Name

placeholder: Enter your name

autocomplete: on

type: text

validate:

required: true

 

–   name: email

label: Email

placeholder: Enter your email address

type: email

validate:

rule: email

required: true

 

–   name: message

label: Message

size: long

placeholder: Enter your message

type: textarea

validate:

required: true

 

buttons:

–   type: submit

value: Submit

–   type: reset

value: Reset

 

process:

–   email:

from: “{{ form.value.email }}”

to: “{{ config.plugins.email.to }}”

subject: “[Healthcheck Contact Form] {{ form.value.name|e }}”

body: “{% include ‘forms/data.html.twig’ %}”

–   save:

fileprefix: contact-

dateformat: Ymd-His-u

extension: txt

body: “{% include ‘forms/data.txt.twig’ %}”

–   message: Thank you for getting in touch regarding your healthcheck report!

–   display: thankyou

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Full example of form.md YAML:

We can place any page content below this YAML portion. Our contact form will show up on the bottom of the page after all page content.

  1. Inside the page folder (in which the form.md is placed), create a subfolder named “thankyou” with a file named “formdata.md” with this snippet:

title: Email sent

cache_enable: false

process:

twig: true

 

## Email sent successfully!

This will result in a “Email sent” success screen when the user clicks submit on the contact form:

  1. Final Step – Configuring Email Plugin settings. Full email configuration documentation can be found here (https://github.com/getgrav/grav-plugin-email/blob/develop/README.md)

 

Set-up for Google SMTP (Gmail)

  1. Enable IMAP in your Gmail by going to Settings -> Forwarding and POP/IMAP -> IMAP Access

  1. Enable “Less secure apps” in your user account settings (https://myaccount.google.com/lesssecureapps)

  1. From Admin dashboard, go to Plugin -> Email to configure settings:

Fill out configuration:

 

 

 

 

Grav – A Modern Flat-File CMS

09Grav is an open source flat-file CMS that we have started experimenting with for client documentation. Since it requires no database, it is a simple and great alternative to providing documentation without using separate .doc files. The search feature is especially nice for when you want to search through all documentation.

Demo site for GRAV rtfm skeleton: https://demo.getgrav.org/rtfm-skeleton/basics/overview

 

Here are some things we’ve learned along the way:

Installing Plugins:

Admin Panel and Editor are very important plugins to have.

Admin Panel creates an admin dashboard at URL sitename/admin. From here, you can install other plugins, edit pages, manage users, and change configuration settings.

Install by going to your GRAV root folder in a terminal and calling your php.exe with “bin/gpm install admin”


In our case, the php.exe used was within my xampp folder.

Editor is a very useful plugin that provides a “Edit” section in the admin sidebar that allows any authorized users to modify any PHP, Javascript, CSS, Twig, Markdown, and YAML files. This allows for easy editing of any file directly from the admin dashboard!

 

Install by going to your GRAV root folder in a terminal and calling your php.exe with “bin/gpm install editor”

 

CSS:
To modify the css, access user/themes/learn2/css-compiled/theme.css

In this case, we modified the file to left align all my elements by changing the #chapter ID since my page files are chapter.md. This can be achieved by changing these four “center” properties to “left”

(Before) Center aligned:

(After) Left aligned:

Another case is when we modified sidebar font-size by modifying #sidebar ul.topics > li > a in css-compiled/theme.css

Sidebar Logo (top left):
To change the sidebar logo from default GRAV image, access user/themes/learn2/templates/partials/logo.html.twig

To change the admin sidebar logo from default GRAV image, access: user/plugins/admin/themes/grav/templates/partials/logo.html.twig

Replace what is in the file with the SVG code of the image. This was done by converting a PNG to SVG using https://www.pngtosvg.com/

Example of what SVG looks like:

Sidebar:

To modify the sidebar on the left, access user\themes\learn2\templates\partials\sidebar.html.twig
In this case, we wanted to remove the check marks indicating that we had visited that page along with the “Clear History” button on the bottom of the sidebar.

This can be done by removing the relevant lines in the file.

Where to keep your images
We ran into an issue where the images in the images folder would disappear upon caching. This was due to the images folder being in the wrong place. Even though there is a default “images” folder in the root folder, this is not the place to store your images.

Per the official Grav documentation, the images folder should be placed within user/pages:

Do not put images in here:

Instead put them in user/pages/images as depicted here:

On the pages themselves (.md files), link to the images by going up one folder and accessing the images folder with the format (..\images\imagename.png):

 

Be careful when using underscores (“_”) in the .md file
In markdown, surrounding a word with underscores will result in italicizing that word. This could become an issue since many files we deal with use underscores to separate timestamps from the file name.

Take this line for example:

Based on that code, we want the page to look like this:

Instead we get an unwanted italicized word and the removal of an underscore between CODE and RELATION:

The problem can be fixed by “escaping” the underscore by putting a backslash in front of it. Keep in mind that even if we were to escape the underscore between CODE and RELATION, the Markdown language would then try to find the next underscore and would italicize all words in between the underscores (marked in green).

This code:

Will use the underscores boxed in green to italicize all in between them (and removes the underscore in front of “configuration”):

To resolve this, make sure to escape all underscores:

Grav File Uploads

In admin panel, we can add users with these 2 permissions (admin.login and admin.pages):

This creates a user who can log into the admin panel and can edit pages.

When these users go to edit the pages, there is a section that allows media uploads.

“Edit page” page:

These users can also access the “edit page” page through the edit links on the site itself:

These are the files types supported by Grav:

(Although csv is not listed here, it was able to be added as a xml media type and verified to be working)

Once you upload the file and save the page, anyone who has access to this “edit page” page can download/view the file by clicking on the eye “View” icon:

The uploaded files go into the same directory as the markdown page itself.

Clicking the + “Insert” icon will insert the file in the page like so:

Which looks like this on the page:


Clicking it displays the file on the page for .txt, .pdf, .json and .csv. Downloads it immediately for .docx files (these are the 5 I tested):

Issue: When clicking the “View” eye icon for .txt files, there is an error regarding permissions. (It works fine when actually inserted into the page and clicked on from there)

Clearing Cache

CLI commands:
cd ~/webroot/my-grav-project

bin/grav clear-cache