{"id":17087391,"url":"https://github.com/dakujem/selectoo","last_synced_at":"2025-04-12T21:53:11.389Z","repository":{"id":52636018,"uuid":"116148928","full_name":"dakujem/selectoo","owner":"dakujem","description":"A flexible select input for nette/forms package with capability to generate tailored scripts, namely Select2.","archived":false,"fork":false,"pushed_at":"2025-01-09T22:53:43.000Z","size":64,"stargazers_count":1,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T16:03:20.635Z","etag":null,"topics":["cascading-inputs","component","javascript-wrapper","nette","selectbox"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dakujem.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-01-03T14:56:02.000Z","updated_at":"2025-01-09T22:52:51.000Z","dependencies_parsed_at":"2024-04-18T20:43:04.563Z","dependency_job_id":"5d3600c5-09cb-4c49-8f6a-6f10584d5b03","html_url":"https://github.com/dakujem/selectoo","commit_stats":{"total_commits":38,"total_committers":2,"mean_commits":19.0,"dds":0.02631578947368418,"last_synced_commit":"83e15950176bd099e0556818adc28e4c60d4c5d4"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dakujem%2Fselectoo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dakujem%2Fselectoo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dakujem%2Fselectoo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dakujem%2Fselectoo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dakujem","download_url":"https://codeload.github.com/dakujem/selectoo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248217181,"owners_count":21066633,"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":["cascading-inputs","component","javascript-wrapper","nette","selectbox"],"created_at":"2024-10-14T13:32:57.606Z","updated_at":"2025-04-12T21:53:11.361Z","avatar_url":"https://github.com/dakujem.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Selectoo\n\n[![PHP from Packagist](https://img.shields.io/packagist/php-v/dakujem/selectoo.svg)]()\n\n\nSelectBox \u0026 MultiSelectBox hybrid input with lazy \u0026 asynchronous options loading capabilities to be used with Select2, Selectize, Chosen and similar UI libraries.\n\nThe aim of Selectoo is to provide a flexible tool for creating reusable select inputs.\n\n\n## Features\n\n- can work in single-choice or multi-choice modes\n\t- single-choice mode is roughly equal to `SelectBox`\n\t- multi-choice  mode is roughly equal to `MultiSelectBox`\n- on-demand (lazy) loading of options using a callback\n\t- options can be loaded asynchronously using AJAX\n\t- options are only loaded when really needed\n- can be skinned with UI libraries or custom scripts (see below)\n- dependent / cascading inputs\n\n\n## Usage / Use cases\n\n**Reusable** inputs with specific setup:\n- select2-skinned (or other library) input with special configuration options and other application logic\n- autocomplete with ajax\n- tagging\n- custom ui script for altering the DOM upon selection\n- cascading / dependent inputs\n\n\u003e See included examples for more information.\n\n\n## Configuring Selectoo input\n\nCreate a (multi)select box with fixed options\n```php\n$items = ['a', 'b', 'c', 'd',];\n$input = new Selectoo($label, $items, $multiselect);\n```\n\nor a (multi)select box with options loaded on demand (lazy loading).\n```php\n$input = new Selectoo($label, [$repository, 'fetchAll'], $multiselect);\n```\n\nAn engine can optionally be attached\n```php\n$input-\u003esetEngine(new Select2Engine);\n```\n\nand configured.\n```php\n$input-\u003egetEngine()\n\n\t-\u003eplaceholder('Select a user', true)\n\t-\u003ewidth('width: 100%', true)\n\t-\u003ecloseOnSelect(false, true)\n\n;\n```\n\nThe `Select2Engine` is configured using magic options (or `setOption` method).\nThe names of the magic methods (or option names) represent the **Select2 configuration options**.\n\n\n## Lazy options loading \u0026 AJAX\n\nLazy loading is used when the Selectoo instance is given \"item callback\" callable instead of an array of items.\nThe callable is supposed to return a list of items.\n\nThe item callback also works as a validator for values.\nIt receives raw value as the first argument (and the input instance as the second).\nThe callback should return the array of possible values (these are the items) in form\nexactly the same as the items set to `SelectBox` or `MultiSelectBox` inputs.\nThe raw value is then compared to the returned items and filtered.\nThis approach ensures the validity of the data.\n\nIt is important to set this callback in case you work with remote item loading (ajax/api loading of options).\n\nSee the [example ajax presenter](examples/ajax/ExamplePresenter.php),\ncomplete with input factory and user repository examples.\n\nAjax configuration can be very simple:\n```php\n(new Select2Engine())\n\t-\u003eajax('{url: \"' . $link . '\", dataType: \"json\" }')\n;\n```\n\n## Supported and intended UI libraries\n\nSelectoo uses \"script engines\" to generate JavaScript UI scripts along with HTML input element.\nAny script engine can be attached to the `Selectoo` instance by calling `$selectoo-\u003esetEngine($engine)`.\n\n- [select2/select2](https://github.com/select2/select2)\n\t- use the `Select2Engine` instances\n- selectize/selectize.js\n\t- to be implemented\n- harvesthq/chosen\n\t- to be implemented\n\nCustom engines can easily be created implementing the `ScriptEngineInterface` interface.\n\n\n## Factories\n\nFor best reusability I strongly encourage using factories for inputs with more logic,\ntypically these involve fetching data from storage or external resources along with JS/UI configuration,\nhandling events and value validation.\n\nSee simple examples:\n- [general selectoo factory](examples/factories/Select2SelectooFactory.php)\n- [example user select factory](examples/factories/UserSelectooFactory.php)\n- [example AJAX API loaded input](examples/ajax/UserAjaxSelectooFactory.php)\n\n\n## Script management\n\nThe scripts generated by engines can be post-processed and/or collected by a management routine.\nThis approach can be used to gather and place the scripts at the end of the page and to solve problems\nwhen writing scripts inside the page and loading jQuery at the end of the HTML file.\n\nSee [script-management example](examples/script-management/Select2SelectooWithCollectorFactory.php) for more information.\n\n\n## Dependent selections / cascading inputs\n\nExample is being prepared.\n\nWhat is needed, in general:\n- UI script that manages on change events\n- Select2 configuration that sends the value of master inputs in the URL of the AJAX request\n- repository filtering based upon the values\n- API endpoint that receives the master values and makes repository request, using values from the URL\n- \"item callback\" that also makes repository request, using values from `Form`\n\n\u003e Note that when the item callback is called the values from the `Form` object can be used to check for master values\n\n\u003e By \"master values\" above I mean the values of the inputs the Selectoo instance depends on\n\nBy following these steps, dependent Selectoo inputs can be created and values validated.\n\n\n## Examples\n\nPlease see the examples included in the repository to get a better understanding of when Selectoo comes handy.\n\n\n## Notable differences compared to Nette SelectBox \u0026 MultiSelectBox\n\n- disabling a Selectoo input does not modify/reset its value, so it can be re-enabled without the loss of the information\n- disabled input is handled differently - raw value is always loaded even when input (or items) is disabled. The disabled values are filtered when calling `getValue` method.\n\n\n## Requirements\n\n| Selectoo | PHP | Nette forms |\n|:---------|:----|:------------|\n| version `2.0` | `7.1+` | `3.*` |\n| version `1.0` | `7.0+` | `2.4.*` |\n\nYou should also install **Select2** version `4` to use the `Select2Engine`,\nsee [Select2 documentation](https://select2.org/).\n\nYou may install any other select input \"skin\" and implement your own engine for it within minutes.\n\nSelectoo can also be used without such a \"skin\".\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdakujem%2Fselectoo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdakujem%2Fselectoo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdakujem%2Fselectoo/lists"}