{"id":14969778,"url":"https://github.com/amarkal/amarkal-settings","last_synced_at":"2025-10-26T09:31:05.136Z","repository":{"id":62488701,"uuid":"88450441","full_name":"amarkal/amarkal-settings","owner":"amarkal","description":"Add setting pages with Amarkal UI components to your WordPress theme or plugin","archived":false,"fork":false,"pushed_at":"2017-12-25T21:13:55.000Z","size":117,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-09-28T12:03:54.677Z","etag":null,"topics":["amarkal","wordpress","wordpress-framework"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amarkal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-17T00:03:22.000Z","updated_at":"2022-09-26T01:50:51.000Z","dependencies_parsed_at":"2022-11-02T09:31:09.738Z","dependency_job_id":null,"html_url":"https://github.com/amarkal/amarkal-settings","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarkal%2Famarkal-settings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarkal%2Famarkal-settings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarkal%2Famarkal-settings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarkal%2Famarkal-settings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amarkal","download_url":"https://codeload.github.com/amarkal/amarkal-settings/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219863300,"owners_count":16555950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amarkal","wordpress","wordpress-framework"],"created_at":"2024-09-24T13:42:21.760Z","updated_at":"2025-10-26T09:30:59.823Z","avatar_url":"https://github.com/amarkal.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# amarkal-settings [![Build Status](https://scrutinizer-ci.com/g/amarkal/amarkal-settings/badges/build.png?b=master)](https://scrutinizer-ci.com/g/amarkal/amarkal-settings/build-status/master) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/amarkal/amarkal-settings/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/amarkal/amarkal-settings/?branch=master) [![Built with Grunt](https://cdn.gruntjs.com/builtwith.svg)](https://gruntjs.com/) [![Amarkal Powered](https://askupasoftware.com/amarkal-powered.svg)](https://products.askupasoftware.com/amarkal) [![License](https://img.shields.io/badge/license-GPL--3.0%2B-red.svg)](https://raw.githubusercontent.com/amarkal/amarkal-settings/master/LICENSE)\nAdd setting pages with [amarkal-ui](https://github.com/amarkal/amarkal-ui) components to your WordPress theme or plugin.\n\n**Tested up to:** WordPress 4.8  \n**Dependencies**: *[amarkal-core](https://github.com/amarkal/amarkal-core)*, *[amarkal-ui](https://github.com/amarkal/amarkal-ui)*\n\n![amarkal-settings](https://askupasoftware.com/wp-content/uploads/2015/04/amarkal-settings.png)\n\n## overview\n\n**amarkal-settings** lets you create setting pages for your theme or plugin, based on [amarkal-ui](https://github.com/amarkal/amarkal-ui) components. Setting pages store data as options in the database, and use AJAX to store the data asynchronously to improve user experience.\n\n## Installation\n\n### Via Composer\n\nIf you are using the command line:  \n```\n$ composer require askupa-software/amarkal-settings:dev-master\n```\n\nOr simply add the following to your `composer.json` file:\n```javascript\n\"require\": {\n     \"askupa-software/amarkal-settings\": \"dev-master\"\n }\n```\nAnd run the command \n```\n$ composer install\n```\n\nThis will install the package in the directory `vendors/askupa-software/amarkal-settings`.  \nNow all you need to do is include the composer autoloader.\n\n```php\nrequire_once 'path/to/vendor/autoload.php';\n```\n\n### Manually\n\nDownload [amarkal-core](https://github.com/amarkal/amarkal-core/archive/master.zip), [amarkal-ui](https://github.com/amarkal/amarkal-ui/archive/master.zip) and [amarkal-settings](https://github.com/amarkal/amarkal-settings/archive/master.zip) from github and include them in your project.\n\n```php\nrequire_once 'path/to/amarkal-core/bootstrap.php';\nrequire_once 'path/to/amarkal-ui/bootstrap.php';\nrequire_once 'path/to/amarkal-settings/bootstrap.php';\n```\n\n## Adding Setting Pages\n\nA 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.\n\n### Adding a settings page\n\nThe following example shows how to add settings page that will be available under the 'Tools' submenu.\n\n```php\n$page = amarkal_add_settings_page(array(\n    'slug'         =\u003e 'my-settings-page',\n    'parent_slug'  =\u003e 'tools.php', // The 'Tools' top level menu item slug\n    'title'        =\u003e 'My Settings',\n    'menu_title'   =\u003e 'My Settings'\n));\n```\n\nNow you can use the returned instance to add settings fields. Any Amarkal UI component can be used as a field.\n\n```php\n$page-\u003eadd_field(array(\n    'type'       =\u003e 'text',\n    'default'    =\u003e 'Default text...',\n    'title'      =\u003e 'My Text',\n    'name'       =\u003e 'my-text'\n));\n```\n\n### Adding a section to a settings page\n\nYou 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.\n\n\u003e\u003e 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.\n\n```php\n$page-\u003eadd_section(array(\n    'slug'         =\u003e 'my-section', // Must be unique within the list of sections for this page\n    'title'        =\u003e 'My Section'\n));\n\n// Make sure to add a 'section' argument to fields to associate them with a given section\n$page-\u003eadd_field(array(\n    'section'    =\u003e 'my-section',\n    'type'       =\u003e 'text',\n    'default'    =\u003e 'Default text...',\n    'title'      =\u003e 'My Text',\n    'name'       =\u003e 'my-text'\n));\n```\n\n### Retrieving a settings field value\n\nYou can retrieve the value of a certain field by its name, and the slug of the page in which it is registered.\n\n\u003e\u003e This method checks the database first, and if nothing is found, it will return the field's default value.\n\n```php\n$value = amarkal_get_settings_value('my-settings-page', 'my-text');\n```\n\n## Reference\n\n### amarkal_add_settings_page\n*Add a settings page.*\n```php\namarkal_add_settings_page( $args )\n```\nThis 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'`.\n\n\u003e\u003e 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.\n\n**Parameters**  \n* `$args` (*Array*)  The list of page arguments. Acceptable arguments are:\n  * `parent_slug` (*String*) The slug name for the parent menu (or the file name of a standard WordPress admin page).\n  * `slug` (*String*) The slug name to refer to this menu by (should be unique for this menu).\n  * `title` (*String*) The text to be displayed in the title tags of the page when it is displayed.\n  * `subtitle` (*String*) The text to be displayed below the title at the top part of the page.\n  * `menu_title` (*String*) The text to be used for the menu.\n  * `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.\n  * `footer_html` (*String*) Specifies the HTML to be printed at the footer of the  settings page.\n  * `subfooter_html` (*String*) Specifies the HTML to be printed below footer of the  settings page.\n\n**Return Value**  \n(*Amarkal\\Settings\\SettingsPag*) The instance of the settings page\n\n**Example Usage**\n```php\namarkal_add_settings_page(array(\n    'parent_slug'  =\u003e 'tools.php',\n    'slug'         =\u003e 'my-settings-page',\n    'title'        =\u003e 'My Settings',\n    'menu_title'   =\u003e 'My Settings',\n    'capability'   =\u003e 'manage_options'\n));\n```\n\n### amarkal_get_settings_page\n*Get the instance of a settings page.*\n```php\namarkal_get_settings_page( $slug )\n```\nThis function is used to get the instance of a reigstered settings page by its slug.\n\n**Parameters**  \n* `slug` (*String*) The slug name of the settings page\n\n**Return Value**  \n(*Amarkal\\Settings\\SettingsPage*) The instance of the settings page\n\n**Example Usage**\n```php\n$page = amarkal_get_settings_page('my-settings-page');\n```\n\n### amarkal_get_settings_value\n*Get the value of the given field.*\n```php\namarkal_get_settings_value( $slug, $field_name )\n```\nThis 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.\n\n**Parameters**  \n* `$slug` (*String*) The slug of the settings page to which this field belongs\n* `$field_name` (*String*)  The name of the field.\n\n**Return Value**  \n(*Mixed*) The value of the given field.\n\n**Example Usage**\n```php\n$value = amarkal_get_settings_value('my-settings','my-text');\n```\n\n### amarkal_get_settings_values\n*Get all the values for the given settings page as an array.*\n```php\namarkal_get_settings_values( $slug )\n```\nThis 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.\n\n**Parameters**  \n* `$slug` (*String*) The slug of the settings page of which the values are to be retrieved.\n\n**Return Value**  \n(*Array*) The list of all field values\n\n**Example Usage**\n```php\n$values = amarkal_get_settings_values('my-settings');\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famarkal%2Famarkal-settings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famarkal%2Famarkal-settings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famarkal%2Famarkal-settings/lists"}