{"id":18870407,"url":"https://github.com/sebastiansulinski/ssd-form","last_synced_at":"2025-04-14T15:21:22.974Z","repository":{"id":57368862,"uuid":"53877599","full_name":"sebastiansulinski/ssd-form","owner":"sebastiansulinski","description":"jQuery plugin to handle form validation and submission","archived":false,"fork":false,"pushed_at":"2019-08-23T07:41:38.000Z","size":72,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-28T04:11:33.321Z","etag":null,"topics":["jquery-form","jquery-plugin","jquery-validation"],"latest_commit_sha":null,"homepage":null,"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/sebastiansulinski.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":"2016-03-14T17:39:10.000Z","updated_at":"2020-07-06T19:51:24.000Z","dependencies_parsed_at":"2022-09-15T15:30:58.106Z","dependency_job_id":null,"html_url":"https://github.com/sebastiansulinski/ssd-form","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiansulinski%2Fssd-form","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiansulinski%2Fssd-form/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiansulinski%2Fssd-form/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiansulinski%2Fssd-form/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sebastiansulinski","download_url":"https://codeload.github.com/sebastiansulinski/ssd-form/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248904623,"owners_count":21180836,"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":["jquery-form","jquery-plugin","jquery-validation"],"created_at":"2024-11-08T05:20:03.585Z","updated_at":"2025-04-14T15:21:22.944Z","avatar_url":"https://github.com/sebastiansulinski.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simple form validation / submission jQuery plugin\n\n## Demo\n\n[SSD Form Demo](http://ssd-form.ssdtutorials.com/)\n\n## Installation\n\n```\nnpm i ssd-form\n```\n\n## Set up\n\n```html\n\u003cdiv data-form-wrapper\u003e\n\n    \u003cform\n        method=\"post\"\n        action=\"./submit.php\"\n        data-ajax-form\n        data-success-behaviour=\"fadeOutShowMessage\"\n        novalidate\n    \u003e\n\n        \u003clabel for=\"title\"\u003e\n            \u003cspan data-validation=\"title\"\u003e\n                \u003cspan data-case=\"required\"\u003ePlease select your title\u003c/span\u003e\n                \u003cspan data-case=\"value_is\"\u003eSelected value must be Mr\u003c/span\u003e\n            \u003c/span\u003e\n        \u003c/label\u003e\n\n        \u003cselect\n            name=\"title\"\n            id=\"title\"\n            data-validate=\"required|value_is:1\"\n            \u003e\n            \u003coption value=\"\"\u003eSelect title\u003c/option\u003e\n            \u003coption value=\"1\"\u003eMr\u003c/option\u003e\n            \u003coption value=\"2\"\u003eMrs\u003c/option\u003e\n            \u003coption value=\"3\"\u003eMiss\u003c/option\u003e\n            \u003coption value=\"4\"\u003eMs\u003c/option\u003e\n        \u003c/select\u003e\n\n        \u003clabel for=\"first_name\"\u003e\n            \u003cspan data-validation=\"first_name\"\u003e\n                \u003cspan data-case=\"required\"\u003ePlease provide your first name\u003c/span\u003e\n                \u003cspan data-case=\"min\"\u003eLength must be at least 3 characters\u003c/span\u003e\n                \u003cspan data-case=\"response\"\u003eValidation triggered by ajax response\u003c/span\u003e\n            \u003c/span\u003e\n        \u003c/label\u003e\n\n        \u003cinput\n            type=\"text\"\n            name=\"first_name\"\n            id=\"first_name\"\n            data-validate=\"required|min:3\"\n            placeholder=\"Your first name *\"\n        \u003e\n\n        \u003clabel for=\"last_name\"\u003e\n            \u003cspan data-validation=\"last_name\"\u003e\n                \u003cspan data-case=\"required\"\u003ePlease provide your last name\u003c/span\u003e\n                \u003cspan data-case=\"min\"\u003eLength must be at least 3 characters\u003c/span\u003e\n            \u003c/span\u003e\n        \u003c/label\u003e\n\n        \u003cinput\n            type=\"text\"\n            name=\"last_name\"\n            id=\"last_name\"\n            data-validate=\"required|min:3\"\n            placeholder=\"Your last name *\"\n        \u003e\n\n        \u003clabel for=\"email\"\u003e\n            \u003cspan data-validation=\"email\"\u003e\n                \u003cspan data-case=\"required\"\u003ePlease provide your email address\u003c/span\u003e\n                \u003cspan data-case=\"email\"\u003eInvalid email address\u003c/span\u003e\n            \u003c/span\u003e\n        \u003c/label\u003e\n\n        \u003cinput\n            type=\"email\"\n            name=\"email\"\n            id=\"email\"\n            data-validate=\"required|email\"\n            placeholder=\"Your email address *\"\n        \u003e\n\n        \u003clabel for=\"password\"\u003e\n            \u003cspan data-validation=\"password\"\u003e\n                \u003cspan data-case=\"required\"\u003ePlease choose your password\u003c/span\u003e\n                \u003cspan data-case=\"password\"\u003eLength must be at least 6 characters, one capital letter and one number\u003c/span\u003e\n                \u003cspan data-case=\"confirmed\"\u003ePasswords do not match\u003c/span\u003e\n            \u003c/span\u003e\n        \u003c/label\u003e\n\n        \u003cinput\n            type=\"password\"\n            name=\"password\"\n            id=\"password\"\n            data-validate=\"required|password|confirmed\"\n            placeholder=\"Password\"\n        \u003e\n\n        \u003clabel for=\"password_confirmation\"\u003e\n            \u003cspan data-validation=\"password_confirmation\"\u003e\n                \u003cspan data-case=\"required\"\u003ePlease confirm your password\u003c/span\u003e\n                \u003cspan data-case=\"min\"\u003eLength must be at least 5 characters\u003c/span\u003e\n            \u003c/span\u003e\n        \u003c/label\u003e\n\n        \u003cinput\n            type=\"password\"\n            name=\"password_confirmation\"\n            id=\"password_confirmation\"\n            data-validate=\"required|password\"\n            placeholder=\"Password\"\n        \u003e\n        \n        \u003clabel\u003e\n            Please select delivery option\n            \u003cspan data-validation=\"delivery\"\u003e\n                \u003cspan data-case=\"radio\"\u003eYou must select one option\u003c/span\u003e\n            \u003c/span\u003e\n        \u003c/label\u003e\n\n        \u003clabel for=\"delivery-1\"\u003e\n            \u003cinput type=\"radio\" name=\"delivery\" id=\"delivery-1\" value=\"1\" data-validate=\"radio\"\u003e Option 1\n        \u003c/label\u003e\n        \u003clabel for=\"delivery-2\"\u003e\n            \u003cinput type=\"radio\" name=\"delivery\" id=\"delivery-2\" value=\"2\"\u003e Option 2\n        \u003c/label\u003e\n        \u003clabel for=\"delivery-3\"\u003e\n            \u003cinput type=\"radio\" name=\"delivery\" id=\"delivery-3\" value=\"3\"\u003e Option 3\n        \u003c/label\u003e\n\n        \u003clabel\u003e\n            \u003cspan data-validation=\"terms\"\u003e\n                \u003cspan data-case=\"checked\"\u003eYou must agree to our newsletter and conditions\u003c/span\u003e\n            \u003c/span\u003e\n        \u003c/label\u003e\n        \n        \n        \u003clabel\u003e\n            At least one option must be selected\n            \u003cspan data-validation=\"category\"\u003e\n                \u003cspan data-case=\"min\"\u003eYou must select at least one option\u003c/span\u003e\n            \u003c/span\u003e\n        \u003c/label\u003e\n\n        \u003clabel for=\"category-1\"\u003e\n            \u003cinput type=\"checkbox\" name=\"category[]\" id=\"category-1\" value=\"1\" data-validate=\"min:1\"\u003e Option 1\n        \u003c/label\u003e\n        \u003clabel for=\"category-2\"\u003e\n            \u003cinput type=\"checkbox\" name=\"category[]\" id=\"category-2\" value=\"2\"\u003e Option 2\n        \u003c/label\u003e\n        \u003clabel for=\"category-3\"\u003e\n            \u003cinput type=\"checkbox\" name=\"category[]\" id=\"category-3\" value=\"3\"\u003e Option 3\n        \u003c/label\u003e\n        \n\n        \u003clabel\u003e\n            Exactly one option must be selected\n            \u003cspan data-validation=\"type\"\u003e\n                \u003cspan data-case=\"min\"\u003eYou must select exactly one option\u003c/span\u003e\n                \u003cspan data-case=\"max\"\u003eYou must select exactly one option\u003c/span\u003e\n            \u003c/span\u003e\n        \u003c/label\u003e\n\n        \u003clabel for=\"type-1\"\u003e\n            \u003cinput type=\"checkbox\" name=\"type[]\" id=\"type-1\" value=\"1\" data-validate=\"min:1|max:1\"\u003e Option 1\n        \u003c/label\u003e\n        \u003clabel for=\"type-2\"\u003e\n            \u003cinput type=\"checkbox\" name=\"type[]\" id=\"type-2\" value=\"2\"\u003e Option 2\n        \u003c/label\u003e\n        \u003clabel for=\"type-3\"\u003e\n            \u003cinput type=\"checkbox\" name=\"type[]\" id=\"type-3\" value=\"3\"\u003e Option 3\n        \u003c/label\u003e\n        \n\n        \u003clabel for=\"terms\"\u003e\n            \u003cinput\n                type=\"checkbox\"\n                name=\"terms\"\n                id=\"terms\"\n                data-validate=\"checked\"\n            \u003e I agree to the terms and conditions\n        \u003c/label\u003e\n\n        \u003cinput\n            type=\"submit\"\n            class=\"button\"\n            value=\"SEND ENQUIRY\"\n            data-submit-trigger\n        \u003e\n\n        \u003cbutton\n            type=\"button\"\n            class=\"button hide\"\n            disabled\n            data-submit-pending\n        \u003e\n            \u003ci class=\"fa fa-spinner fa-spin\"\u003e\u003c/i\u003e PROCESSING\n        \u003c/button\u003e\n\n    \u003c/form\u003e\n\n    \u003cp data-confirmation\u003e\u003c/p\u003e\n\n\u003c/div\u003e\n```\n\nInclude the necessary styles for the plugin to work\n\n```html\n\u003clink href=\"assets/css/ssd-form.css\" rel=\"stylesheet\"\u003e\n```\n\nTo instantiate the form simply call it on the form\n\n```javascript\n$(function() {\n    $('form[data-ajax-form]').ssdForm();\n});\n```\n\n## Options\n\nThere are several options available\n\n```\n// form wrapper\ndataFormWrapper: 'data-form-wrapper',\n\n// confirmation element (if form behaviour shows confirmation)\ndataConfirmation: 'data-confirmation',\n\n// validation segment (wraps validation cases)\ndataValidationSegment: 'data-validation',\n\n// validation case (wraps each validation message for a given form element)\ndataValidationCase: 'data-case',\n\n// submit button\ndataSubmitTrigger: 'data-submit-trigger',\n\n// button that is shown when the form is being submitted (pending)\ndataSubmitPending: 'data-submit-pending',\n\n// class indicating that the given input's value\n// is to be fetched from CKEDITOR.instances\nclassCkEditor: 'editor',\n\n// class that hides pending button\nclassHide: 'hide',\n\n// class that shows validation case\nclassShow: 'show',\n\n// allows you to add more behaviours\nextendBehaviours: {},\n\n// allows you to add more validation rules\nextendValidationRules: {}\n\n// allows you to run custom behaviour on successful ajax response\npostAjaxSuccess: function(form, form_model, data) {}\n\n// allows you to run custom behaviour on failed ajax response\npostAjaxFailure: function(form, form_model, jqXHR, textStatus, errorThrown) {}\n\n// allows you to specify which attributes should be used\n// during data serialization instead of default 'name' attribute\n// example would be for instance 'data-field'\nserializeAttribute: null,\n\n// action that overwrites default behaviour\n// of the validated form submission\n// default one submits form using $.ajax()\n// and form 'method' and 'action' attributes\nactionMethod: function(form, form_model, success, error) {}\n```\n\n## Validation\n\nTo apply validation to a given element, apply `data-validate` attribute to it with the validation type. i.e.\n\n```\ndata-validate=\"required|min:3\"\n```\n\n### Validation options\n\n- `required` : input must have a value\n- `checked` : input must be checked\n- `radio` : input of type `radio` must have one option selected\n- `value_is:n` : input value must equal `n` (`value:10` would mean that value must equal 10)\n- `email` : input value must be a valid email address - regex /^[a-zA-Z0-9._\\-]+@[a-zA-Z0-9]+([.\\-]?[a-zA-Z0-9]+)?([\\.]{1}[a-zA-Z]{2,4}){1,4}$/\n- `password` : input value must match the following regex `/(?=.*\\d)(?=.*[a-z])(?=.*[A-Z]).{6,}/`\n- `min:n` : input value's length must be minimum of `n` characters (or for array types - number of items in array). i.e. `min:10` would mean that the value has to be at least 10 characters long / array has to have at least 10 items\n- `max:n` : input value's length must be maximum of `n` characters (or for array types - number of items in array). i.e. `max:10` would mean that the value has to be maximum 10 characters long / array must not have more than 10 items\n- `confirmed` : input must have a matching input with the same name and `_confirmation` appended and both have to have the same value i.e `password`  and `password_confirmation`\n- `regex` : input must match the regex associated with `data-regex`\n\n## Form submission\n\nForm will submit the input to the uri associated with its `action` attribute.\nIf response is to return any errors it should return them as json in the following format:\n\n```json\n{\n    \"first_name\": \"required\",\n    \"email\": \"invalid\"\n}\n```\n\nResponse keys represent the field (associated with `data-validation`) and value (or array of values) representing given case (associated with `data-case`).\n\nPlease note that if returned validation field contains array of cases, then only the first one will be displayed above the field.\n\nFor the validation to work, the response needs to return status code that would trigger `error` callback of the $.ajax() method - for instance `422` (please see example in submit.php).\n\n## Successful behaviour\n\nOnce the form has been processed successfully it will trigger one of the following methods, associated with the `data-success-behaviour` attribute:\n\n- `redirect` : redirects to a given url/i. Response needs to contain `redirect` entry `{ \"redirect\" : \"/confirmation\" }`\n- `reload` : reloads the page\n- `fadeOutShowMessage` : fades out the form and displays the message in its place. Response has to contain `message` entry `{ \"message\" : \"Your request has been processed successfully.\" }`\n- `fadeOutShowMessageRedirect` : fades out the form, displays the message and after 3 seconds redirects to a given url/i. Response needs to contain `message` and `redirect` entry `{ \"message\" : \"Your request has been processed successfully.\", \"redirect\" : \"/confirmation\" }`\n- `fadeOutShowMessageReload` : fades out the form, displays the message and after 3 seconds reloads the page. Response needs to contain `message` entry { \"message\" : \"Your request has been processed successfully.\" }`\n- `fadeOutShowMessageResetFadeIn` : fades out the form, displays the message, resets the form and fades it back in. Response needs to contain `message` entry `{ \"message\" : \"Your request has been processed successfully.\" }`\n- `callReplaceRemove` : makes ajax call and replaces and removes elements specified in the response.\n\n## Extending validation rules and form behaviours\n\nIf you'd like to add more validation rules, use the `extendValidationRules` option, which will extend the internal `ValidationRules` object. Each new method takes the `element` argument. `element.rules_collection` represents any value that's after the rules colon i.e. `min:5` would return `5`, `something:5,6,7` would return `5,6,7`:\n\n```javascript\n$('form[data-ajax-form]').ssdForm({\n\n    extendValidationRules: {\n\n        number_is: function(element) {\n\n            return Number(element.value) === Number(element.rules_collection);\n\n        }\n\n    }\n\n});\n\n\u003cinput\n    type=\"text\"\n    name=\"year\"\n    id=\"year\"\n    data-validate=\"required|number_is:2016\"\n    placeholder=\"Provide current year\"\n\u003e\n```\n\nOther options available on the `element` object:\n\n```\n// name attribute\nname,\n\n// type attribute\ntype,\n\n// value of the input\nvalue,\n\n// validation rules associated with the data-validate attribute\nrules: obj.data('validate'),\n\n// returns true if element name is of the array type\n// i.e. name=\"category[]\"\nisArray,\n\n// returns true if checkbox / radio button is checked\nisChecked,\n\n// returns true if given input is visible / not hidden\nisVisible,\n\n// returns true if given input has class 'editor' associated with it\n// this option is useful if you're using wysiwyg editor etc.\nisEditor,\n\n// returns associated regex rule\nregex\n```\n\nFor behaviours you do the same with `extendBehaviours` option, methods which take two arguments `form` (instance of the `FormModel` object) and `data` (ajax json response):\n\n```javascript\n$('form[data-ajax-form]').ssdForm({\n\n    extendBehaviours: {\n\n        alertMessage: function(form, data) {\n\n            alert(data.message);\n\n        }\n\n    }\n\n});\n\n\u003cform\n    method=\"post\"\n    action=\"./submit.php\"\n    data-ajax-form\n    data-success-behaviour=\"alertMessage\"\n    novalidate\n\u003e\n...\n\u003c/form\u003e\n```\n\n## Custom serialize attribute\n\nThere might be some situations where you might want to use different attribute on your form fields to represent the identity of your input than the default `name`.\n\nThis might be useful in situations where you might be sending request to the external service over the ssl and don't want your server to receive any data when the form is submitted.\n\nYou can specify what field attribute should be used by overwriting the `serializeAttribute` property.\n\n```html\n$('form[data-ajax-form]').ssdForm({\n\n    serializeAttribute: 'data-field'\n\n});\n\n\u003cinput\n    type=\"text\"\n    data-field=\"year\"\n    id=\"year\"\n    data-validate=\"required|number_is:2016\"\n    placeholder=\"Provide current year\"\n\u003e\n```\n\n## Custom action\n\nIf you'd like to perform custom action once the form has been successfully validated, you can overwrite the default one by using the `actionMethod` property. This property is of a function type and takes 4 arguments.\n\n- `form`: instance of the main Form object\n- `form_model`: instance of the FormModel\n- `success`: default success callback\n- `error`: default error callback\n\n```javascript\n$('form[data-ajax-form]').ssdForm({\n\n    actionMethod: function(form, form_model, success, error) {\n\n        console.log('Calling action method');\n\n        form.endRequest(form_model);\n\n    }\n\n});\n```\n\n## CKEDITOR field\n\nTo fetch data from the CKEDITOR instance, please use the `classCkEditor` config option to specify what css class is representing input associated with te CKEDITOR instance. Input also has to have associated `id` attribute. You will have to bind CKEDITOR instance with the input yourself, but form will fetch the correct data on submit.\n\n```html\n$('form[data-ajax-form]').ssdForm({\n\n    classCkEditor: 'ckeditor'\n\n});\n\n\u003ctextarea class=\"ckeditor\" id=\"body\" name=\"body\"\u003e\u003c/textarea\u003e\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebastiansulinski%2Fssd-form","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsebastiansulinski%2Fssd-form","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebastiansulinski%2Fssd-form/lists"}