Abandonment Notice: Creating and improving my plugins for Grav was fun to do, however times are changing and so am I. My interests have shifted away from coding and so I am abandoning my plugins. If you are interested in taking over please follow the "Abandoned Resource Protocol". Simply skip the first two steps and refer to this statement in step 3.
The Form Prefiller Plugin is for Grav CMS. It's purpose is to make prefilling form fields easier.
The purpose of the plugin is to prefill frontend form fields with default values by function calls using the data-*@:
notation. For the full explanation see the Using Function Calls (data-*@) in the Grav documentation.
Before starting to discover and use this plugin it's good to point out that there is a standard Grav way of prefilling or initialising a Grav Form with values.
It uses the undocumented Twig function setAllData
. A good working example was posted in the Grav Forum in 2017, see: Twig in form yaml, dynamic input values
Typically the plugin should be installed via GPM (Grav Package Manager):
$ bin/gpm install form-prefiller
Alternatively it can be installed via the Admin Plugin. The benefit when using the admin plugin is that a file with your configuration, and named form-prefiller.yaml
will be automatically saved in the user/config/plugins/
folder once the configuration is saved in the admin. Then, there is no need to copy the configuration file manually.
Another option is to manualy install the plugin by downloading the plugin as a zip file. Copy the zip file to your /user/plugins
directory, unzip it there and rename the folder to form-prefiller
.
Here is the default configuration in the configuration file form-prefiller.yaml
plus an explanation of the settings:
enabled: true
enabled: true|false
determines whether the plugin is active or not
Simply edit the plugin options in the Admin panel, or, if you don't use the Admin panel, copy the form-prefiller.yaml
default file to your user/config/plugins
folder and use that copy to change configuration settings.
To test the plugin create a new page using the example form page in the example-prefill-form-page
folder.
In order to experiment with language translations either the Grav LangSwitcher Plugin or the Language Selector plugin with flags for Grav CMS can be of help.
To get the most out of this plugin a couple of system and page configuration settings are required.
- The processing of Twig in the page frontmatter should be enabled. To do this either set
Process frontmatter Twig
toOn
in the Content section of the System Configuration in the Admin Plugin or enable it in theuser/config/system.yaml
configuration file:
pages:
frontmatter:
process_twig: true
-
To prevent the use of old cached values the page should be excluded from the Grav cache.
-
Using Twig variables in field labels (and in the page content if desired) requires setting
process.twig: true
in the page frontmatter.
To meet these last two requirements the form page frontmatter must include these lines:
cache_enable: false
process:
twig: true
These function calls make filling form fields with values from different sources easy:
getFrontmatter
- gets the value of a variable in the page header or frontmattergetTwig
- gets the value of a Twig variablegetTwigRender
- gets a result from processing parameters via a custom Twig templategetURLParameter
- gets a URL parameter value in either regular (?q=123) or Grav format (/q:123). If a parameter is specified in both formats the Grav formatted one gets precedence.
To control the return value in case a call returns null
a default return value may be specified as an extra parameter, for example return 42
when the variable the_answer_is
is missing in the page frontmatter (or is and equals to null
):
data-default@: ['\Grav\Plugin\FormPrefillerPlugin::getFrontmatter', 'the_answer_is', '42']
All frontmatter variables, any data loaded via prefill_data
and any URL parameters are accessible as Twig variables.
All can be used with the getTwig
function by using these dot notation prefixes:
prefill_frontmatter
for frontmatter variablesprefill_data
for data loaded from an external file/*prefill_params
for URL parameters
The purpose of the plugin is to prefill form fields with default values. For this Grav uses the data-*@:
notation as the key, where *
is the name of the dynamic field property you want to fill with the result of the function call.
See the examples below how to prefill dynamic field properties.
For the full explanation see the Using Function Calls (data-*@) in the Grav documentation.
Prefill a field with a URL parameter
Given this URL: https://example.com/search?query=something
(regular format) or https://example.com/search/query:somethin
(Grav format), then the value of the search
parameter can be prefilled using this function call:
data-default@: ['\Grav\Plugin\FormPrefillerPlugin::getURLParameter', 'search']
Using a list from frontmatter
Any variable present in the page header or frontmatter can be used in the function call getFrontmatter
. Suppose the form page frontmatter contains this list of pizza's:
pizzas:
0: 'Margarita'
1: 'Salami'
2: 'Rosita'
3: 'Chef Special'
The drop down form field can then be prefilled like this:
-
name: pizza
label: Select your Pizza
type: select
classes: fancy
default: 3
data-options@:
- '\Grav\Plugin\FormPrefillerPlugin::getFrontmatter'
- pizzas
Multi language forms
Text from a language file can be used to translate labels into the current language. All that is required is to change:
label: Select your Pizza
into:
data-label@:
- '\Grav\Plugin\FormPrefillerPlugin::getTwig'
- PLUGIN_FORM_PREFILLER.DEMO_TEXTS.PIZZA_LABEL
Using Twig functions and filters
Twig can also be used in the frontmatter to set frontmatter variables dynamically.
For example setting this in the frontmatter:
delivery_date: '{{ now|date_modify(''+2 day'')|date(''Y-m-d H:i'') }}'
and
data-default@:
- '\Grav\Plugin\FormPrefillerPlugin::getFrontmatter'
- delivery_date
in a form field will result in the prefilled field showing the date and time two days from now.
Prefilling a select field from a template
A select
form field requires a list to enable the user to select one of the options.
To demonstrate this the plugin comes with an example template in it's templates/partials
directory named pizzas.yaml.twig
:
{# Set suitable data structure for the form field type #}
{# In this example a numeric array #}
{% set pizzas = {
0: 'Margarita',
1: 'Salami',
2: 'Rosita',
3: 'Chef Special'
} %}
{# To return anything other then a string apply the filter yaml_encode #}
{{ pizzas|yaml_encode }}
In order to get the list as an array instead of a string make sure to apply the yaml_encode
filter in the template.
Using the data from the template in the form is simply a matter of calling the getTwigRender function and specifying the template name:
-
name: get_pizzas_from_template
label: 'Getting a list from a template ("pizzas.yaml.twig")'
type: select
classes: fancy
default: 3
data-options@:
- '\Grav\Plugin\FormPrefillerPlugin::getTwigRender'
- pizzas.yaml.twig
Loading external data
External data in YAML or JSON format can be loaded through a frontmatter variable named prefill_data
. For example:
prefill_data:
- 'user://data/test.yaml'
The content of the test file user/data/test.yaml
is for example:
var1: ef_val1
var2:
var2a: ef_val2a
var2b: ef_val2b
The plugin then replaces the file reference with the file data itself.
To prefill a form field with the value of var2b
use this function call:
data-default@:
- '\Grav\Plugin\FormPrefillerPlugin::getTwig'
- prefill_data.test.var2.var2b
Multipe files can be read by specifying a list. For more information see the Import Plugin documentation.
The plugin tries to silently cope with errors but does log them. When to your surprise form fields do not get prefilled take a look at the Grav log file ('logs/grav.log`). Also when the debugger is enabled error messages as well as warnings are displayed in the Debug Bar.
An example of an error log message is:
"FormPrefillerPlugin: Error reading data from "user://data/test.yaml": Indentation problem at line 4 (near " ef_val2a")"
An example of a Debug Bar warning message is:
"FormPrefillerPlugin: Warning: the function getURLParameter returned "null" since the URL parameter "category" was not found"
Credits go to Aaron Dalton (Perlkonig) for his Import Plugin from which some code I have reused.