THEMEKIT OPTIONS

Plugin installation

Populate the panel

There are three ways to populate the options panel with new settings and new navigation menu items but in all cases you will use a single array.

Via json array

Create an empty file settings.json, you can use the name you want, or download the example file below. Insert the json array you want with the following syntax. The top level array items are the primary navigation menu items, the second level array items can be used as secondary navigation menu items or as settings. You can view all the settings codes on the next sections.

{
    "settings": {
        "Primary menu 1": {
            "Secondary menu 1": [
                {
                    "type": "information",
                    "id": "setting-1",
                    "title": "Setting 1",
                    "content": "Custom text 1"
                }
            ]
        },
        "Primary menu 2": [
            {
                "type": "information",
                "id": "setting-2",
                "title": "Setting 2",
                "content": "Custom text 2"
            }
        ]
    }
}

After the json file is ready you need to load them. You can do it in two ways. By placing the json file inside the /custom/ folder of the Themekit Options plugin folder, in this case the file name must be settings.json. A backup of the /custom/ folder is automatically created when the plugin is deleted and automatically restored on plugin activation, this ensure the custom contents will not be lost if the plugin is deleted or updated. If you want to locate the json file somewhere else, you can do it by using the following function, insert it into the functions.php file that's located into the theme folder or, if you want to use a plugin, into the main plugin file. Replace YOUR-PATH with the path of your json file. To get the theme path use the function get_template_directory(), to get the Themekit Options path use the constant THEMEKIT_OPTIONS_PATH.

function themekit_options_custom_settings($array) {
    $path = 'YOUR-PATH';
    return themekit_options_update_settings_array($array, themekit_options_get_array_settings($path));
}
add_filter('themekit_options_init_panel', 'themekit_options_custom_settings');

Via PHP array

Use the following function, insert it into the functions.php file that's located into the theme folder or, if you want to use a plugin, into the main plugin file. Replace the $custom_array content with your one.

function themekit_options_custom_settings($array) {
    $custom_array = array(
        'Primary menu 1' => array(
                "Secondary menu 1" => array(
                    array("type" => "information", "id" => "setting-1", "title" => "Setting 1", "content" => "Custom text 1"),
                    array("type" => "information", "id" => "setting-2", "title" => "Setting 2", "content" => "Custom text 2")
                ),
                "Secondary menu 2" => array(
                    array("type" => "information", "id" => "setting-3", "title" => "Setting 3", "content" => "Custom text 3"),
                    array("type" => "information", "id" => "setting-4", "title" => "Setting 4", "content" => "Custom text 4")
                )
         ),
        'Primary menu 2' => array(
                array("type" => "information", "id" => "setting-5", "title" => "Setting 5", "content" => "Custom text 5"),
                array("type" => "information", "id" => "setting-6", "title" => "Setting 6", "content" => "Custom text 6")
         ),
    );
    return themekit_options_update_settings_array($array, $custom_array);
}
add_filter('themekit_options_init_panel', 'themekit_options_custom_settings');

Via built-in array

The plugin come with a buit-in settings array with all common settings required by the premium themes. To activate it define the constant THEMEKIT_OPTIONS_DEFAULT and set it to true. You can definte it with the function define('THEMEKIT_OPTIONS_DEFAULT', true); into the functions.php file that's located into the theme folder or if you want to use a plugin, into the main plugin file. The default settings and navigation menu items can be extended with your custom settings.

Settings list

Every setting require the following values: type, id, title and content. The id must be unique. You can download a pre-built setting file by click the button below, insert the setting.json file and the thumbs folder into the /custom/ plugin folder.

{
    "type": "information",
    "id": "",
    "title": "",
    "content": ""
}

{
    "type": "text",
    "id": "",
    "title": "",
    "content": "",
    "multilingual": true
}

{
    "type": "textarea",
    "id": "",
    "title": "",
    "content": "",
    "multilingual": true
}

{
    "type": "select",
    "id": "",
    "title": "",
    "content": "",
    "value": [ "Value 1", "Value 2", "Value 3" ]
}

{
    "type": "select-image",
    "id": "",
    "title": "",
    "content": "",
    "value": [
        [ "Value 1", "image-1.png" ],
        [ "Value 2", "image-2.png" ],
        [ "Value 3", "image-3.png" ]
    ]
}

{
    "type": "radio",
    "id": "",
    "title": "",
    "content": "",
    "value": [ "Value 1", "Value 2", "Value 3" ]
}

{
    "type": "checkbox",
    "id": "",
    "title": "",
    "content": ""
}

{
    "type": "number",
    "id": "",
    "title": "",
    "content": "",
    "unit": "px"
} 

{
    "type": "number-4",
    "id": "",
    "title": "",
    "content": "",
    "unit": "px"
}

{
    "type": "range",
    "id": "",
    "title": "",
    "content": "",
    "range": [ 0, 100 ],
    "unit": "px"
}

{
    "type": "upload",
    "id": "",
    "title": "",
    "content": ""
}

{
    "type": "upload-image",
    "id": "",
    "title": "",
    "content": "",
    "background-size": "auto 80px"
}

{
    "type": "code",
    "id": "",
    "title": "",
    "content": "",
    "mode": "css",
    "multilingual": true
}

{
    "type": "wp-editor",
    "id": "",
    "title": "",
    "content": ""
}

{
    "type": "color",
    "id": "",
    "title": "",
    "content": ""
}

{
    "type": "multi-input",
    "id": "",
    "title": "",
    "content": "",
    "value": [
        {
            "type": "upload",
            "id": "",
            "title": ""
        },
        {
            "type": "text",
            "id": "",
            "title": "",
            "multilingual": true
        },
        {
            "type": "textarea",
            "id": "",
            "title": "",
            "multilingual": true
        },
        {
            "type": "checkbox",
            "id": "",
            "title": ""
        }
    ]
}

{
    "type": "repeater",
    "id": "",
    "title": "",
    "content": "",
    "items": [
        {
            "type": "text",
            "name": "",
            "id": ""
        },
        {
            "type": "text",
            "name": "",
            "id": ""
        },
        {
            "type": "textarea",
            "name": "",
            "id": ""
        }
    ]
}

[
    {
        "id": "value"
    },
    {
        "id": "value"
    }
],[
    {
        "id": "value"
    },
    {
        "id": "value"
    }
]

$items = themekit_options_get_setting('SETTING-ID');
if (is_array($items)) {
    for ($i = 0; $i < count($items); $i++) {
        echo $items[$i]["COMPONENT-ID"];
        echo $items[$i]["COMPONENT-ID-2"];
    }
}

{
    "type": "font",
    "id": "",
    "title": "",
    "content": ""
}

{
    "type": "widgets",
    "id": "",
    "title": "",
    "content": ""
}

{
    "type": "post-types",
    "id": "",
    "title": "",
    "content": "",
    "show_default_taxonomies": true,
    "allow_custom_taxonomies": true,
    "allow_custom_archive_page": true
}

{
        "type": "system-requirements",
        "id": "",
        "title": "",
        "content": "",
        "value": [ "memory-limit", "upload-max-size", "post-max-size", "max-execution-time", "zip", "uploads-folder-writable", "php-version" ]
      }

{
    "type": "export",
    "id": "",
    "title": "",
    "content": ""
}

{
    "type": "import",
    "id": "",
    "title": "",
    "content": "",
    "envato-verification": true,
    "allow-zip-upload": true,
    "thumbs": true,
    "imports": [
        {
            "name": "Demo 1",
            "url": "DEMO-FILE-URL",
            "thumb": "demo-1.jpg",
            "required": [ "woocommerce", "revslider" ]
        },
        {
            "name": "Demo 2",
            "url": "DEMO-FILE-URL",
            "thumb": "demo-2.jpg",
            "required": [ "revslider" ]
        },
        {
            "name": "Demo 3",
            "url": "DEMO-FILE-URL",
            "thumb": "demo-3.jpg"
        }
    ]
}

Envato verification

Enable the Envato purchase code verification to allow the download and importing of a demo only to the users with a valid purchase code.
Installation and usage instructions:

• Upload the file envato.php to your server, the one that will host the import files, create a dedicated folder for that, ex. https://yoursite.com/demos/envato.php. You can find this file inside the folder /wp-content/plugins/themekit-options/include/. Do not rename the file.
• Go to https://build.envato.com/my-apps/ and register a new app.
• As App name insert the name you want. On Required permissions check only "View the user's items' sales history". As Confirmation URL insert the link the envato.php file, ex. https://yoursite.com/demos/envato.php.
• Click "Register App".
• Open the file envato.php you previously uploaded and edit the following variables.
  $PRODUCTS_IDS Insert here the array of IDs of the Envato products you want validate. Ex. array("2751380", "1151366")You can find the ID of a product from his URL. Ex. the ID of https://codecanyon.net/item/slider-revolution-responsive-wordpress-plugin/2751380 is 2751380.
  $DEMOS_DIR Insert here the name of the real directory that will contain your import files. The directory must be inside the same directory of the envato.php file. The directory name should be long and random like a password to avoid someone can find it, ex. AED90KOP.
  $CLIENT_ID Insert here your Envato App OAuth client ID.
  $SECRET_KEY Insert here your Envato App Secret key.
  $BLOCK_MULTIPLE_DOMAINS = true; Set it to true to allow the usage of a purchase code only to maximum 3 domains, if the user try to use the purchase code to more than 3 domains an alert message will appear and the download of the demo will be blocked.
• Go to this link: https://api.envato.com/authorization?response_type=code&client_id=[YOUR-APP-CLIENT-ID]&redirect_uri=[YOUR-URL]
  Replace [YOUR-APP-CLIENT-ID] with your Envato App OAuth client ID and [YOUR-URL] with the url of the envato.php file, ex. https://yoursite.com/demos/envato.php.
• In the imports array of the code above the URLs of all imports must point the the envato.php file but with an extra URL attribute to comunicate the import file name. Ex. https://yoursite.com/demos/envato.php?demo=demo-1.zip
• Upload all your import files inside the directory declared in the $DEMO_DIR variable. Ex. https://yoursite.com/demos/AED90KOP/demo-1.zip
• You're done.

How it work

• The purchase code verification is really solid due it happen all on your server side and now files are sent by your server if the code is not valid.
• The import file sent the user's website is a temporary copy of the original file with another name and within another folder.
• The temporary file is automatically deleted when the user finish the import process, to add another security layer, all the temporary files older than 30 minutes are automatically deleted when the envato.php file is executed again by another user.
• If you enabled the $BLOCK_MULTIPLE_DOMAINS option, a json file containing the list of all purchase codes and domains will be generated in the same folder of the envato.php file. This file is encrypted but you can view it by going to this url: https://yoursite.com/demos/envato.php?domains=show&key=[YOUR-APP-SECRET-KEY]. Replace [YOUR-APP-SECRET-KEY] with Envato App Secret key.
• All the stored files are encrypted, the encryption key is your Envato App Secret key

Read a setting

To read a setting you need to use the following PHP function. Replace SETTING-ID with the ID of the setting you want to get the value for.

themekit_options_get_setting('SETTING-ID');

Returned value types

Most setting types return a string or numeric value but others return and array. Currently only the Repeater setting return an array, you can use the following PHP code to read the array.

$items = themekit_options_get_setting('SETTING-ID');
if (is_array($items)) {
    for ($i = 0; $i < count($items); $i++) {
        echo $items[$i]["COMPONENT-ID"];
        echo $items[$i]["COMPONENT-ID-2"];
    }
}

Manually get the global settings array

Some special setting like the Widgets and the Post Types store their value in a private area and can not be accessed directly. All values, including the private area ones, are stored into the single global settings array, to get them use the following PHP code.

global $THEMEKIT_OPTIONS_SETTINGS;
if (!isset($THEMEKIT_OPTIONS_SETTINGS)) {
    $THEMEKIT_OPTIONS_SETTINGS = get_option('themekit-options-settings');
}

To read the Widgets and Post Types values use the keys $THEMEKIT_OPTIONS_SETTINGS['private']['widgets'] and $THEMEKIT_OPTIONS_SETTINGS['private']['post-types'].

Multilingual settings

The multilingual settings are compatible only with WPML and Polylang plugins. You don't need any configuration to use the multilingual feature, it's all automatic. You only need to add the option multilingual: true to the json setting array.

• If the translation is not found the main language content will be used instead.
• The multilingual components are text, textarea and code editor.
• Work with global options and single post options.
• The global options panel will display a new field for each language.
• The single post options panel will display only the field of the current page language.

Extra settings

The settings json array can contain additional settings. Add the key advanced to the root of the json array and inside it add the extra settings. Like showed below.

{
    "settings": {
        "Primary menu 1": {
            "Secondary menu 1": [
                {
                    "type": "information",
                    "id": "setting-1",
                    "title": "Setting 1",
                    "content": "Custom text 1"
                }
            ]
        },
        "Primary menu 2": [
            {
                "type": "information",
                "id": "setting-2",
                "title": "Setting 2",
                "content": "Custom text 2"
            }
        ]
    },
    "advanced": {
        "hidden-items": [ "setting-1", "Primary menu 1" ] 
    }
}

CSS generation

This feature allow the generation of a css file that contain the values setted in the theme option panel. Below the usage instructions.

• Create a css file named custom.css or download the example file below. The file name must be custom.css.
• Move this file inside the folder "/wp-content/plugins/themekit-options/custom/".
• Insert your css codes as usually but replace the css values with the code [themekit:SETTING-ID] where SETTING-ID is the ID if the setting you want to use. See the example below.
• You're done!

body {
    font-family: [themekit:setting-id-1];
    color: [themekit:setting-id-2];
}

p {
    font-size: [themekit:setting-id-3]px;
}

How it work

• Everytime the Theme options panel is updated a css file named custom.auto.css with the final css is generated.
• The custom.auto.css file is automatically loaded on the front-end.
• Only the styles with a value in the theme options are generated, the others are not included.
• Static styles not synchronized with the theme options can also be included, in the example file below the static style is .static-css { color: red; }.

Panel customization

The panel is white label and full brandable. See below constants can be inserted into the functions.php file that's located into the theme folder or, if you want to use a plugin, into the main plugin file.

Custom files

You can include four different custom files and the theme options will automatically load them. All the following files must be included inside the folder "/wp-content/plugins/themekit-options/custom/". You can download the example files from the button below.