Grav Version 1.1 Coming Soon

With new features and capabilities

8 mins

I wanted to take this opportunity to outline what we've been working on the past few months and provide some details on what you can expect in the upcoming releases. Since we released Grav 1.0 and the 1.0 version of the Admin Plugin 4 months ago, we have had 10 point releases. These primarily focused on bug fixes but did also include some minor new functionality.

When 1.0 was released we also outlined in some broad stokes what we planned for future versions of Grav, and with Grav 1.1 we are tackling a few of these items.

TL;DR

Major updates in Grav Core v1.1 adding new and enhanced blueprint functionality. This allows you to produce more powerful and flexible forms. Primarily you will see this in the Admin Plugin, but this same code is used by front-end forms also. Grav also gets much improved GPM functionality with versioning capabilities. This provides advanced control over which version of dependencies is required for installation and upgrades. This should result in less compatibility issues when performing updates.

The Grav Admin also gets a major update via a complete JavaScript rewrite. This rewrite fixes many JS issues, and provides improvements to existing functionality as well as providing some new JS-based functionality that is now possible. Also the admin is getting a theme update that is minor visually, but allows for compatibility with the upcoming Admin Pro plugin, as well as providing a much improved mobile experience.

We plan on releasing both of these 1.1 versions towards the end of April. To ensure maximum stability, we also intend to release periodic 'snapshot' releases of 1.1 throughout the month of April for you to test with.

Grav v1.1

Blueprint Improvements

The main improvements to Grav take the form of a major rewrite of our blueprint functionality. Blueprints are an essential piece of functionality within Grav that helps define configuration fields. These allow us to create a definition of a form field that can be rendered in the administrator plugin and allow the input, validation, and storage of values into the various configuration and page files that power Grav. Grav 1.0 had extensive support for building and extending blueprints, but Grav 1.1 takes this even further and adds improvements to our existing system.

The key blueprint functionality that will be made available with Grav 1.1 include:

  • Extending Blueprints

    You could extend forms in Grav 1.0, but now you can use a newer extends@: default syntax rather than the previous '@extends' string that needed to be quoted in YAML. Also this new format allows for the defining of a context which lets you define where to look for the base blueprint. Another new feature is the ability to extend from multiple blueprints.

  • Embedding/Importing Blueprints

    One feature that has been requested is the ability to embed or import one blueprint into another blueprint. This allows you to share fields or sub-form between multiple forms. This is accomplished via the import@ syntax.

  • Removing Existing Fields and Properties

    Another new feature is the ability to remove completely existing fields or properties from an extended blueprint. This allows the user a lot more flexibility when creating custom forms by simply using the new unset@: true syntax. To remove a field property you would use unset-<property>@: true in your extended field definition, for example: unset-options@: true.

  • Replacing Existing Fields and Properties

    Similar to removing, you can now replace an existing field or property with the replace@: true syntax for the whole field, and replace-<property>@: true for a specific property.

  • Field Ordering

    Probably the most frequently requested blueprint functionality that we have added is the ability to change field ordering. Imagine that you want to extend the default page blueprint but add a new tab. Previously, this meant your tab would be added at the end of the form, but now you can define that you wish the new tab to be added right after the content tab. This works for any field too, so you can extend a blueprint and add your own custom fields anywhere you wish! This is accomplished by using the new ordering@: syntax with either an existing property name or an integer.

  • Configuration Properties

    Another useful new feature is the ability to directly access Grav configuration in blueprints with config-<property>@ syntax. For example you can set a default for a field via config-default@: site.author.name which will use the author.name value from the site.yaml file as the default value for this field.

  • Function Calls

    The ability to call PHP functions for values has been improved in Grav 1.1 to be more powerful. You can use the data-<property>@ syntax to call static methods to obtain values. For example: data-default@: '\Grav\Plugin\Admin::route'. You can now even pass parameters to these methods.

  • Validation Rules

    You can now define a custom blueprint-level validation rule and assign this rule to a form field.

  • Custom Form Field Types

    This advanced new functionality allows you to create a custom field type via a new plugin event called getFormFieldTypes(). This allows you to provide extra functionality or instructions on how to handle the form form field.

We will be updating our Blueprints Documentation after the release of Grav 1.1 to include full details on thew blueprints capabilities with real-world examples so you can see the uses and benefits of each.

GPM Versioning

A new feature that we have wanted to add to our GPM package management system is the ability to control dependencies by version. We have opted to use a syntax very similar to the Composer Package Manager that is already familiar to most PHP developers.

This new versioning system allows you to define specific minimum version requirements of dependent packages within Grav. This should ensure that we have less (hopefully none!) issues when you update one package that also requires a specific minimum version of another package. The admin plugin for example may have an update that requires a specific version of Grav itself.

Other Improvements

There are a whole raft of other minor improvements including the ability to provide blueprints via a plugin (previously limited to Themes only). Also we have continued to refactor hard-coded paths to use PHP Streams that allow a setup file to configure where certain parts of Grav are stored in the physical filesystem. This will allow us to ensure Grav remains as flexible as possible and opens up more multi-site configuration options.

Grav Admin Plugin v1.1

JavaScript Rewrite

Along side the development of Grav 1.1, we've been making some big architectural changes to the Admin plugin also. The major change for 1.1 is a complete JavaScript rewrite from scratch. The original admin JS was a bit of a hodgepodge of various existing scripts, whereas the new code is written in ES6 (ES2015) and compiled with babel and built with webpack and gulp.

This change has allowed us to better organize our code and keep everything modular. All JS vendor dependencies are now using the NPM ecosystem which ensures our ability to keep everything up to date more easily.

During this extensive rewrite many known issues have been addressed. Also this process has exposed many other subtle problems that have gone unnoticed but were bugs or limitations just the same. The new code also has made many existing features more powerful or more extensible.

A summary of JavaScript improvements include:

  • Lists can now be nested and 'fancy fields' (such as editor, datetime picker, selectize, other lists) get automatically initialized so they are always available no matter if you add or remove items from the lists

  • The Editor has been reworked to be more flexible. In fact you can now pass any CodeMirror setting via blueprints, through the codemirror: attribute. The buttons have also a new API that allow to add or ignore buttons and behaviors into the toolbar from any plugin (see grav-plugin-editor-buttons). We also added the headers buttons (H1-H6) and Undo / Redo buttons, due to popular demand

  • We reworked the Datetimepicker, you will notice a new refreshed UI with a much better support for translations

  • We introduced a new colorpicker field. You can now add more colors to your admin plugins :)

  • Tabs are now persistent. In views such as Page editing, when switching tab and saving or refreshing, would cause the tab to be reset to the initial one.

  • Behind the scenes we have reworked how the form and toggleables work. This added a lot more reliability and consistency across the whole admin.

  • The Pages view has more persistent states. It will now remember your expanded/collapsed states as well as filtering.

  • When editing a page in Expert mode, the frontmatter editor is now more friendly. You will now get line numbers, undo/redo and YAML linter.

Theme Rewrite

The default Grav theme has been tweaked and in many places completely rewritten to ensure that it's as flexible as possible. The primary reason for this was to ensure theming and customization compatibility for the upcoming Admin Pro plugin, but a key benefit includes greatly improved mobile compatibility.

Versioning Support in GPM

Along with the versioning support added in the Grav Core for 1.1, the admin plugin can now install dependencies with the same versioning requirements as the GPM CLI commands.