PHPackages nomensa/form-builder - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. nomensa/form-builder ActiveLibrary[Utility & Helpers](/categories/utility) nomensa/form-builder ==================== v0.52.0(6y ago)51.5k5[1 PRs](https://github.com/nomensa/FormBuilder-Laravel/pulls)MITPHPPHP >=7.1.3 Since Jan 23Pushed 3y ago6 watchersCompare [ Source](https://github.com/nomensa/FormBuilder-Laravel)[ Packagist](https://packagist.org/packages/nomensa/form-builder)[ RSS](/packages/nomensa-form-builder/feed)WikiDiscussions master Synced 3d ago READMEChangelogDependencies (2)Versions (35)Used By (0) FormBuilder - A Laravel package =============================== [](#formbuilder---a-laravel-package) - [The Business Case](#the-business-case) - [The Developer Case](#the-developer-case) - [The Accessibility Case](#the-accessibility-case) - [Form states](#form-states) - [Display Mode](#display-mode) - [Getting started](#getting-started) - [Contributors](#contributors) - [Artisan commands](#artisan-commands) - [Field types](#field-types) - [Custom Components](#custom-components) - [Cool edge cases](#cool-edge-cases) - [Database Model Tables](#database-model-tables) The Business Case ----------------- [](#the-business-case) This package reduces time and cost of application development by providing solutions to the following requirements: - The business process involves filling out many, long, complicated forms. - Form "ownership" is passed between different user roles. - Forms move through "states" during their life-cycle with different fields becoming editable/visible. - Versioning - The questions on a form may change at a future date, but the answers recorded against them must remain true to what the question was at the time the form was filled out. - Reporting across multiple versions of a form. In the case where a few questions on a form have changed, it must be possible to produce reports containing both versions. The Developer Case ------------------ [](#the-developer-case) FormBuilder aims to reduce complexity and repetition for the developer by providing the following features: - The ability to define long complicated forms as a JSON structure and letting the application markup the HTML. - The ability to choose CSS class names applied to elements in markup. - Artisan commands to create the required database migrations, models, controllers and to create new form schemas. The Accessibility Case ---------------------- [](#the-accessibility-case) Although ultimate responsibility for making an interface accessible lies with the developer, FormBuilder does not stand in the way. Current standards have been followed when defining how the forms are markedup but provisions to override all parts of the system are in place should an edge case need to be implemented. Form "states" ============= [](#form-states) Each form can have multiple states and each field in the form can be marked-up in 1 of 4 ways in each state. The possible values are: - editable - *visible and editable* - readonly - *visible but cannot be edited* - hidden - *not visible but editable (eg. Via custom JavaScript)* - ignore - *not included in the form markup* They can be imagined on a 2x2 matrix of editability and visibility. ``` --------------------- ^ | hidden | editable | | |--------|----------| editability | ignore | readonly | --------------------- visibility --> ``` Let's use a school homework assignment as a simple example. Imagine a simple quiz form is started by a student who has to fill 3 answer fields. After submission, the form is passed to a teacher, those first 3 answer fields now become read-only and a 4th field called 'feedback' is revealed that only the teacher can fill. When the teacher submits the form, all 4 fields become read-only and neither student nor teacher can edit the fields but both can view them in a read-only state. In the above example the form has 3 states: 1. The way the fields are displayed for the student 2. The way the fields are displayed for the teacher 3. The way the fields are displayed for the final state They are set for each field via an object of key-pair values in the schema. The states are given key names, a human description relevant to that form, and the value is how the particular field is displayed. This is how the states object might be set for the first answer field: ``` "states": { "student-answering": "editable", "teacher-marking": "readonly", "final-view": "readonly" } ``` ### Legacy state values [](#legacy-state-values) The codebase currently contains some support for a number of deprecated values. These use-case-specific values are legacy of the application that FormBuilder was original developed for and will not be supported in future releases. For reference only and should not be used: - editable\_if\_true\_else\_ignore - editable\_if\_true\_else\_readonly - hidden-for-learner - readonly\_for\_owner Display Mode ============ [](#display-mode) Display mode describes how the user is interacting with the form during the request. It can only be 1 of the 4 CRUD verbs: *creating, reading, updating, deleting.* - You can set it on an instance of FormBuilder using the `->setDisplayMode(string $verb)` method. - You can check if FormBuilder is in a particular display mode using `->isDisplayMode(string $verb)` method which returns a boolean. - You can get it using the `->getDisplayMode()` method. It's *mostly* implemented simply as an enumerated variable that can be checked to determine things like what button or wording is displayed in a custom component *(eg. Does the button say "Create" or "Update").* However, one built-in use of display mode is when fields are being rendered. If a form is being rendered in the display mode *reading* then fields that are 'editable' in the current state are overridden to be 'readonly'. *(Note: The opposite affect is not applied, readonly fields are not forced to editable if the display mode is 'updating').* Getting started --------------- [](#getting-started) Installation is easy with the following steps: Add the package to `composer.json` using the install command: ``` $ composer require nomensa/form-builder ``` Add the service provider in `config/app.php` file: ``` 'providers' => [ ... Nomensa\FormBuilder\FormBuilderServiceProvider::class, ]; ``` Add aliases to `config/app.php` file: ``` 'aliases' => [ ... 'FormBuilder' => Nomensa\FormBuilder\FormBuilder::class, 'CSSClassFactory' => Nomensa\FormBuilder\BootstrapCSSClassFactory::class, ], ``` - Run `php artisan formbuilder:install` - Add routes declaration - Run db migrations to rebuild database schema - Include the FormBuilder JavaScript script Creating a basic first form --------------------------- [](#creating-a-basic-first-form) Run the artisan command to create a form, let's call it *"My First Form"*. ``` $ php artisan formbuilder:make-form MY-FORM "My First Form" ``` Now open `/app/FormBuilder/Forms/MY-FORM/schema.json` in your editor and paste in the following code: ``` [ { "type": "dynamic", "rows": [ { "editing_instructions": "Welcome to my great form." }, { "columns": [ { "field": "first-form-name", "label": "Name", "type": "text", "helptext": "What people call you", "states": { "state-1": "editable", "state-2": "readonly" } } ] }, { "title": "Time", "columns": [ { "field": "first-form-love-kittens", "label": "I love kittens", "type": "checkbox", "states": { "state-1": "editable", "state-2": "readonly" } } ] } ] } ] ``` Now we will create an instance of FormBuilder in our controller, with this form loaded in: ```