askupa-software/amarkal-settings

Add setting pages with Amarkal UI components to your WordPress theme or plugin

amarkal-settings

Add setting pages with amarkal-ui components to your WordPress theme or plugin., _(*1)

Tested up to: WordPress 4.8
Dependencies: amarkal-core, amarkal-ui, _(*2)

, _(*3)

overview

amarkal-settings lets you create setting pages for your theme or plugin, based on amarkal-ui components. Setting pages store data as options in the database, and use AJAX to store the data asynchronously to improve user experience., _(*4)

Installation

Via Composer

If you are using the command line:, _(*5)

$ composer require askupa-software/amarkal-settings:dev-master

Or simply add the following to your composer.json file:, _(*6)

"require": {
     "askupa-software/amarkal-settings": "dev-master"
 }

And run the command, _(*7)

$ composer install

This will install the package in the directory vendors/askupa-software/amarkal-settings.
Now all you need to do is include the composer autoloader., _(*8)

require_once 'path/to/vendor/autoload.php';

Manually

Download amarkal-core, amarkal-ui and amarkal-settings from github and include them in your project., _(*9)

require_once 'path/to/amarkal-core/bootstrap.php';
require_once 'path/to/amarkal-ui/bootstrap.php';
require_once 'path/to/amarkal-settings/bootstrap.php';

Adding Setting Pages

A Setting page is a graphical user interface (based on amarkal-ui) that provides a convenient way for your users to store and retrieve options for your theme/plugin. A setting page is presented in the admin menu as a child page to an existing top level menu item., _(*10)

Adding a settings page

The following example shows how to add settings page that will be available under the 'Tools' submenu., _(*11)

$page = amarkal_add_settings_page(array(
    'slug'         => 'my-settings-page',
    'parent_slug'  => 'tools.php', // The 'Tools' top level menu item slug
    'title'        => 'My Settings',
    'menu_title'   => 'My Settings'
));

Now you can use the returned instance to add settings fields. Any Amarkal UI component can be used as a field., _(*12)

$page->add_field(array(
    'type'       => 'text',
    'default'    => 'Default text...',
    'title'      => 'My Text',
    'name'       => 'my-text'
));

Adding a section to a settings page

You can also divide your settings into sections, to better organize them and make it easier for the user to find what he is looking for., _(*13)

When you add one or more sections, a sidebar will appear with all the added section names, as well as a search box to search for a settings field in all the sections., _(*14)

$page->add_section(array(
    'slug'         => 'my-section', // Must be unique within the list of sections for this page
    'title'        => 'My Section'
));

// Make sure to add a 'section' argument to fields to associate them with a given section
$page->add_field(array(
    'section'    => 'my-section',
    'type'       => 'text',
    'default'    => 'Default text...',
    'title'      => 'My Text',
    'name'       => 'my-text'
));

Retrieving a settings field value

You can retrieve the value of a certain field by its name, and the slug of the page in which it is registered., _(*15)

This method checks the database first, and if nothing is found, it will return the field's default value., _(*16)

$value = amarkal_get_settings_value('my-settings-page', 'my-text');

Reference

amarkal_add_settings_page

Add a settings page., _(*17)

amarkal_add_settings_page( $args )

This function is used to create a settings page in WordPresss admin section. Once created, a menu item will be added to the submenu of the parent slug given in 'parent_slug'., _(*18)

If you want to create a top-level settings page, you need to create a menu page using add_menu_page(), and then set the settings page's 'parent_slug' to the slug of the top-level menu page that you've created., _(*19)

Parameters
* $args (Array) The list of page arguments. Acceptable arguments are: * parent_slug (String) The slug name for the parent menu (or the file name of a standard WordPress admin page). * slug (String) The slug name to refer to this menu by (should be unique for this menu). * title (String) The text to be displayed in the title tags of the page when it is displayed. * subtitle (String) The text to be displayed below the title at the top part of the page. * menu_title (String) The text to be used for the menu. * capability (String) The capability required for this menu to be displayed to the user. Used to determine whether or not a page is included in the menu. * footer_html (String) Specifies the HTML to be printed at the footer of the settings page. * subfooter_html (String) Specifies the HTML to be printed below footer of the settings page., _(*20)

Return Value
(Amarkal\Settings\SettingsPag) The instance of the settings page, _(*21)

Example Usage, _(*22)

amarkal_add_settings_page(array(
    'parent_slug'  => 'tools.php',
    'slug'         => 'my-settings-page',
    'title'        => 'My Settings',
    'menu_title'   => 'My Settings',
    'capability'   => 'manage_options'
));

amarkal_get_settings_page

Get the instance of a settings page., _(*23)

amarkal_get_settings_page( $slug )

This function is used to get the instance of a reigstered settings page by its slug., _(*24)

Parameters
* slug (String) The slug name of the settings page, _(*25)

Return Value
(Amarkal\Settings\SettingsPage) The instance of the settings page, _(*26)

Example Usage, _(*27)

$page = amarkal_get_settings_page('my-settings-page');

amarkal_get_settings_value

Get the value of the given field., _(*28)

amarkal_get_settings_value( $slug, $field_name )

This function is used to retrieve the value of a given field. If no value exists in the database, the default value will be returned. This function makes a call to get_option() internally, providing the default value of the field as the second argument., _(*29)

Parameters
* $slug (String) The slug of the settings page to which this field belongs * $field_name (String) The name of the field., _(*30)

Return Value
(Mixed) The value of the given field., _(*31)

Example Usage, _(*32)

$value = amarkal_get_settings_value('my-settings','my-text');

amarkal_get_settings_values

Get all the values for the given settings page as an array., _(*33)

amarkal_get_settings_values( $slug )

This function is used to retrieve all the value of a given settings page. If no value exists in the database, the default values will be returned. This function makes a call to get_option() internally, providing the default value of the field as the second argument., _(*34)

Parameters
* $slug (String) The slug of the settings page of which the values are to be retrieved., _(*35)

Return Value
(Array) The list of all field values, _(*36)

Example Usage, _(*37)

$values = amarkal_get_settings_values('my-settings');