GavernWP WordPress framework: Developer’s guide for option creation & storage
Changes to content of an administration panel is very easy using the GavernWP framework. The framework is based upon a series of JSON files which contain sets of options. This approach allows new options to be easily created, and new options made available in an administration panel.
Options files are located in the gavern/options catalog in a folder associated with the currently-used language. In the catalog, you will find two main file groups:
- tabs.json file – This file includes a list of the sections visible on the right side of an administration panel
["Basic", "options.basic", "enabled"]
where the first element of a table is a section name displayed in a panel, the second element is a filename without the “.json” extension which stores a list of options available in a given section, and the third value refers to whether a given section is visible in a panel. In this case, there will be a Basic tab displayed in a panel based on content of the options.basic.json file.
- options.*.json files – these include a list of options available in a given section; their names are strictly associated with the content of a tabs.json file.
Each options.*.json file includes three main fields of a stored object:
- groupname – a section title
- groupdesc – specifies a section description displayed directly under a section title
- fields – this includes a table of field objects displayed under the title and a section description
Each field object itself includes the following fields:
- name – Used to specify an option name to be associated with a particular field. A prefix is automatically added to an option name which is a theme name (stored in a global variable –$tpl->name).
- type– This specifies a field type. Standard field types are:
- TextBlock – A field which includes description text –not used to store any option value.
- Text – The most basic text field, it allows the capture of short text values.
- RawText – pure, simple text without any formatting
- Textarea – A text field used for entering a greater amount of text.
- Select – A selection field.
- Switcher – A checkbox restricted to two options: “Enabled” and “Disabled”.
- Media – A field used to select images.
- WidthHeight – A field used to specify two values which define the width and height (mostly used with the Media field).
These fields are defined in a gavern/form_elements/standard.php file and their code is derived from a GKFormInput field. Files associated with options are parsed by a gavern/form.parser.php file. Additionally, you may create your own field types in a gavern/form_elements catalog. In GavernWP, we have included the following field types:
- Menu – Used to set options associated with a page’s menu; used within a Navigation section
- Theme Style – A field enabling a page’s style to be selected; used at the beginning of a Basic section.
Instructions on creating custom field types will be described later in this article.
- label – This specifies the label text visible next to a field.
- tooltip – (optional) This allows tooltip content to be specified. This text appears during a mouse over of the label of a specified field.
- default – Default value of a given field.
- class – (optional) This field is used to specify CSS classes added to an element while generating it (if the field code supports such functionality).
- format– (optional) A field which specifies the desired structure of a field’s content in the form of a regular expression. e.g. value:
[a-zA-Z]{2,5}specifies that a field given is correctly completed only when a user sets as its value a sequence of capital or small letters between 2 and 5 symbols in length.
- required – (optional) Sets whether completion of a particular field is mandatory.
- visibility – (optional) Specifies when a particular field is visible. Visibility rules are separated with commas and are arranged in the format FIELD_NAME=VALUE. In the event of multiple visibility rules, they are linked with the AND operator. The value of FIELD_NAMEis a name without a prefix with a theme name. e.g.
option1=10,option2=20
will result in the specified field becoming visible when an option with the name option1 is set to 10 and, at the same time, an option2 option has a value of 20.
- other – (optional) This field is used to store additional values, e.g. in the case of a Select field, for storing names and options values. This field is very useful when creating more advanced fields which may require additional configuration options.
After adding a new option, consider its support within the theme. The option value is loaded by using a get_option function of the following form:
get_option($tpl->name . '_OPTION_NAME', 'DEFAULT_VALUE');
In this example, OPTION_NAME is an option name from a JSON file and DEFAULT_VALUE is the default value of an option used when a user does not specify a value for a given option. The underscore (“_”) symbol must not be omitted. A prefix with a theme name is added in order differentiate between values of options of different theme.
Creating your own field types options
When creating a new field type, you must start by creating a catalog aligned with a field name (for example, CustomField in a gavern/form_elements catalog). Then, you have to create a config.json file in this catalog and complete it according to the following schema:
{
"name": "CustomField",
"description": "Example Custom Field",
"js": false,
"css": false,
"php": "customfield.php",
"class": "GKFormInputCustomField"
}
In this example, the name, description, php and class fields must include particular values; the js and css fields are optional – they are used to specify whether a given field must use additional CSS and JavaScript code (in which case, the name of files from a field catalog must be set as a value). Also, you must create a customfield.php file which includes a GKFormInputCustomField class derived from a GKFormInput class.
Additionally, a customfield.css file must include protective code similar to the following:
// disable direct access to the file
defined('GAVERN_WP') or die('Access denied');
Each field class must include at least one public method – output — not loading any additional arguments. This method must return the HTML code of a field given. Field properties from a JSON file are available as class fields, e.g. required is available as:
$this->required
The second important public method of each class of a form field is a getValue method which loads one argument – $default. Its use is optional and useful only when a value of a given field uses more than one field in the database. In this case, it is useful to overwrite this method. As an example, we recommend a standard code of a WidthHeight field where overwriting of a getValue method is used for storing the values of two form fields in one main field created by a GKInputFormWidthHeight class.
The remaining class methods must be established according to the needs of the author of a given form field.
This article was first published
