{"id":19894584,"url":"https://github.com/amarkal/amarkal-ui","last_synced_at":"2025-05-02T20:30:41.507Z","repository":{"id":62488709,"uuid":"85730395","full_name":"amarkal/amarkal-ui","owner":"amarkal","description":"A set of UI components for WordPress","archived":false,"fork":false,"pushed_at":"2017-12-31T21:58:48.000Z","size":212,"stargazers_count":4,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-07T05:11:15.091Z","etag":null,"topics":["amarkal","wordpress","wordpress-framework"],"latest_commit_sha":null,"homepage":"","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-03-21T17:02:12.000Z","updated_at":"2022-09-26T01:53:46.000Z","dependencies_parsed_at":"2022-11-02T11:01:41.289Z","dependency_job_id":null,"html_url":"https://github.com/amarkal/amarkal-ui","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-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarkal%2Famarkal-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarkal%2Famarkal-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarkal%2Famarkal-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amarkal","download_url":"https://codeload.github.com/amarkal/amarkal-ui/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252103918,"owners_count":21695387,"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-11-12T18:33:55.659Z","updated_at":"2025-05-02T20:30:41.008Z","avatar_url":"https://github.com/amarkal.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# amarkal-ui [![Build Status](https://scrutinizer-ci.com/g/amarkal/amarkal-ui/badges/build.png?b=master)](https://scrutinizer-ci.com/g/amarkal/amarkal-ui/build-status/master) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/amarkal/amarkal-ui/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/amarkal/amarkal-ui/?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-ui/master/LICENSE)\nA set of UI components for WordPress.\n\n**Tested up to:** WordPress 4.7  \n**Dependencies:** *[amarkal-core](https://github.com/amarkal/amarkal-core)*\n\n## overview\n\n**amarkal-ui** is a set of UI components and tools that can be used for building user interfaces in a WordPress environment.\n\n### Available Components\n\n* [Text](https://github.com/amarkal/amarkal-ui/tree/master/components/text)\n* [Textarea](https://github.com/amarkal/amarkal-ui/tree/master/components/textarea)\n* [Number](https://github.com/amarkal/amarkal-ui/tree/master/components/number)\n* [Select](https://github.com/amarkal/amarkal-ui/tree/master/components/select)\n* [Radio](https://github.com/amarkal/amarkal-ui/tree/master/components/radio)\n* [Checkbox](https://github.com/amarkal/amarkal-ui/tree/master/components/checkbox)\n* [Composite](https://github.com/amarkal/amarkal-ui/tree/master/components/composite)\n* [Switch](https://github.com/amarkal/amarkal-ui/tree/master/components/switch)\n* [Slider](https://github.com/amarkal/amarkal-ui/tree/master/components/slider)\n* [Button](https://github.com/amarkal/amarkal-ui/tree/master/components/button)\n* [Toggle](https://github.com/amarkal/amarkal-ui/tree/master/components/toggle)\n* [Code](https://github.com/amarkal/amarkal-ui/tree/master/components/code)\n* [Progress Bar](https://github.com/amarkal/amarkal-ui/tree/master/components/progressbar)\n* [HTML](https://github.com/amarkal/amarkal-ui/tree/master/components/html)\n* Color Picker (coming soon)\n* Attachment (coming soon)\n* Editor (coming soon)\n* Date (coming soon)\n\n## Installation\n\n### Via Composer\n\nIf you are using the command line:  \n```\n$ composer require askupa-software/amarkal-ui:dev-master\n```\n\nOr simply add the following to your `composer.json` file:\n```javascript\n\"require\": {\n     \"askupa-software/amarkal-ui\": \"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-ui`.  \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\n[Download the package](https://github.com/amarkal/amarkal-ui/archive/master.zip) from github and include `bootstrap.php` in your project.\n\n```php\nrequire_once 'path/to/amarkal-ui/bootstrap.php';\n```\n\n## Rendering components\n\nThe `amarkal_ui_render($type, $props)` method is used to generate the HTML of the component whose `$type` is given. For example, the following code will \nrender a `text` component:\n\n```php\necho amarkal_ui_render('text', array(\n    'name'        =\u003e 'my-textfield',\n    'value'       =\u003e 'Some cool value...'\n));\n```\n\nAnd the output will be:\n\n```html\n\u003cdiv class=\"amarkal-ui-component amarkal-ui-component-text\" amarkal-component-name=\"my-textfield\"\u003e\n    \u003cscript class=\"amarkal-ui-component-props\" type=\"application/json\"\u003e{\"name\":\"my-textfield\",\"id\":\"my-textfield\",\"value\":\"Some cool value...\"}\u003c/script\u003e\n    \u003cinput type=\"text\" id=\"my-textfield\" name=\"my-textfield\" value=\"Some cool value...\"\u003e\n\u003c/div\u003e\n```\n\nYou can then use `jQuery(...).amarkalUIComponent()` to control the component in the front-end. For example, to get its value, you can call:\n\n```js\nvar value = $('.amarkal-ui-component-text').amarkalUIComponent('getValue');\n```\n\n## Working with forms\n\nWhile you can use components individually, when you have multiple components it makes sense to work in the context of a form. The `Amarkal\\UI\\Form` PHP class and its corresponding jQuery method `jQuery.amarkalUIForm(...)` allows you to easily process data and communicate it between the server and the client. Additionally, working with forms allows you to specifiy visibility conditions to any form components.\n\n### Data processing\n\nThe `Amarkal\\UI\\Form` object takes a list of UI components and loops through them to produce the final values that can then be stored into the database or further processed.\n\n### Instantiating The Form Object\n\nWhen instantiating a Form object, an array of UI components must be provided as an argument. These UI components can have default values, and some components can have filter and validation functions.\n\n```php\n$form = new Amarkal\\UI\\Form(array(\n    array(\n        'name'    =\u003e 'my-textfield',\n        'type'    =\u003e 'text',\n        'default' =\u003e 'Some text'\n    ),\n    array(\n        'name'    =\u003e 'my-textarea',\n        'type'    =\u003e 'textarea',\n        'default' =\u003e 'Some text'\n    )\n));\n```\n\n### Updating Form Values\n\nThe `Form::update()` function can be use to process form submissions and produce a filtered \u0026 validated set of values that can be safely stored in the database. The `Form::update()` function takes an array of old and new values (referred to as `$old_instance` and `$new_instance`) and uses them to produce a list of final values (referred to as `$new_instance`). When calling the `Form::update()` function, the form object will loop through all the form's UI components, and will do the following in each iteration:\n\n* If the component is disabled, the default value will be used and no processing will occur.\n* If the `$new_instance` does not have a value for the given component, the value in `$old_instance` will be used.\n* If the `$new_instance` and `$old_instance` both do not have a value for the given component, the default value will be used.\n* If the `$new_instance` has a value for the given component, that value will be filtered and validated (if applicabale) before being placed in the `$final_instance`.\n\n```php\n// Example for processing a POST form submission\n$new_instance = filter_input_array(INPUT_POST);\n$old_instance = array(); // This can be the values previously stored in the database\n$final_instance = $form-\u003eupdate($new_instance, $old_instance);\n```\n\n### Displaying Errors\n\nDuring the processing of component values, if a validatable component is found to be invalid (via its validation function), an error message will be stored in the Form's `$errors` array as `'component_name' =\u003e 'error_message'`. The list of errors can be retrieved using `Form::get_errors()`. For example:\n\n```php\n// Instantiate a form object\n$form = new Amarkal\\UI\\Form(array(\n    array(\n        'name'       =\u003e 'my-numberfield',\n        'type'       =\u003e 'number',\n        'default'    =\u003e 0,\n        'validation' =\u003e function($v,\u0026$e) {\n            if($v \u003e 10) {\n               $e = 'must be less than or equal to 10';\n               return false;\n            }\n            return true;\n        }\n    )\n));\n\n// Update form with invalid values\n$new_instance = array(\n    'my-numberfield' =\u003e 20\n);\n$final_instance = $form-\u003eupdate($new_instance);\n$errors = $form-\u003eget_errors();\n\nvar_dump($errors);\n```\n\nThe above will print:\n\n```\narray(1) {\n    [\"my-numberfield\"]=\u003e\n    string(32) \"must be less than or equal to 10\"\n}\n```\n\n### Visibility conditions\n\nWhen working in the context of forms, components can receive visibility conditions to show/hide them based on the values of other components in the form. For example:\n\n```php\n$form = new Amarkal\\UI\\Form(array(\n    array(\n        'name'       =\u003e 'my_number',\n        'type'       =\u003e 'number'\n    ),\n    array(\n        'name'       =\u003e 'my_text',\n        'type'       =\u003e 'text',\n        'show'       =\u003e '{{my_number}} === 3'\n    )\n));\n```\n\nBased on the above condition, `my_text` will only be visible if the value of `my_number` equals 3.\n\n**Syntax**\n\nVisibility conditions are written in pure javascript, while component values can be insrted to them by using double curly braces around the component's name (i.e. `{{component_name}}`). The component placeholders are replaced during runtime by the component's value. This means that you can write simple conditions like:\n```\n{{my_text}} === 'foo'\n```\nOr more complex conditions, like:\n```\n{{my_switch}} === 'on' \u0026\u0026 {{my_slider}} \u003e= 30\n```\nOr even use functions:\n```\nMath.floor({{my_number}}) \u003e= 10\n```\n\n**How does it work?**\n\nInternally, Amarkal uses a graph data structure to describe the relationships between all the components, based on their visibility conditions. When a component changes its value, the algorithm checks if there are other compnents that might be affected by this change, and evaluates their condition to see if their visibility state should be changed.\n\n\u003e NOTE: Components with a visibility condition MUST have a name\n\n## Reference\n\n### PHP Reference\n\n#### amarkal_ui_render\n*Render a UI component.*\n```php\namarkal_ui_render( $type, array $props = array() )\n```\nThis function is used to render the HTML of a UI component of type `$type` with the properties given in `$props`. To see the list of available components, go to `amarkal-ui\\components\\`. The `$type` is a string corresponding to the name of the folder in which the component is stored in. The rendered HTML is returned as a string.\n\n**Parameters**  \n* `$type` (*String*)  The component's type - one of the core component types, or a registered custom component.\n* `$props` (*Array*)  The component's properties.\n\n**Example Usage**\n```php\necho amarkal_ui_render('text', array(\n    'name'        =\u003e 'my-textfield',\n    'value'       =\u003e 'Some cool value...'\n));\n```\n\n#### amarkal_ui_register_component\n*Register a custom UI component.*\n```php\namarkal_ui_register_component( $type, $class_name )\n```\nThis function can be used to register a custom UI component, or to override an existing UI component. The registered component's class should inherit from `Amarkal\\UI\\AbstractComponent`. See one of the core components `controller.php` file as an exapmle of implementation of a component class.\n\n**Parameters**  \n* `$type` (*String*)  The component's type. If `$type` is similar to one of the core component's type, it will override the core component.\n* `$class_name` (*String*)  The component's class name.\n\n**Example Usage**\n```php\nclass MyCustomComponent extends Amarkal\\UI\\AbstractComponent\n{\n    public function get_script_path() \n    {\n        return 'path/to/template.phtml';\n    }\n}\namarkal_ui_register_component('my_custom_component', 'MyCustomComponent');\n\n// Then render it using amarkal_ui_render\necho amarkal_ui_render('my_custom_component', array(\n    'prop' =\u003e 'value'\n));\n```\n\n### JS Reference\n\n#### jQuery.amarkalUIComponent(...)\n\nInstantiate an amarkal UI component and/or call a component's method.\n\n**Supported methods**\n* `getValue()`\n\n  Returns the value of the component\n  ```js\n  var value = $('#my-component').amarkalUIComponent('getValue');\n  ```\n* `setValue( value )`\n\n  Sets the value of the component\n  ```js\n  var value = 'foo';\n  $('#my-component').amarkalUIComponent('setValue', value);\n  ```\n* `getProps()`\n\n  Get the `props` object for this component.\n  ```js\n  var props = $('#my-component').amarkalUIComponent('getProps');\n  ```\n* `setProps()`\n\n  Merge the `props` object of this component with the given object.\n  ```js\n  $('#my-component').amarkalUIComponent('setProps', {propName: 'propValue'});\n  ```\n* `getName()`\n\n  Get the name of this component. Similar to calling `getProps().name`, with the only difference that this method will return `false` if the component does not have a name.\n  ```js\n  var name = $('#my-component').amarkalUIComponent('getName');\n  ```\n* `reset()`\n\n  Reset this component to its default state.\n  ```js\n  $('#my-component').amarkalUIComponent('reset');\n  ```\n* `refresh()`\n\n  Re-render this component. This is applicable for components whose appearance depends on their container element, like the `slider` component. For such components, it is necessary to refresh them after their container's width has changed, or when it turns from a hidden to a visible state.\n  ```js\n  $('#my-component').amarkalUIComponent('reset');\n  ```\n* `changed()`\n\n  Check if the component has changed its value by comparing its initial value with its current value.\n  ```js\n  var changed = $('#my-component').amarkalUIComponent('changed');\n  ```\n* `instance()`\n\n  Returns the instance object for this component.\n  ```js\n  var instance = $('#my-component').amarkalUIComponent('instance');\n  instance.setValue('foo');\n  ```\n\n#### Events\n* `amarkal.change`\n\n  Triggered when the component's value changes.\n  ```js\n  $('#my-component').on('amarkal.change', function(){...});\n  ```\n* `amarkal.show`\n\n  Triggered when the component's visibility condition turns from unsatisfied to satisfied.\n  ```js\n  $('#my-component').on('amarkal.show', function(){...});\n  ```\n* `amarkal.hide`\n\n  Triggered when the component's visibility condition turns from satisfied to unsatisfied.\n  ```js\n  $('#my-component').on('amarkal.hide', function(){...});\n  ```\n\n  #### jQuery.amarkalUIForm(...)\n\n  Instantiate an amarkal UI form, and/or call a form's method.\n\n  **Supported methods**\n* `getData()`\n\n  Returns an object containing the values of all the components in the form.\n  ```js\n  var values = $('#my-form').amarkalUIForm('getData');\n  // 'values' is an object whose keys are the names of all the components names\n  ```\n* `setData( data )`\n\n  Sets the values of all the components based on the given data object.\n  ```js\n  var data = {\n      'component_name': 'component_value'\n  };\n  $('#my-form').amarkalUIForm('setData', data);\n  ```\n* `getValue( name )`\n\n  Get the value of the component whose name is given.\n  ```js\n  var value = $('#my-form').amarkalUIForm('getValue', 'component_name');\n  ```\n* `getComponent( name )`\n\n  Get the instance of the component whose name is given.\n  ```js\n  var $component = $('#my-form').amarkalUIForm('getComponent', 'component_name');\n  ```\n* `isVisible( name )`\n\n  Get the visibility state of the component whose name is given, based on its visibility condition.\n  ```js\n  var visible = $('#my-form').amarkalUIForm('isVisible', 'component_name');\n  ```\n* `refresh()`\n\n  Refresh all the components in this form.\n  ```js\n  $('#my-form').amarkalUIForm('refresh');\n  ```\n* `changed()`\n\n  Check if any of the values in the form has changed by comparing its current value with its initial value.\n  ```js\n  var changed = $('#my-form').amarkalUIForm('changed');\n  ```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famarkal%2Famarkal-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famarkal%2Famarkal-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famarkal%2Famarkal-ui/lists"}