Premium Site Toolbox Site Toolbox Documentation

Site Toolbox Documentation

Learn how to use the plugins in Site Toolbox

Found an issue or a problem that you can't find an answer for? Create an issue in our Premium Issue Tracker.

Before you start

Before you can install a Premium Plugin, you are required to have the License Manager plugin installed. It is a free plugin available in GPM and can be installed like any other through the Plugin section of the admin plugin, or via command line.

$ bin/gpm install license-manager

Installation

First ensure you are running the latest version of Grav 1.7 (-f forces a refresh of the GPM index).

$ bin/gpm selfupgrade -f

These plugins are available via GPM, and you can install them in one go via the CLI:

$ bin/gpm install svg-icons warm-cache zapier-rss

The Warm Cache plugin makes use of the sitemap plugin to function properly, so allow installation when prompted.

You can also install the theme via the Plugins section in the admin plugin.

SVG Icons

The SVG Icons Plugin is an extension for Grav CMS that provides over 8000 SVG icons with various sets of SVG icons that can be used in your content and Twig templates by using either a unique shortcode (for content) or Twig function (for templates).

This package currently contains 6 primary SVG icon sets:

Tabler Icons (2664) → [DEFAULT] Developed by Csaba Kissi (v1.95.1)
Hero Icons (292) → Developed by Steve Schoger with both outline and solid variants (v2.0.11)
Simple Icon Brands (2340) → Over 2100 popular brand icons (v7.11.0)
Social Icons (6) → A few basic consistent social networking icons (v1.0)
NEW Bootstrap Icons (1811) → Over 1500 icons (v1.9.1)
NEW Iconsax icons (1792) → outline and bold variants (v1.0)

Configuration

Plugin status → Will enable or disable the entire plugin.

Shortcode for Content

Valid icon sets include:

tabler
heroicons\solid
heroicons\outline
brands
bootstrap
iconsax\bold
iconsax\outline
social

When you need to use an SVG icon in your content, you can use the shortcode. Here are some examples:

[svg-icon="alien" /]

This is the quickest most basic approach. This will use the default tabler SVG icon set. Note, no extension is required for the icon name as they are all SVGs.

[svg-icon=award set="tabler" /]

Another example with an explicit set defined and no trailing slash.

[svg-icon icon="atom" /]

The more commonly used approach with icon specifically defined.

[svg-icon icon="battery-4" set="tabler" /]

Icon and set defined, but no trailing slash.

[svg-icon icon="badge-check" class="w-12" set="heroicons|solid" /]

Example from HeroIcons / Solid and a TailwindCSS class of w-12 to specify a width.

[svg-icon icon="shield-check" class="w-12 h-12 text-blue-600" /]

Example of some popular brands from Simple Icons.

[svg-icon icon="grav" class="w-8" set="brands" /]
[svg-icon icon="apple" class="w-8" set="brands" /]
[svg-icon icon="ferrari" class="w-8" set="brands" /]
[svg-icon icon="spacex" class="w-8" set="brands" /]

More complex example with TailwindCSS classes for width/height and also a color.

[svg-icon icon="shield-check" class="w-24 h-24 text-red-500 stroke-1 transform rotate-90" /]

Just showing off now with vector stroke modified and a custom rotation.

Twig Function for Templates

Using the plugin directly from Twig templates is a little different. There's an svg_icon() twig function available to use but it only takes a path to the SVG icon, plus classes. Some examples include:

{{ svg_icon('tabler/plus.svg', 'h-6 w-6 text-gray-600 stroke-3/2')|raw }}

This is using the tabler/plus.svg icon with various TailwindCS classes for width, height, color and stroke. Note the use of |raw filter at the end. This is important as the output is the raw inline HTML of the SVG.

{{ svg_icon('heroicons/outline/star.svg', 'current-color h-8 w-8')|raw }}

Here we are using the star.svg from HeroIcons in Outline style. The classes use the current color.

Custom Icons

If you want to add your own icons, you should clean them up to ensure any hardcoded colors are removed and currentColor is used instead. For example, search and replace:

stroke=\"#(?:[0-9a-fA-F]{3}){1,2}\"
stroke="currentColor"

fill=\"#(?:[0-9a-fA-F]{3}){1,2}\"
fill="currentColor"

Warm Cache

Configuration

Plugin status → Will enable or disable the entire plugin. When disabled, no tray icon will display.
Sitemap URL → This defaults to the value set in the Sitemap plugin
Enable Quicktray → Enables or disables the quicktray icon to trigger an Ajax-powered warm-cache call of your site.
Quicktray Icon → Allows you to override the default tachometer icon with a different Fontawesome icon
onCacheClear Events → When enabled, Clearing the Cache either via Admin or CLI will then trigger a warm-cache call.
Show Count in Results → By default the number of pages that were warmed shows in the results of the call. This can be disabled.
Log Results → The results of the cache clear can be logged for debugging errors.
User Agent → This is the string set by the crawler that hits each page. You can configure this or use it to filter out these cache-warming calls from your analytics data.

Usage

Admin Plugin

To use warm-cache plugin in the admin, you simply click the icon in the quicktray. This is configurable but is a Tachometer by default. You should see a 'toast' message in the top-right corner with a message after completion.

Quick Try

CLI Command

The warm-cache plugin also includes a useful CLI command that also be scripted or used via a cron-job or scheduler as needed.

To use this from the CLI you need to call the command pass the URL of the sitemap. For example:

bin/plugin warm-cache warm https://mysite.com/sitemap.json

Interestingly you can run this from any Grav instance that has warm-cache installed, and warm the cache of any other Grav server that has the sitemap plugin installed. This is because warm-cache simply iterates over the entries in the sitemap and causes Grav to respond with the page requested, hence forcing Grav to warm the cache for that page.

Scripted

The simplest way to script the warm cache process for a site we have in /Useres/joe/workspace/grav-example-site is to create a shell script that runs the CLI command. In this example, we'll create /Users/joe/bin/warm-cache.sh file with the contents:

#!/bin/sh
cd /Users/joe/workspace/grav-example-site
bin/plugin warm-cache warm https://localhost/grav-example-site/sitemap.json

Then we ensure this warm-cache.sh is executable via:

chmod +x warm-cache.sh

Assuming the bin/ folder is in Joe's path, then anytime we're in the CLI we can simply run:

warm-cache.sh

Cron Job

With the warm-cache.sh script created you can run this daily by running this file via crontab. Edit your crontab file with crontab -e then add the following line:

* 3 * * * /Users/joe/bin/warm-cache.sh

Grav Scheduler

To use the Grav Scheduler, a simple approach is to first creat a warm-cache.sh script as provided above, then set that up in the scheduler in the "Custom Schedular Jobs"

First make sure your scheduler is working, then you can add a custom entry in your user/config/scheduler.yaml configuration file:

...
custom_jobs:
  warm-cache:
    command: /Users/joe/bin/warm-cache.sh
    args: null
    at: '* 3 * * *'
    output: logs/warm-cache.log
    output_mode: append
    email: null

or via Admin:

Warm Cache Scheduler

This will run the warm-cache script every day at 3am and store the output in Grav's logs/warm-cache.log file by appending the output each time.

Zapier RSS

Configuration

Before configuring this plugin, you should copy the user/plugins/zapier-rss/zapier-rss.yaml to user/config/plugins/zapier-rss.yaml and only edit that copy.

Here is the default configuration and an explanation of available options:

enabled: true                                                 # plugin enabled
active: false                                                 # default zapier state
template: zapier-feed.zrss.twig                               # TWIG template to use
description: For Zapier RSS integration with other services   # Description
limit: 20                                                     # Number of items to include
length: 1000                                                  # Number of chars per item
order:                                                        # Ordering of items
  by: date
  dir: desc

Note that if you use the Admin Plugin, a file with your configuration named zapier-rss.yaml will be saved in the user/config/plugins/-folder once the configuration is saved in the Admin.

Usage

Simply install the plugin and then the URL you would use to integrate with would be your existing blog page with the new .zrss extension appended to it:

http://yoursite.com/your/blog.zrss

This ensures the feed uses the custom templates/zapier-feed.zrss.twig file to process. To modify this Twig file, simply copy it into your theme or plugin's templates/ folder and modify as you like.

You can override the regular collection properties, or any of the other config options at the blog level, by modifying the frontmatter of the page that contains the collection. For example:

---
title: 'My Blog'
header_image: custom_header.jpg
content:
    items:
        - [email protected]
    order:
        by: date
        dir: desc
    limit: 8

zapier-rss:
    active: true
    description: 'My Custom Zapier ZRSS Feed'
    template: 'zapier-custom-feed.rss.twig'
    limit: 20
    length: 500
---

You can also control if a particular item in the collection should not be included in this feed by skipping it:

---
title: 'My Blog Post"

zapier-rss:
    skip: true
---