{"id":15180492,"url":"https://github.com/massimo-cassandro/symfony-bootstrap-form-theme","last_synced_at":"2025-10-01T21:30:20.921Z","repository":{"id":36463956,"uuid":"221957628","full_name":"massimo-cassandro/symfony-bootstrap-form-theme","owner":"massimo-cassandro","description":"Bootstrap 4 Form Theme for Symfony 3, 4 and 5","archived":true,"fork":false,"pushed_at":"2023-07-19T10:18:18.000Z","size":1330,"stargazers_count":7,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-16T18:06:23.056Z","etag":null,"topics":["bootstrap","bootstrap-4","checkboxes","form-theme","forms","single-checkboxes","symfony","twig","twig-templates","user-experience","user-interface"],"latest_commit_sha":null,"homepage":"https://massimo-cassandro.github.io/symfony-bootstrap-form-theme/","language":"Twig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/massimo-cassandro.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":"2019-11-15T16:02:23.000Z","updated_at":"2023-07-19T10:18:41.000Z","dependencies_parsed_at":"2022-08-08T15:01:07.369Z","dependency_job_id":null,"html_url":"https://github.com/massimo-cassandro/symfony-bootstrap-form-theme","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/massimo-cassandro%2Fsymfony-bootstrap-form-theme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/massimo-cassandro%2Fsymfony-bootstrap-form-theme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/massimo-cassandro%2Fsymfony-bootstrap-form-theme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/massimo-cassandro%2Fsymfony-bootstrap-form-theme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/massimo-cassandro","download_url":"https://codeload.github.com/massimo-cassandro/symfony-bootstrap-form-theme/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234897368,"owners_count":18903646,"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":["bootstrap","bootstrap-4","checkboxes","form-theme","forms","single-checkboxes","symfony","twig","twig-templates","user-experience","user-interface"],"created_at":"2024-09-27T16:20:59.343Z","updated_at":"2025-10-01T21:30:20.239Z","avatar_url":"https://github.com/massimo-cassandro.png","language":"Twig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Symfony Bootstrap 4 Form Theme\n\n**This repository has been archived, form theme and scripts are now available at: \u003chttps://github.com/massimo-cassandro/twig-utilities\u003e and \u003chttps://github.com/massimo-cassandro/form-utilities\u003e**\n\n\nA [Bootstrap](https://getbootstrap.com/) 4 Form Theme for [Symfony](https://symfony.com/) 3, 4 and 5.\n\nv.2 - Oct 2020\n\nFor a complete lookup to all widgets and parameter take a look at \u003chttps://massimo-cassandro.github.io/symfony-bootstrap-form-theme/\u003e: it is a static page generated by the html produced by the test app and can be viewed without installing Symfony or anything else.\n\n\n## Quick install\n\nIf you don't need the whole test application, you can only download the files located in the `dist` folder, that contains the js and scss files and `bs4_form_layout.html.twig`.\n\nYou can also install them in your project using npm:\n\n```\nnpm i --save --only=prod @massimo-cassandro/symfony-bootstrap-form-theme\n```\n\n## Using the form theme\n\n* Add the `/dist/scss/_forms.scss` file to your scss (after Bootstrap css). Change default options if necessary.\n\n\u003eIn the demo page, `_forms.scss` is bundled within the `public/assets/sf-bs4-form-test.scss` file.\n\n* If you want to use the multiselect widget, add the `_forms-multiselect.js` and `_forms-multiselect.scss` files (both located in the `dist` folder) to your js and scss.\n\n\u003e In the demo page, both files are bundled within the main js and scss files.\n\n* Copy the `dist/bs4_form_layout.html.twig` file in your *template* folder\n* Modify your configuration file as explained below:\n\n**Symfony 5 `/config/packages/twig.yaml`**\n\n```yaml\ntwig:\n    form_themes:\n      - 'path/to/bs4_form_layout.html.twig'\n```\n\n\n**Symfony 3 `config.yml`**\n\n```yaml\n# Twig Configuration\ntwig:\n    paths:\n      - \"path/to/bs4_form_layout.html.twig\"\n```\n\n\n## Using the Symfony test application\n\nYou can clone the test app repository and run the form test app:\n* clone the repo and run composer to install Symfony.\n* run npm in the `public/assets` directory allowing dev dependencies (omit the `--only=prod` flag):\n\n```\nnpm i --save @massimo-cassandro/symfony-bootstrap-form-theme\n```\n\n* The main twig file is: `templates/index.html.twig`\n* The controller is: `src/Controller/DefaultController.php`\n* The form theme used for testing is: `templates/bs4_form_layout_WORK_COPY.html.twig`\n* js and scss source files are located in `/src` folder\n\nThe test page gives you detailed informations about all form widgets:\n\n![](docs/readme_files/sample.png)\n\nYou can easily modify the template, the js or the css and immediately test the result.\n\nRun `sh build.sh` to update the `dist` and `docs` folders, if you need.\n`build.sh` creates a static html file from the Symfony page. You may need the change the url of your local domain in `gulpfile.js`.\n\n### Codekit\n\nI've used [Codekit](https://codekitapp.com/) to build js and scss in the test app (the `assets/config.codekit3` file contains the project configuration), anyway to can easily switch to another tool.\n\n## Symfony Widgets Reference\n\n### General\n\n* The `help` parameter allows you to add custom help text. It adds a `div.form-help-text` element to the rendered markup that contains the help string (HTML can be used). The `form-help-text` class is defined in `_forms.scss`.\n\n```twig\n{{ form_row(form.xxxx, {\n  \"help\": \"Help text\"\n}) }}\n```\n\n```markup\n\u003cdiv class=\"form-group\"\u003e\n  \u003c!-- ... --\u003e\n  \u003cdiv class=\"form-help-text\"\u003e\n    Help text\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\n* The `disabled: true` parameter adds a `disabled` class to the group container element (in addition to the `disabled` attribute of the field); this allows you to stylize the whole field group.\n\n```twig\n{{ form_row(form.xxxx, {\n  disabled: true\n}) }}\n```\n\n```markup\n\u003cdiv class=\"form-group disabled\"\u003e\n  \u003c!-- ... --\u003e\n\u003c/div\u003e\n```\n\n\n* A new `params` parameter allows you to change some behaviour of the widgets. It is a json-like element whose sub-parameters changed depending on the widget used. You can find the whole list of parameters below. Take also a look at the [sample page](https://massimo-cassandro.github.io/symfony-bootstrap-form-theme/).\n\n```twig\n{{ form_row(form.xxxx, {\n  params: {\n    bs_custom_control: true\n  }\n}) }}\n```\n\n#### Parameters\n\n* **`container`**: generates a `.form-group` div or fieldset (if the element is a collection) wrapping the form element\n* **`container_class`**: add a custom class to the container element\n* **`collection_container`**: specify if a container element must be added for collecions\n* **`before`** and **`after`**: markup for input groups elements (see examples)\n* **`raw_label`**: if true, allows using html for labels (default false)\n* **`top_label`**: single checkboxes only, put the label at the top of the element\n* **`bs_custom_control`**: if true, activates Bootstrap custom controls (default false, see examples)\n* **`inline`**: checkboxes and radio buttons only, if true disposes elements inline (default false)\n* **`no_items_mes`**: collections only, message to be displayed if the Choice array is empty (see examples)\n* **`multiselect`**: collection only, generates a multiselect element\n* **`button_class`**: multiselect only, class for button element (default: btn-multiselect, defined in _forms.scss)\n* **`menu_class`**: multiselect only, class for menu element\n* **`columns`**: collections only, activates a multicolumns layout (see examples)\n\n\n### Checkboxes\n\n#### Single checkboxes\n\n* The default behaviour generate the Bootstrap default stacked markup wrapped into a `.form-group` container:\n\n```markup\n\u003cdiv class=\"form-group\"\u003e\n  \u003cdiv class=\"form-check\"\u003e\n    \u003cinput type=\"checkbox\"\n      id=\"custom-id\"\n      name=\"form[checkboxField2]\"\n      class=\"form-check-input\"\n      value=\"1\"\u003e\n    \u003clabel for=\"custom-id\"\u003e\n      Checkbox label\n    \u003c/label\u003e\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\n* You can avoid the `.form-group` container using the `params.container` parameter. Note however that any `help` parameter will be ignored, as it is related to the presence of the container:\n\n```twig\n{{ form_row(form.xxxx, {\n  \"params\": {\n    \"container\": false\n  }\n}) }}\n```\n\n* A single checkbox with label on top, can be obuained thru the `top_label` option. This option requires the `.form-group`, therefore the `params.container` is always forced to true.\n\n```twig\n{{ form_row(form.xxxx, {\n  \"params\": {\n    \"top_label\": true\n  }\n}) }}\n```\n\n* Custom checkbox control can be activated using the `params.bs_custom_control` parameter:\n\n```twig\n{{ form_row(form.xxxx, {\n  \"params\": {\n    \"bs_custom_control\": true\n  }\n}) }}\n```\n\n* Custom checkbox controls use `::before` and `::after` pseudo-elements, which makes it impossible to use the `::before` pseudo-element used for styling required fields' labels. For this reason, the required parameter, if associated with a custom-checkbox, generates a `\u003cspan class=\"required\"\u003e` element placed after the `label` element. Therefore, in this case, the asterisk for required fields is located after the label string and not before:\n\n```markup\n\u003cdiv class=\"custom-control custom-checkbox\"\u003e\n  \u003cinput type=\"checkbox\" ... \u003e\n  \u003clabel...\u003e...\u003c/label\u003e\n  \u003cspan class=\"required\"\u003e\u003c/span\u003e\n\u003c/div\u003e\n```\n* Actually, custom checkbox is incompatible with the `params.container` and `params.top_label` options, therefore they will be ignored even if they are setted to true. For the same reason, the `help` parameter will not take effect with custom checkbox, as it is related to the `.form-group` container.\n\n#### Multiple checkboxes\n\nMultiple checkboxes are element rendered by the `ChoyceType` type (https://symfony.com/doc/current/reference/forms/types/choice.html) with 'expanded' =\u003e true, 'multiple' =\u003e true options.\n\nThe **multiple columns** option requires a scss file included in my [m-utilities](https://github.com/massimo-cassandro/m-utilities) package.\n\nAfter downloaded the package, you need to add the respoinsive columns file to your scss:\n\n```scss\n@import 'path/to/node_modules/m-utilities/sass_utilities/bs4_responsive_columns';\n```\n\nSee the [`_forms.scss`](/symfony-bootstrap-form-theme/blob/master/web/public/forms/_forms.scss) file and [test result page](https://massimo-cassandro.github.io/symfony-bootstrap-form-theme/#multiple_cboxes_multi_columns) for info and examples.\n\nTake a look to the [test result page](https://massimo-cassandro.github.io/symfony-bootstrap-form-theme/#multiple_checkboxes) for detailed info.\n\n### Radios\n\nRadio buttons options are the same of checkboxes.\n\n### Multiselect\nMultiple checkboxes and radio button can be displydes as a dropdown using the `multiselect` option.\n\nThis option is inspired by the \u003ca href=\"http://davidstutz.de/bootstrap-multiselect/\"\u003eBootstrap Multiselect plugin\u003c/a\u003e, and offers a way to arrange in a more compact way multiple elements.\n\nFor usability reasons, it should not be used with a large number of items.\n\nTo activate this option set `params.multiselect` to `true` for default settings, or set placeholder and specific classes for menu and buttons as described in [Bootstrap docs](https://getbootstrap.com/docs/4.4/components/dropdowns/):\n\n```twig\n{{ form_row(form.xxxx, {\n  \"params\": {\n    \"multiselect\": true\n  }\n}) }}\n\n{{ form_row(form.xxxx, {\n  \"params\": {\n    \"multiselect\": {\n        placeholder: 'Select an option'\n        button_class: '...',\n        menu_class: '...'\n    }\n  }\n}) }}\n```\nThis option needs some [Bootstrap JS components](https://getbootstrap.com/docs/4.4/components/dropdowns/#overview), [Popper.JS](https://popper.js.org/) and [jQuery](https://jquery.com/).\n\nIn addition, the `_forms.js` script is needed.\n\n### Select elements\n\n* Select elements have `custom-select` class (\u003chttps://getbootstrap.com/docs/4.4/components/forms/#select-menu\u003e) by default, this behaviour can be changed using the `params` element of `form_row`\n\n### Input groups\n\nThis option allows to add text, buttons, or button groups on either side of textual inputs, selects, or file inputs.\n\nAdd a `before` and/or an `after` parameter to the `params` option to generate an input group.\n\nLook at the [test page](https://massimo-cassandro.github.io/symfony-bootstrap-form-theme/#input_groups) for detailed info and examples\n\n```twig\n{{ form_row(form.xxxx, {\n  \"params\": {\n    \"before\": [\n      {\n        \"type\": \"text\",\n        \"content\": \"$\"\n      }\n    ],\n    \"after\": [\n      {\n        \"type\": \"text\",\n        \"content\": \".00\"\n      }\n    ]\n  }\n}) }}\n```\n\n## TODO\n* readonly checkboxes\n* check bootstrap validation markup\n* errors\n* custom validity\n* Grouped stacked checkboxes\n* progress?\n* buttons?\n* date interval?\n* css for sizing classes\n* range: current value label, step labels\n* Option for adding custom classes to fieldset or div containers\n* Option to have help text printed at bottom of radio buttons or multiple checkboxes\n\n\n## Reference\n* \u003chttps://symfony.com/doc/current/form/form_customization.html\u003e\n* \u003chttps://symfony.com/doc/3.4/form/form_themes.html\u003e\n* \u003chttps://symfony.com/doc/3.4/forms.html\u003e\n* \u003chttps://symfony.com/doc/current/reference/forms/types.html\u003e\n* \u003chttps://symfony.com/doc/3.4/form/rendering.html\u003e\n* \u003chttps://symfony.com/doc/3.4/reference/forms/twig_reference.html\u003e\n* \u003chttps://symfony.com/doc/3.4/form/bootstrap4.html\u003e\n* \u003chttps://getbootstrap.com/docs/4.4/components/forms/\u003e\n* \u003chttps://getbootstrap.com/docs/4.4/components/input-group/\u003e\n* \u003chttps://getbootstrap.com/docs/4.4/components/buttons/\u003e\n\n\n## Changelog\n\n### v.2.1 / Nov 2020\n* Implemented `aria-describedby` attribute for help text ([issue #2](https://github.com/massimo-cassandro/symfony-bootstrap-form-theme/issues/2))\n* Inline radios and checkboxes fix\n* Option for using html strings for labels\n\n### v.2 / Oct 2020\n* Environment switched to Symfony 5\n* All js scripts rearranged as ES modules\n\n\n### v.1 / Sep 2019\n* First release built on Symfony 3\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmassimo-cassandro%2Fsymfony-bootstrap-form-theme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmassimo-cassandro%2Fsymfony-bootstrap-form-theme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmassimo-cassandro%2Fsymfony-bootstrap-form-theme/lists"}