{"__v":0,"_id":"57e27bb985b9db0e00214388","category":{"__v":0,"_id":"57e104db9ff1e21900a721ab","project":"571f5e8cd8667f0e00a3c498","version":"571f5e8cd8667f0e00a3c49b","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-09-20T09:43:55.998Z","from_sync":false,"order":4,"slug":"form-api-jquery-plugin","title":"Form-API"},"parentDoc":null,"project":"571f5e8cd8667f0e00a3c498","user":"5720c075db52d01700f5d1e4","version":{"__v":12,"_id":"571f5e8cd8667f0e00a3c49b","hasDoc":true,"hasReference":true,"project":"571f5e8cd8667f0e00a3c498","createdAt":"2016-04-26T12:26:52.312Z","releaseDate":"2016-04-26T12:26:52.312Z","categories":["571f5e8cd8667f0e00a3c49c","571f73cfcb4baa0e00d13a80","571f7451cb4baa0e00d13a88","571f7d2720695f3400f38797","571f7fb0ac2a080e0014c661","571f884be54f2d0e003ebb0a","572200c9ecb38d0e00d80ebd","572c301e7c8eff0e00aaa174","57df91b2c6348d0e0020c452","57e104db9ff1e21900a721ab","57fd04caeaa77f19008b8202","5899c7113514ce0f0014da84"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-21T12:23:21.940Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Please check and consider the [Session-API Requirements and conventions](doc:session-api-requirements-conventions). Additionally, if you write your own HTML and use our jQuery-Plugin, following instructions can be helpful.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Field names\"\n}\n[/block]\nYou have to use the payment-namespace for the name. We also recommend to set the suitable ID.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<input type=\\\"text\\\" name=\\\"payment[amount]\\\" id=\\\"payment_amount\\\" />\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Field wrapper\"\n}\n[/block]\nWe recommend to use suitable wrapper-divs for better error handling and show/hide-effects.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div id=\\\"payment_amount_wrapper\\\">\\n  <label for=\\\"payment_amount\\\">Amount</label>\\n  <input type=\\\"text\\\" id=\\\"payment_amount\\\" name=\\\"payment[amount]\\\">\\n  <div class=\\\"error\\\" id=\\\"payment_amount_error\\\"></div>\\n</div>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Error handling\"\n}\n[/block]\nYou can place and design your errors like you want. If you want to use the automatic error rendering you have to provide an element (e.g. div, span, label, ...) with the required ID (fieldname + \"_error\") and class (\"error\"). \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div class=\\\"error\\\" id=\\\"payment_amount_error\\\"></div>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThe automatic error renderings also adds the \"has-error\"-class to the coresponding input and wrapper, if they exists.\n\n**Example code after auto rendering errors:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div id=\\\"payment_amount_wrapper\\\" class=\\\"has-error\\\">\\n  <label for=\\\"payment_amount\\\">Amount</label>\\n  <input type=\\\"text\\\" id=\\\"payment_amount\\\" name=\\\"payment[amount]\\\" class=\\\"has-error\\\">\\n  <div class=\\\"error\\\" id=\\\"payment_amount_error\\\">This field is required.</div>\\n</div>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n**Global errors**\nGlobal errors are special errors not bound to a special field and can occur e.g. after a failed payment or if you submit a field, that's not part of the form (this should be fixed during the development of your form). You should show global errors to the user so he/she can contact you if something went wrong. For automatic error rendering you have to provide an element with \"global_error\"-ID.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div id=\\\"global_error\\\"></div>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Other fields errors\",\n  \"body\": \"The Form-API automatically renders existing \\\"other_fields\\\" errors into the \\\"global_errors\\\"-element if there is no next url given. Because in this case some required fields are missing to process the payment.\"\n}\n[/block]","excerpt":"","slug":"form-api-requirements-conventions","type":"basic","title":"Requirements and conventions"}

Requirements and conventions


Please check and consider the [Session-API Requirements and conventions](doc:session-api-requirements-conventions). Additionally, if you write your own HTML and use our jQuery-Plugin, following instructions can be helpful. [block:api-header] { "type": "basic", "title": "Field names" } [/block] You have to use the payment-namespace for the name. We also recommend to set the suitable ID. [block:code] { "codes": [ { "code": "<input type=\"text\" name=\"payment[amount]\" id=\"payment_amount\" />", "language": "html" } ] } [/block] [block:api-header] { "type": "basic", "title": "Field wrapper" } [/block] We recommend to use suitable wrapper-divs for better error handling and show/hide-effects. [block:code] { "codes": [ { "code": "<div id=\"payment_amount_wrapper\">\n <label for=\"payment_amount\">Amount</label>\n <input type=\"text\" id=\"payment_amount\" name=\"payment[amount]\">\n <div class=\"error\" id=\"payment_amount_error\"></div>\n</div>", "language": "html" } ] } [/block] [block:api-header] { "type": "basic", "title": "Error handling" } [/block] You can place and design your errors like you want. If you want to use the automatic error rendering you have to provide an element (e.g. div, span, label, ...) with the required ID (fieldname + "_error") and class ("error"). [block:code] { "codes": [ { "code": "<div class=\"error\" id=\"payment_amount_error\"></div>", "language": "html" } ] } [/block] The automatic error renderings also adds the "has-error"-class to the coresponding input and wrapper, if they exists. **Example code after auto rendering errors:** [block:code] { "codes": [ { "code": "<div id=\"payment_amount_wrapper\" class=\"has-error\">\n <label for=\"payment_amount\">Amount</label>\n <input type=\"text\" id=\"payment_amount\" name=\"payment[amount]\" class=\"has-error\">\n <div class=\"error\" id=\"payment_amount_error\">This field is required.</div>\n</div>", "language": "html" } ] } [/block] **Global errors** Global errors are special errors not bound to a special field and can occur e.g. after a failed payment or if you submit a field, that's not part of the form (this should be fixed during the development of your form). You should show global errors to the user so he/she can contact you if something went wrong. For automatic error rendering you have to provide an element with "global_error"-ID. [block:code] { "codes": [ { "code": "<div id=\"global_error\"></div>", "language": "html" } ] } [/block] [block:callout] { "type": "warning", "title": "Other fields errors", "body": "The Form-API automatically renders existing \"other_fields\" errors into the \"global_errors\"-element if there is no next url given. Because in this case some required fields are missing to process the payment." } [/block]