Options files are in gavern/options catalog in a folder connected with a currently used language. In the catalog, you will find two main files groups:

• tabs.json file – it includes a list of sections visible on the right side of an administration panel:  each section is described with a table in the form

  ["Basic", "options.basic", "enabled"]

  the first element of a table is a section name displayed in a panel, the second element is a file name without “.json” extension which stores a list of options available in a section given and the third value refers to whether a section given is visible in a panel. In this case, there will be a Basic tab displayed in a panel based on content of options.basic.json file.
• options.*.json files – they include a list of options available in a section given – their names are strictly connected with the content of tabs.json file.

Each options.*.json file includes three main fields in an object stored:

• groupname – it is a section title
• groupdesc – it specifies a section description displayed directly under a  section title
• fields – it includes a table of objects of fields displayed under the title and a section description

Each field defined by an object including the following fields:

• name – it specifies an option name which will be connected with a particular field. There is a prefix added automatically to an option name which is a theme name (it is stored in a global variable – $tpl->name).
• type– it specifies a field type. Standard fields are:
  • TextBlock – a field including a description text – it is not used for storing any option value
  • Text – the easiest text field allowing to insert short text values
  • Textarea – a text field used for inserting a greater number of text values
  • Select – a select field
  • Switcher – a checkbox restricted to two options: “Enabled” and “Disabled”
  • Media – a field allowing to choose images
  • WidthHeight – a field allowing to specify two values defining width and height (mostly used with a Media field)

These fields are defined in a gavern/form_elements/standard.php file and their code was derived from a GKFormInput field. It is worth remembering that files connected with options are parsed by a gavern/form.parser.php file. Additionally, you may create your own fields types in a gavern/form_elements catalog. In GavernWP, we have included the following fields types:

• Menu – a field allowing to generate options connected with page’s menu – used in a Navigation section
• ThemeStyle – a field allowing to choose page’s style – used at the beginning of a Basic section.

The description of creating your own fields types we will describe in the further part of this article.

• label – it specifies a label text visible next to a field
• tooltip – (optional) it allows to specify tooltip content which will appear after mousing over a label of a field given
• default – default value of a field given
• class – (optional) this field allows to specify CSS classes added to an element while generating it (if a field code supported such a functionality)
• format – (optional) a field specifying a desired field content in the form of a regular expression. e.g. value: 

  [a-zA-Z]{2,5}

  specifies that a field given will be filled in correctly only when a user set as its value a sequence of capital or small letters from 2 to 5 symbols.
• required – (optional) allows to specify whether filling in a particular field was required
• visibility – (optional) specifies when a particular field is visible. Visibility rules are separated with commas and are created in FIELD_NAME=VALUE format – in the case of a few visibility rules, they are linked with AND operator. The value of  FIELD_NAME is a name without a prefix with a theme name. e.g.

  option1=10,option2=20

  will cause that a field given will be visible when an option with option1 name will be set to 10 and, at the same time, an option2 option will have have value equals 20.
• other – (optional) this field is used for storing additional values, e.g. in the case of a Select field, it is used 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, you have to remember about its support in the theme. Option value is loaded by using a get_option function of a schemata given:

get_option($tpl->name . '_OPTION_NAME', 'DEFAULT_VALUE');

when OPTION_NAME is an option name from a JSON file and DEFAULT_VALUE is default value of an option which will be used when a user does not specify a value of an option given. What is important, there is a “_” symbol which you cannot omit. A prefix with a theme name is added in order differentiate values of options of different themes.

Creating your own field types options

While creating a new field type, you have to start from creating a catalog compliant with a field name, e.g. CustomField in a gavern/form_elements catalog. Then, you have to create a config.json file in this catalog and fill it in according to the schemata below:

{
"name": "CustomField",
"description": "Example Custom Field",
"js": false,
"css": false,
"php": "customfield.php",
"class": "GKFormInputCustomField"
}

name, description, php i class fields have to include particular values; js and css fields are optional – they allow to specify whether a field given has to use additional CSS and JavaScript code (then, a name of files from a field catalog has to be set as a value). Also, you have to create a customfield.php file including a GKFormInputCustomField class derived after a GKFormInput class.

Also, a customfield.css file must include a safety code at the beginning:

// disable direct access to the file
defined('GAVERN_WP') or die('Access denied');

Each field class has to include at least one public method – output not loading any additional arguments. This method must return HTML code of a field given. Field properties froma JSON file are available as class fields, e.g. required is available as:

$this->required

The second important public methid 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 field given uses more than one field in the data base. Then, it is useful to overwrite this method – as an example we recommend a standard code of a WidthHeight field where overwritting a getValue method was used for storing values of two form fields in one main field created by a GKInputFormWidthHeight class.

The remaining class methods have to be created according to the needs of the author of a form  field given.

• style family
• styles included in style family given

The whole configuration is included in styles.json file:

[{
"family": "color",

"family_desc": "Theme color",

"family_tooltip": "You can select one of the theme colors",

"styles": [

{

"name": "Color I",

"value": "color1",

"file": "style1.css"

},

{

"name": "Color II",

"value": "color2",

"file": "style2.css"

}

]

}]

As you can see, it includes color style family which has two styles, namely: Color I and Color II.

In order to create new style family or a style for style family given, it is enough to create a next object in styles.json file and then create CSS files connected with a family given – in the case of color family, these are style1.css and style2.css files.

GavernWP will load CSS files of a style given in a head section – chosen in an administration panel or, if there is a tool for choosing user’s styles switched on, they will be loaded based on a Cookie file storing data about a style used by a user.

You have to remember that for each style family there is at least one CSS file loaded. Therefore, creating coexisting style families like:

• dark styles and light styles
• blue styles and green styles

is incorrect because at least one CSS style from each family will be loaded immediately. So the correct one is creating style families responsible for some elements of website styling, e.g. a separate family responsible for website coloring (colors) and a separate one for website background (patterns).

Generally, you have to care about particular style families in order not to overwrite one another.

You may find files responsible for theme’s configuration in gavern/options/ catalog:

• fonts.json – a file which stores theme’s groups of fonts. By default, there are three main gropus created. In order to create a new group, it is enough to add a next object to the object table existing in this file.plik przechowujący grupy czcionek szablonu.
• menus.json – you will find space for menu used in a theme in this file. You have to remember that except adding a new object, you have to add PHP code generating menu data in theme’s code. It is also worth remembering that there could be one main menu (main field in menu object).
• opengraph.json – this file includes configuration of fields used in a block connected with metabox which is used for generating Open Graph data. We do not recommend to make any changes in it before you get acquainted with Open Graph tags implementation in GavernWP framework.
• styles.json – this file is used for generating additional theme’s styles. Except adding a new style, you have to remember about creating an additional CSS file which will be loaded while changing theme’s style.
• template.json – it is the most important configuration file. It includes information about a theme and it allows to switch off chosen elements of theme administration panel. It is NOT recommended to add new fields to this files because they will not be used without additional PHP code.
• widgets.json – a file including a list of all positions of widgets. Similarly to menus.json file, you have to remember that except adding a new widget position, you have to also add PHP code which generates it in a theme.
• widgets.styles.json – a file used for creating new widget styles. Thanks to its implementation, it allows to assign a style given to one widget type only or exclude some widget types from a style given.

In order to understand better JSON files format, we recommend to visit the official website of  this format.

1. with files use from a languages catalog
2. by creating a catalog of a language given in a config catalog
3. by creating a catalog of a language given in an options catalog

The first stage is a standard operation described in details in WordPress documentation. Let’s focus on the two remaining stages then:

Generally, there is en_US catalog created in config and options catalogs which includes JSON configuration files in an English language. So, in order to translate a theme to a different language , you have to copy this catalog and change its name to a respective language used in your installation, e.g. pl_PL. Then, you have to change all phrases from the English language to your language.

NOTE! You must not change the names of keys in JSON files, the same as, proper names because they are used for proper work and reading values.

e.g. in a widgets.json file for a fragment:

{

"name": "Top widgets",

"id": "top",

"description": "Widgets area on under the header of website",

"before_widget": "<div id=\"%1$s\" class=\"box%2$s\">",

"after_widget": "</div>",

"before_title": "<h3 class=\"box-title\">",

"after_title": "</h3>"

},

change the following phrases only:

• “Top widgets”
• “Widgets area on under the header of website”

After this operation, you will see sentences in your mother tongue in an administration panel.

It’s worth remembering that in the case when GavernWP will not find a catalog corresponding to the language set in configuration, there will be files used from en_US catalogs.

The overall outline of files structure is presented below:

1. theme’s catalog
   It includes all basic files and catalogs for a theme. It is worth seeing that Custom Pages templats have a theme. prefix at the beginning of their names which helps to find them in files structure.
   1. css
      There are all CSS theme’s files in it. They are described in details in an entry about framework’s CSS code.
      
      1. back-end
         To have everything ordered, CSS files connected with an administration panel were placed in this catalog.
         
   2. fonts
      This catalog is used for storing files with additional fonts. You have to remember that each font must have its own catalog including a stylesheet.css file. More information about fonts service can be found in an entry about Fonts in an administration panel.
      
   3. gavern
      A catalog including the base of whole GavernWP framework work.
      
      1. classes
         Files with supporting classes used in framework’s code.
         
      2. config
         Files including framework’s configuration. It has to be remembered that there are additional catalogs used for making transalations.
         
      3. form_elements
         It includes a main file with a code which generates basic form elements in an administration panel, as well as, catalogs with elements created by a user.
         
      4. helpers
         A collection of classes connected with specific framework’s tasks, e.g. with generating layout fragments.
         
      5. layouts
         Files used for generating HTML code of an administration panel.
         
      6. options
         Files which store options of particular sections of theme’s administration panel. Similarly to config catalog; there are also additional catalogs used for making translations.
         
   4. images
      Graphic files used with a theme
      
      1. back-end
         Files connected with an administration panel.
         
      2. headers
         Default header’s images.
         
      3. post_formats
         Images connected with entries formats.
         
   5. js
      JavaScript scripts files used in a thme
      
      1. back-end
         Likewise in css and images catalogs there are files included used in an administration panel.
         
      2. templates
         Additional JavaScript files used by some Custom Pages.
         
   6. languages
      Main files used for creating translations.
      
   7. layouts
      Files used for generating subpages; they include elements which are used very often; e.g. a head section.