{"id":24063342,"url":"https://github.com/believer-ufa/prettyforms","last_synced_at":"2025-04-23T16:28:02.988Z","repository":{"id":23453388,"uuid":"26817222","full_name":"believer-ufa/prettyforms","owner":"believer-ufa","description":"Helps to make a simple and easy client-server validation for forms","archived":false,"fork":false,"pushed_at":"2018-02-24T10:49:19.000Z","size":2598,"stargazers_count":51,"open_issues_count":2,"forks_count":8,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-09T12:03:29.970Z","etag":null,"topics":["javascript"],"latest_commit_sha":null,"homepage":"http://believer-ufa.github.io/prettyforms/","language":"JavaScript","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/believer-ufa.png","metadata":{"files":{"readme":"readme-en.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}},"created_at":"2014-11-18T16:02:29.000Z","updated_at":"2022-04-18T15:00:41.000Z","dependencies_parsed_at":"2022-08-22T01:10:14.819Z","dependency_job_id":null,"html_url":"https://github.com/believer-ufa/prettyforms","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/believer-ufa%2Fprettyforms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/believer-ufa%2Fprettyforms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/believer-ufa%2Fprettyforms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/believer-ufa%2Fprettyforms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/believer-ufa","download_url":"https://codeload.github.com/believer-ufa/prettyforms/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250470487,"owners_count":21435811,"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":["javascript"],"created_at":"2025-01-09T09:37:35.627Z","updated_at":"2025-04-23T16:28:02.973Z","avatar_url":"https://github.com/believer-ufa.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"PrettyForms.js\n===========\n\nA small library, through which you can easily make the form validation on the client and server sides. Originally set up to work with [Twitter Bootstrap](http://getbootstrap.com).\n\nDepends: jQuery.\n\n[Screencast of the library](demo.gif)\n\n## Installation\nYou can download a zip-file with the library, or set it through the bower:\n```shell\nbower install prettyforms --save\n```\n\n*Tip:* to further increase the usability of your site, you can also connect the [SweetAlert](https://github.com/t4t5/sweetalert) library, which will be automatically used by Prettyforms.\n\n## The algorithm of the library:\n1. The user fills the fields and clicks a submit button. Library validates all data and, if all goes well, it collects all the data and send the form POST request to server and expects a JSON-answer in a special format.\n2. The server receives the request, conducting additional validation of the data is already on his side. If there are errors in the validation server, it returns to the client a specially crafted JSON-response containing the command to display the server validation error information about the fields and they contain mistakes.\n3. If the data have been validated successfully, the server performs the necessary operations and returns JSON-response describing the action that the client machine must perform after a successful transaction processing.\n\nThat is, the server always meet a certain set of commands for the browser, and the browser simply executes these commands on a client machine. This is the algorithm of the library.\n\n## Laravel 5\n\nFor Laravel, a special component that greatly expands its features and uses for client validation the current library. For more details you can read about it on the [page of this component](https://github.com/believer-ufa/prettyforms-laravel).\n\n## Example of use\n\nConnect the JS-file `prettyforms.js` to the page, and add an attribute validation `data-validation=\"rules;to;validation\"` a list of validation rules to all fields of your form. After adding the rules, the form fields will automatically become a library for validation PrettyForms. If the data will be invalid, the library will not allow the form to go to the server. This is the minimum functional library without server binding.\n\nIn order to connect the library to work with the server, add to your standard submit button class `senddata`, by which clicks the button will be captured and processed by library. Now the library will not only produce customer validation, and will be responsible for sending data to the server and handle the response.\n\nExample forms for Bootstrap-validation framework with attributes:\n\n```html\n\u003cform class=\"form-horizontal\" role=\"form\" method=\"POST\" action=\"/register\"\u003e\n    \u003ch1 class=\"form-signin-heading\"\u003eRegistration\u003c/h1\u003e\n    \u003cdiv class=\"form-group\"\u003e\n        \u003clabel for=\"inputEmail3\" class=\"col-sm-2 control-label\"\u003eEmail\u003c/label\u003e\n        \u003cdiv class=\"col-sm-10\"\u003e\n            \u003cinput type=\"email\"\n                   class=\"form-control\"\n                   id=\"inputEmail3\"\n                   name=\"email\"\n                   data-validation=\"notempty;isemail\"\n                   placeholder=\"Enter your email\"\u003e\n        \u003c/div\u003e\n    \u003c/div\u003e\n    \u003cdiv class=\"form-group\"\u003e\n        \u003clabel for=\"inputPassword3\" class=\"col-sm-2 control-label\"\u003ePassword\u003c/label\u003e\n        \u003cdiv class=\"col-sm-10\"\u003e\n            \u003cinput\n                type=\"password\"\n                class=\"form-control\"\n                id=\"inputPassword3\"\n                name=\"password\"\n                data-validation=\"notempty;minlength:6\"\n                placeholder=\"Your password\"\u003e\n        \u003c/div\u003e\n    \u003c/div\u003e\n    \u003cdiv class=\"form-group\"\u003e\n        \u003clabel for=\"inputPassword4\" class=\"col-sm-2 control-label\"\u003eConfirm password\u003c/label\u003e\n        \u003cdiv class=\"col-sm-10\"\u003e\n            \u003cinput type=\"password\"\n                   class=\"form-control\"\n                   id=\"inputPassword4\"\n                   name=\"password_retry\"\n                   data-validation=\"notempty;passretry\"\n                   placeholder=\"Confirm password suddenly make a mistake? We will check it.\"\u003e\n        \u003c/div\u003e\n    \u003c/div\u003e\n    \u003cdiv class=\"form-group\"\u003e\n        \u003cdiv class=\"col-sm-offset-2 col-sm-10\"\u003e\n            \u003cdiv class=\"btn btn-default senddata\"\u003eRegister\u003c/div\u003e\n        \u003c/div\u003e\n    \u003c/div\u003e\n\u003c/form\u003e\n```\n\n## Field validators\n\nValidation rules are separated by `;`, the parameters for the rule passed through a `:`.\nAn example of a correct list of rules contains two rules, one of them with a parameter: `\"notempty;minlength:6\"`\n\n| Name | Description | Option |\n| ------------- | ------------- | --------- |\n| notempty | Field can not be empty. If a set of radio-input, then one of them must be marked. | No opts |\n| minlength | Not less than {%} characters | Number of characters |\n| maxlength | Not more than {%} characters | Number of characters |\n| hasdomain | The address must start with the correct domain ({%}) | Domain |\n| isnumeric | The field can only contain numbers | No opts |\n| isemail | There should be a valid E-Mail | No opts |\n| isdate | The field must contain the date | No opts |\n| isphone | The field should contain a telephone number | No opts |\n| minint | Minimum number entered {%} | number |\n| maxint | Maximum number entered {%} | number |\n| intonly | You can enter only the number of | Number |\n| passretry | Must be equal to the password field | field name with password, the default \"password\" |\n| checked | Check that checkbox-element is checked. Used to the need to agree to the terms of the license, for example. | No opts |\n\n#### Adding a custom validator rule\nYou can easily add your own validators, using a similar example:\n```javascript\n$(window).load(function(){\n  PrettyForms.Validator.setValidator('needempty', 'The field should be empty!', function(element, value, param){\n      // needempty - validator name\n      // the second option - error message\n      // third - is validation function itself, which passed three parameters: jQuery-element, value of this element, and validator parameters if it was referred to the properties of the validation\n      return value === '';\n  });\n});\n```\n\n#### Additional attributes of validation\nThe library also allows you to add to the fields some additional attributes that govern the behavior of the test field.\n\n| Attribute | Description | Required?|\n| ------------- | ------------- |-------------|\n| data-dontsend=\"true\"  | Disables verification of the field and sending it to the server | No |\n\n\n## Attributes of submit button\nButton, clicking on which generates a sending form can also have several additional attributes that explain where data should be sent from which DOM-element has to be collected, and some other forms of behavior characteristics. If the attributes have not been specified, the data will be taken from your form.\n\n| Attribute | Description | Required? |\n| ------------- | ---------|--------------|\n| data-input  | jQuery-selector element from which data will be collected to send to the server | No, unless otherwise indicated, it will attempt to pull the data from the form, which contains the button. If the form has not been found, a request is sent with no data. |\n| href or data-link  | The address to which to send the data  | No, the default data will be taken from the `action` attribute form, and if it's empty, they will be sent to the current URL of the page |\n| data-clearinputs=\"true\" | Clear form fields after a successful request?  | No require |\n| class=\"... really\"  | Lets ask before sending data. If the [SweetAlert](https://github.com/t4t5/sweetalert) is connected to the site, it will be used. | No require |\n| data-really-text=\"\"  | The question text, the default is taken from the `PrettyForms.messages.really` | No require |\n| data-really-text-btn=\"\"  | Text button, clicking on which will cause the action. By default, the text is taken from `PrettyForms.messages.really_agree` | No require |\n\n## Validation on server\nValidation on the server must do the framework with which you are working. Library expects a response object whose keys - the names of commands and values - a command parameters. So, the command for displaying validation errors called `validation_errors`, as well as its parameters must be specified is another object whose keys are the field names and values as they shall contain one-dimensional arrays with texts validation errors, which were not passed.\n\nIn other words, the logic would be similar to the following: if the field validation fails, the server returns a JSON-response command to display errors. If the validation is successful, the server returns a JSON-response with other commands, for example, redirect user to a page message on successful registration. An example of responding to PHP:\n```php\n// Validate the data, stores the result in the validation of $validation_success\n\nif ($validation_success === false) {\n    // The data is invalid\n    $json_response = [\n        'validation_errors' =\u003e [\n            'field_name' =\u003e array('error_message_1','error_message_2'),\n            'second_field_name' =\u003e array('error_message')\n            // etc.\n        ]\n    ]);\n} else {\n\n    // Here we write the code you need to perform on a server..\n\n    // And prepare a response to the client teams:\n    $json_response = [\n        'redirect' =\u003e '/registration_success'\n    ];\n}\n\n// Returns the response to the client\necho json_encode($json_response);\n```\n\n## Command handlers from the server\nInitially, the library supports the following commands that you can send it to the server:\n\n| Team | Description | Options |\n| ------------- | ---------|--------------|\n| `validation_errors`  | Display validation errors  | The object where the keys - the names of the fields, values - array errors. Or just a string, then it will be displayed next to the submit button  |\n| `redirect`  | Perform redirect the user to another page  | URL of the page |\n| `refresh` | Reload current page  | No opts |\n| `nothing`  | Do nothing | No opts |\n| `success`  | Display the message about success | `{ title: 'Title', text: 'Message text'  }` |\n| `warning`  | Display the message about danger | `{ title: 'Title', text: 'Message text'  }` |\n| `info`  | Display the informative message | `{ title: 'Title', text: 'Message text'  }` |\n| `error`  | Display an error message | `{ title: 'Title', text: 'Message text'  }` |\n\nFor commands `success`,` warning`, `info` and` error` do the following: if your site have a [SweetAlert](https://github.com/t4t5/sweetalert) library, it will be involved in their implementation.\n\nExample of adding your own event handler:\n```javascript\nPrettyForms.Commands.registerHandler('command_name', function (data) {\n  // We do everything here that I want to become.\n  // data - an object with data that is sent to us server\n});\n```\n\n## Format of client-server communication protocol\nThe client library expects the server response in the following format:\n```javascript\n{\n  command_name_1 : \"params\",\n  command_name_2 : \"params\"\n}\n```\n\nTo display validation errors, you must send the following response to the client:\n```javascript\n{\n  validation_errors: {\n    form_field_1: [\"the text of the error №1\", \"the text of the error №2\"],\n    form_field_2: [\"the text of the error №1\", \"the text of the error №2\", \"the text of the error №3\"]\n  }\n}\n```\n\n## API\n\nYou can use some of the methods of the library in your own applications.\n\n`PrettyForms.Validator.validate(element)`\n\u003e Perform validation of a form. Parameter: jQuery-element.\n\n`PrettyForms.getInputData(elements_container)`\n\u003e Collect data from said container, simultaneously checking them all validator. If the validation fails, it returns false instead of the data. Parameter: jQuery-element of which will be collected in all fields.\n\n`PrettyForms.getInputsList(elements_container)`\n\u003e Pull out all the INPUT of said container. Parameter: jQuery-selector.\n\n`PrettyForms.sendData(url, mass, input_container_for_clear, input)`\n\u003e Send the data to the specified URL and process the response. parameters:\n\u003e - URL, which will be sent details\n\u003e - The data to be sent to the URL\n\u003e - jQuery-element - the container for cleaning INPUT or false\n\u003e - jQuery-element - the button, which was committed by a click. It will be made inactive at the time of the request.\n\n## Advanced Setup\n\nPrettyForms originally tuned for sites created based on the Twitter Bootstrap, but you can easily replace it with a template with error messages on their own, redefining three variables in the object \"PrettyForms.templates\".\n\nDuring the validation process, the library will automatically create containers for error messages if they are not on the form. For each field, just below it, the container will be created, based on a template located in the `PrettyForms.templates.element_validations_container`. At the time of writing this wiki, the pattern has the form:\n```html\n\u003cdiv style=\"display:none;margin-top:10px\" id=\"validation-error-{%}\" class=\"alert alert-danger\" role=\"alert\"\u003e\u003c/div\u003e\n```\nThis container will be placed error messages when they occur during the test fields. You can place data fields within its own form, in those places where you want, if you do not have automatic generation approached for any reason. Just add these containers for each field on the form, with an attribute `id=\"validation-error-{field_name}\"`. For example, if you have on the page `\u003cinput name=\"email\"/\u003e`, then it can be created anywhere in the container error: `\u003cdiv style=\"display:none;\" id=\"validation-error-email\" class=\"alert alert-danger\" role=\"alert\"\u003e\u003c/div\u003e `. Now the library will find your container and place the error messages in it.\n\nAlso, the library will automatically generate a container for common error messages validation. He will be placed immediately before the submit button, he is taken from the template variable `PrettyForms.templates.form_validation_messages`. At the time of writing wiki template is as follows:\n```html\n\u003cdiv style=\"margin-bottom:10px\" class=\"validation-errors alert alert-danger\"\u003e\u003c/div\u003e\n```\nYou can also place the container by hand in the place form where you will be most comfortable. To help find your container, add it to a class `.validation-errors`.\n\n## Known Issues\n\nOne of the frequent problems - it is difficult to obtain the contents of those fields, which applied some additional plug-like or Chosen CKEDitor. Specifically, for these two plug-ins in the library has built-in support, and she gets the correct values of the fields associated with these plug-ins, but in the world there are thousands of other plug-ins, with which it can work properly. Keep in mind when using this library.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeliever-ufa%2Fprettyforms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeliever-ufa%2Fprettyforms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeliever-ufa%2Fprettyforms/lists"}