DOCSEARCHbyAlgolia
Submit Docs

Gantry 5 Documentation

repository·develop·Indexed 22 days ago

https://github.com/gantry/gantry5

A flexible theming framework for WordPress, Joomla, and Grav. Gantry 5 uses a system of Outlines, Particles, and Atoms to provide a configurable visual layout engine. It includes a JS and CSS bundler, a dedicated administrator for theme configuration, and support for Gulp-based development environments. Compatible with PHP 8.1.0 through 8.3.x.

Tokens
24K
Snippets
62
Records
101
Agent score
76%

What's inside Gantry 5

  1. Platform compatibility for Gantry Themes

    develop

    Gantry 5 themes are available for the following platforms with these minimum requirements:

    • Grav: Requires Grav 1.7.25 or higher.
    • Joomla: Requires Joomla 5.0 or higher.
    • WordPress: Requires WordPress 5.2 or higher.

  2. Understand Gantry 5 terminology: Outlines, Particles, and Atoms

    develop

    Gantry 5 uses specific terms to describe its core components:

    • Outline: A configurable style used in one or more areas of your site. It acts as the container for a page's style, settings, and layout.
    • Particle: A small block of data used on the front end, similar to a widget or module, but configured directly within the Gantry 5 Administrator.
    • Atom: A specialized type of Particle used for non-rendered data, such as custom JavaScript, CSS, or analytics scripts.

  3. Why Gantry 5 requires 'unsafe-eval' in the Admin Area

    develop

    Gantry 5's administration interface relies on JavaScript bundling tools (such as Browserify) that utilize eval() or new Function() constructs. Additionally, the dynamic nature of the admin UI requires runtime code evaluation for several features.

    Required functionality enabled by unsafe-eval:

    • Cache clearing operations
    • Editing functionality
    • JSON parsing and handling
    • Various admin UI interactions

  4. Core concepts of the Gantry 5 Framework

    develop

    Gantry 5 is a framework designed for rapid theme development using a modular approach. Key architectural components include:

    • Nucleus Grid System: A responsive layout system built from scratch using Flexbox, integrated with the Layout Manager to generate CSS classes.
    • Particles System: A system for creating, configuring, and managing content blocks. Particles can be adjusted at multiple levels, from global settings down to individual block instances.
    • Layout Manager: A drag-and-drop interface used to set up page layouts, place content blocks (Particles), and resize them without editing text files.
    • Outline System: Manages theme overrides, allowing you to create and assign specific Layouts, Settings, and Styles.
    • YAML-driven Configuration: Uses YAML for human-readable data serialization to define blueprints for back-end configuration options.
    • Twig Templating: Utilizes Twig and Timber for dynamic theme rendering.

  5. Re-compile CSS using scss.sh

    develop

    Every Gantry platform (Grav, Joomla, and WordPress) includes an scss.sh script. This script can be run in the background to automatically re-compile SCSS into CSS whenever changes are detected in your theme files.

    ./scss.sh

  6. Configure CSP requirements for the Gantry 5 Admin Area

    develop

    To ensure the Gantry 5 administrator area functions correctly, your Content Security Policy (CSP) must allow 'unsafe-eval' within the script-src directive. This is required for core administrative tasks including cache clearing, editing functionality, JSON parsing, and various UI interactions.

    It is highly recommended to use a Split CSP Policy approach: apply a strict policy to your public-facing frontend, but apply a more permissive policy (including unsafe-eval) specifically to the administrator sections of your site.

    Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;

  7. Install Gantry 5 on WordPress

    develop

    You can install the Gantry 5 Framework plugin on WordPress using either the built-in plugin installer or via FTP.

    Using WordPress Plugin Installer

    1. Navigate to Admin Dashboard > Plugins > Add New.
    2. Select Upload from the top of the list.
    3. Browse to your Gantry 5 plugin .zip package.
    4. Activate the plugin in Admin Dashboard > Plugins.

    Using FTP

    1. Extract the plugin .zip package locally.
    2. Upload the extracted directory to your WordPress installation at wp-content/plugins/.
    3. Activate the plugin in the Admin Dashboard > Plugins.

    Note: The Gantry 5 Framework plugin does not include a default theme. To use Gantry, you must also download and install a Gantry-compatible theme (such as the Gantry Default theme) from the official Gantry Framework site.

  8. Set up a Gantry 5 development environment with Gulp

    develop

    To bundle JavaScript and compile SCSS with automatic recompilation, you must use the Gantry 5 source code (cloned or downloaded from GitHub) rather than a pre-packaged version.

    Prerequisites

    Installation Steps

    1. Navigate to the root of the Gantry 5 project.
    2. Install JS module dependencies: npm install.
    3. Install Gulp globally: sudo npm install gulp --global.
    4. (Optional) To perform a clean installation or reset all modules, run: npm run build-assets. This removes all node_modules folders and re-runs npm install across all project folders.
    5. (Alternative) To update modules without removing existing node_modules folders, use: gulp -up.
    # Install dependencies
npm install

# Install Gulp globally
sudo npm install gulp --global

# Clean reinstall of all modules
npm run build-assets

# Quick update of modules
gulp -up

  9. Configure an offline maintenance page in Grav

    develop

    In Gantry 5 for Grav, you can define a custom offline maintenance page using a Markdown file with YAML front matter. This allows you to control the HTTP response code, prevent search engine indexing, and specify a custom Gantry outline to be used when the site is down.

    Key configuration options include:

    • robots: Set to noindex,nofollow to prevent search engines from indexing the maintenance page.
    • http_response_code: Set to 503 (Service Unavailable) to inform bots and users that the site is temporarily down.
    • routable: Set to false to ensure the page is treated as a non-routable maintenance state.
    • process: Disable markdown and twig processing if you want a static, lightweight response.
    • gantry.outline: Specify the name of the Gantry outline (e.g., _offline) to use for rendering the maintenance layout.
    ---
title: We are Down for Maintenance
robots: noindex,nofollow
routable: false
http_response_code: 503
process:
    markdown: false
    twig: false
gantry:
  outline: _offline
---

  10. Use Gulp tasks to compile CSS and JS

    develop

    Gantry 5 provides several Gulp tasks for managing assets. Use these commands from the project root to compile or watch files.

    Available Gulp Commands

    • gulp or gulp all: Compiles all CSS and JS in the project.
    • gulp watch: Starts compilers in watch mode. Automatically recompiles on any change to targeted JS or SCSS files.
    • gulp watch --css: Starts watch mode for SCSS changes only.
    • gulp watch --js: Starts watch mode for JS changes only.
    • gulp css: Compiles only the CSS files.
    • gulp js: Compiles only the JS files.
    • gulp --prod: Compiles all CSS and JS in production mode. Files are compressed and do not include source maps.
    gulp watch --css
gulp --prod

  11. Update Google Fonts JSON

    develop

    To update the Google Fonts JSON file, you can generate it using the Google Fonts Developer API.

    Use the following URL structure, ensuring you have enabled the Google Fonts API and replaced YOUR-API-KEY with your actual key: https://www.googleapis.com/webfonts/v1/webfonts?key=YOUR-API-KEY

  12. Install Gantry 5 and the Hydrogen Theme

    develop

    To use a Gantry-powered theme, you must install both the Gantry 5 framework and a theme (such as Hydrogen).

    1. Download the latest stable build or CI builds from the official sources:
    2. Follow the step-by-step installation guide specific to your CMS (Joomla, WordPress, or Grav).
    <!-- Links provided in documentation for downloading packages -->