{"id":13401370,"url":"https://github.com/iamntz/carbon-chained-select","last_synced_at":"2025-07-25T13:45:38.556Z","repository":{"id":56988098,"uuid":"139263375","full_name":"iamntz/carbon-chained-select","owner":"iamntz","description":"An awesome chained select for Carbon Fields plugin!","archived":false,"fork":false,"pushed_at":"2020-03-14T08:08:47.000Z","size":1001,"stargazers_count":8,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-11T05:49:15.911Z","etag":null,"topics":["carbon-fields","carbon-fields-field","wordpress"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamntz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-30T16:27:23.000Z","updated_at":"2022-09-28T09:35:12.000Z","dependencies_parsed_at":"2022-08-21T09:40:47.073Z","dependency_job_id":null,"html_url":"https://github.com/iamntz/carbon-chained-select","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamntz%2Fcarbon-chained-select","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamntz%2Fcarbon-chained-select/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamntz%2Fcarbon-chained-select/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamntz%2Fcarbon-chained-select/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamntz","download_url":"https://codeload.github.com/iamntz/carbon-chained-select/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243541960,"owners_count":20307791,"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":["carbon-fields","carbon-fields-field","wordpress"],"created_at":"2024-07-30T19:01:01.999Z","updated_at":"2025-03-14T07:31:33.912Z","avatar_url":"https://github.com/iamntz.png","language":"PHP","funding_links":["https://www.paypal.me/iamntz","https://www.patreon.com/iamntz"],"categories":["Fields (Carbon Fields 2+)"],"sub_categories":[],"readme":"# Carbon Field: chainedselect\n\nProvides a chained select control.\n\n![](https://img.iamntz.com/carbon-chained-select-demo.gif)\n\nAdds a `chainedselect` field type to Carbon Fields. Install using Composer:\n\n```cli\ncomposer require \"iamntz/carbon-chained-select:^3.0\"\n```\n\nFor Carbon Fields 2 (legacy):\n\n```cli\ncomposer require \"iamntz/carbon-chained-select:^2.0\"\n```\n\n\n## `add_option` array structure\n\nBasically this is a multidimensional array with few _magic_ keywords. These keywords are: `__label__`, `__config__`.\n\nAny of these keys *can* be changed by using `carbon_chained_select_config` filter, or, even furter, via `carbon_chained_select_config/name=field-name` filter.\n\n```php\n-\u003eadd_options([\n  '__label__' =\u003e 'Select 1', // field label\n\n  'value1' =\u003e 'Option Text 1',\n  'value2' =\u003e 'Option Text 2',\n\n  'value3_nested' =\u003e [\n    '__label__' =\u003e 'Select 2 (nested)', // option text AND next field label\n\n    'select-2-1-1' =\u003e 'Option text 2 - 1',\n    'select-2-1-2' =\u003e 'Option text 2 - 2',\n\n    \"select-2-1-3\" =\u003e [\n      '__label__' =\u003e 'Select 3 (nested, with remote)', // option text and 3rd level field label\n\n      '__config__' =\u003e [\n        'multiple' =\u003e true,\n        'endpoint' =\u003e '/wp-json/namespace/v2/chained-select',\n      ],\n    ],\n  ],\n]);\n```\n\nAlternatively, you can move all config-related within `__config__` array:\n```php\n-\u003eadd_options([\n  '__config__' =\u003e [\n    'label' =\u003e 'Select 1', // field label\n  ]\n\n  'value1' =\u003e 'Option Text 1',\n  'value2' =\u003e 'Option Text 2',\n\n  'value3_nested' =\u003e [\n    '__label__' =\u003e 'Select 2 (nested)', // option text AND next field label\n\n    'select-2-1-1' =\u003e 'Option text 2 - 1',\n    'select-2-1-2' =\u003e 'Option text 2 - 2',\n\n    \"select-2-1-3\" =\u003e [\n      '__config__' =\u003e [\n        /**\n         * By default, each nested item will be in an array that will look pretty much like this:\n         * [\n         *    'value3_nested' =\u003e value3_nested',\n         *    'select-2-1-3' =\u003e select-2-1-3'\n         * ]\n         *\n         * You can specify a name for each level, so you could have a multi-dimensional array, something like this:\n         * [\n         *  'value3_nested' =\u003e 'value3_nested',\n         *  'last-level-name' =\u003e 'select-2-1-3'\n         * ]\n         *\n         * If no `name` config key is provided, then the value name will be used. For consistency sake,\n         * try to use one way or another, don't mix them. Also, please note that by NOT specifying a name,\n         * you're stuck with the initial order. I.e. won't be able to reorder items without breaking existing data!\n         *\n         * So TL;DR: use a damn name!\n         */\n        'name' =\u003e 'last-level-name',\n\n        // if you have a `label` key here, then the `__label__` key on an upper level will be ignored.\n        'label' =\u003e 'Select 3 (nested, with remote)',\n\n        // optional, is the label that will appear above `select` field. If not specified,\n        // then the label above will be used as both option AND label\n        'option_label' =\u003e '',\n\n        // wether if the field can have multiple values or only one.\n        // Please note that if a field is multiple, you can't have any further nested selects\n        // you can try though, but the results are not predictible :)\n        'multiple' =\u003e true,\n\n        // REST endpoint to fetch new options. This should accept GET requests!\n        // Params sent on the request:\n        // {\n        //    nonce: nonce, // checking for carbon_chained_select key\n        //    value: value, // current select value\n        //    fieldValue: field.value, // whole field value (as an array)\n        //    name: name, // the field name\n        //    query: query // if user searched something, it will be sent as this key\n        // }\n        //\n        // The response should follow the same structure as this initial array,\n        // parsed (read below) then sent as json\n        'endpoint' =\u003e '/wp-json/namespace/v2/chained-select',\n      ],\n    ],\n  ],\n]);\n```\n\nInternally, this will be arranged as needed, so you don't need to worry too much about it.\n\nFor ajax calls, the response must follow the same structure, but must be parsed before is sent:\n\n```php\n$parser = new \\iamntz\\carbon\\chainedSelect\\OptionsParser([\n  'selectOptions' =\u003e $options // same structure as above!\n], 'fieldName');\n\n$parser-\u003eparse();\n```\n\nSecond argument, `fieldName`, is optional and used only for the config filter (i.e. for changing magic keywords).\n\n## Limitation\nAt this moment, you can't have chained \u0026 ajax within fields fetched via ajax.\n\nSo you chain fields like this:\n\n```\nfield \u003e field \u003e ajax \u003e field \u003e field\n```\n\nBut you **cant** chain fields like this:\n\n```\nfield \u003e field \u003e ajax \u003e field \u003e ajax\n```\n\nAlso, you can't have multiple select AND ajax on the same field.\n\n## Return values\nValue returned is an associative array that follows the field names.\n\n----\n\n## Known issues:\n\n- [ ] You can't have another nested field after an ajax select. This _might_ work but I didn't tested.\n- [ ] You can't have another nested field after a select with multiple options. This one has a very very **VERY** low priority (mostly because the way I see it, is a UX nightmare) on my list.\n- [ ] Conditional logic is broken on this field. This is caused by the way I store data in the DB (as a json string). Although I would like to make this work, I have to find some time to dig into Carbon Field conditional and understand its logic.\n- [ ] Didn't tested, but setting a field as required should have the very same issue as the conditional logic above.\n\nIf you have any fixes, please send a PR!\n\n#### Special Note on validation\nCarbon's Select fields (both normal and multiselect) uses a validation that will make sure an user won't be able to select an option that doesn't exists in the provided array in config. However, considering that the source can be also external (i.e. via AJAX), this can't be implemented in a reasonable extensible way.\n\nMost likely this won't affect anything, but **if** sometime in the future Carbon can be used on the frontend, this _may_ be a gateway of abuses.\n\n\n### Support me\nYou can get [hosting](https://m.do.co/c/c95a44d0e992), [donate](https://www.paypal.me/iamntz) or be my [patreon](https://www.patreon.com/iamntz).\n\n\n### License\nThe code is released under MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamntz%2Fcarbon-chained-select","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamntz%2Fcarbon-chained-select","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamntz%2Fcarbon-chained-select/lists"}