{"_id":"57ee399321ceb20e0061957f","category":{"_id":"57e104db9ff1e21900a721ab","__v":0,"version":"571f5e8cd8667f0e00a3c49b","project":"571f5e8cd8667f0e00a3c498","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,"user":"5720c075db52d01700f5d1e4","version":{"_id":"571f5e8cd8667f0e00a3c49b","hasDoc":true,"__v":12,"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"},"__v":1,"project":"571f5e8cd8667f0e00a3c498","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-30T10:08:19.480Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"#General error message\nIf there are errors after submitting the form, you should show a general error message near the submit-button. The validation is done via Ajax and the errors are rendered on the page without a reload, so perhaps there is an error outside of the viewport.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Automation: generalErrorElement option\",\n  \"body\": \"We recommend to use the \\\"generalErrorElement\\\" constructor option to automate this.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<input type=\\\"submit\\\" value=\\\"Jetzt spenden\\\" />\\n<p id=\\\"errorMsg\\\" style=\\\"display: none;\\\">\\n  Es sind leider Fehler aufgetreten, bitte überprüfen Sie Ihre Angaben.\\n</p>\\n<script>\\n  ...\\n  myForm.on(\\\"fundraisingBox:updateSession\\\", function() {\\n    // show only current field errors on session update\\n    if(myForm.getErrors().current_fields)\\n    {\\n      $(\\\"#errorMsg\\\").show();\\n    }\\n    else\\n    {\\n      $(\\\"#errorMsg\\\").hide();\\n    }\\n  });\\n  myForm.on(\\\"fundraisingBox:payment\\\", function() {\\n    if(myForm.getErrors())\\n    {\\n      $(\\\"#errorMsg\\\").show();\\n    }\\n    else\\n    {\\n      $(\\\"#errorMsg\\\").hide();\\n    }\\n  });\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n#Show a loading-overlay until the form is initialized\nThe form is initialized asynchronously after your page is loaded, so there might be a short duration until everything is done. For example adding form fields, items or rendering values. We recommend to show such a loading-overlay until everything is done.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div class=\\\"loading\\\"></div>\\n<p class=\\\"replace_vars\\\">Thank you for your {{interval}} {{amount}} €</p>\\n<form id=\\\"form\\\">\\n  ...\\n  <div id=\\\"emailField\\\"></div>\\n</div>\\n<script>\\n  ...\\n  // show absolute positioned overlay, e.g. with a rotation hourglass\\n  $(\\\".loading\\\").show();\\n  // init form\\n  myForm = $(\\\"#form\\\").fundraisingBoxForm({\\n    hash: \\\"{your_form_hash}\\\" // replace {your_form_hash} with your hash without {}-brackets\\n  });\\n  myForm.on(\\\"fundraisingBox:init\\\", function() {\\n    // e.g. append some fields\\n    myForm.appendFieldRowsTo(\\\"#emailField\\\", [\\\"email\\\"]);\\n    // perhaps call fillValues again if there is dynamic content\\n    myForm.fillValues();\\n    // everything is done, hide loading div\\n    $(\\\".loading\\\").hide();\\n  });\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n#Prevent user to submit or navigate to fast\nYou have to wait for the init-event so the form works properly. If you don't use an overlay we recommend to deactivate the submit button and also the navigation, if you have one and you want to add the session hash to the navigation.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<ul class=\\\"nav\\\">\\n  <li><a href=\\\"1.html\\\">1.Step</a></li>\\n  ...\\n</ul>\\n<form id=\\\"form\\\">\\n  ...\\n</form>\\n<script>\\n  ...\\n  // deactivate form and navigation\\n  $(\\\"#form\\\").on(\\\"submit.init\\\", function() { return false; });\\n\\t$(\\\".nav a\\\").on(\\\"click.init\\\", function() { return false; });\\n  // init form\\n  myForm = $(\\\"#form\\\").fundraisingBoxForm({\\n    hash: \\\"{your_form_hash}\\\", // replace {your_form_hash} with your hash without {}-brackets\\n    addSessionHashTo: \\\".nav a\\\"\\n  });\\n  // reactivate form and navigation after init\\n  myForm.on(\\\"fundraisingBox:init\\\", function() {\\n    $(\\\"#form\\\").off(\\\"submit.init\\\");\\n    $(\\\".nav a\\\").off(\\\"click.init\\\");\\n  });\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n#Payment method handling\nYou can visualize the payment methods like you want, e.g. as radio buttons with nice logos. Consider the ability to handle recurring payments of the single methods.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script>\\n  ...\\n  // add payment methods\\n  $.each(myForm.getPaymentMethods(), function(key, method) {\\n    $(\\\"#paymentMethods\\\").append($('<div class=\\\"radio '+(method.recurring ? \\\"\\\" : \\\"notRecurring\\\")+'\\\"><label><input type=\\\"radio\\\" name=\\\"payment[payment_method]\\\" value=\\\"'+key+'\\\">'+method.label+'</label></div>'));\\n  });\\n  // hide not recurring methods if recurring donation\\n  $(\\\"#payment_interval\\\").change(function() {\\n    if($(this).val() == 0)\\n    {\\n      $(\\\"#paymentMethods .radio\\\").show();\\n    }\\n    else\\n    {\\n      $(\\\"#paymentMethods .notRecurring\\\").hide();\\n      $(\\\"#paymentMethods .notRecurring input\\\").prop(\\\"checked\\\", false);\\n    }\\n  });\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n#Adding sorted choices dynamically\nSome choices (interval, wants_receipt, fb_item_id, payment_method) can be managed and sorted in your FundraisingBox form settings. If this should also apply to your form, you have to add the options via javascript.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<select id=\\\"intervals\\\"></select>\\n...\\n<script>\\n  ...\\n  myForm.on(\\\"fundraisingBox:init\\\", function () {\\n\\t\\t\\t\\t// append available intervals dynamically\\n\\t\\t\\t\\t$.each(myForm.getFormFields().interval.options, function (index, option) {\\n\\t\\t\\t\\t\\t$(\\\"#intervals\\\").append($(\\\"<label class='radio-inline'><input type='radio' name='payment[interval]' value='\\\" + option.key + \\\"'>\\\" + option.value + \\\"</label>\\\"));\\n\\t\\t\\t\\t});\\n\\t\\t\\t\\tmyForm.fillValues(); // call fill values manually again because of dynamic intervals append\\n\\t\\t\\t});\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]","excerpt":"Some useful snippets working with the Form-API.","slug":"form-api-helper-snippets","type":"basic","title":"Helper snippets"}

Helper snippets

Some useful snippets working with the Form-API.

#General error message If there are errors after submitting the form, you should show a general error message near the submit-button. The validation is done via Ajax and the errors are rendered on the page without a reload, so perhaps there is an error outside of the viewport. [block:callout] { "type": "info", "title": "Automation: generalErrorElement option", "body": "We recommend to use the \"generalErrorElement\" constructor option to automate this." } [/block] [block:code] { "codes": [ { "code": "<input type=\"submit\" value=\"Jetzt spenden\" />\n<p id=\"errorMsg\" style=\"display: none;\">\n Es sind leider Fehler aufgetreten, bitte überprüfen Sie Ihre Angaben.\n</p>\n<script>\n ...\n myForm.on(\"fundraisingBox:updateSession\", function() {\n // show only current field errors on session update\n if(myForm.getErrors().current_fields)\n {\n $(\"#errorMsg\").show();\n }\n else\n {\n $(\"#errorMsg\").hide();\n }\n });\n myForm.on(\"fundraisingBox:payment\", function() {\n if(myForm.getErrors())\n {\n $(\"#errorMsg\").show();\n }\n else\n {\n $(\"#errorMsg\").hide();\n }\n });\n</script>", "language": "html" } ] } [/block] #Show a loading-overlay until the form is initialized The form is initialized asynchronously after your page is loaded, so there might be a short duration until everything is done. For example adding form fields, items or rendering values. We recommend to show such a loading-overlay until everything is done. [block:code] { "codes": [ { "code": "<div class=\"loading\"></div>\n<p class=\"replace_vars\">Thank you for your {{interval}} {{amount}} €</p>\n<form id=\"form\">\n ...\n <div id=\"emailField\"></div>\n</div>\n<script>\n ...\n // show absolute positioned overlay, e.g. with a rotation hourglass\n $(\".loading\").show();\n // init form\n myForm = $(\"#form\").fundraisingBoxForm({\n hash: \"{your_form_hash}\" // replace {your_form_hash} with your hash without {}-brackets\n });\n myForm.on(\"fundraisingBox:init\", function() {\n // e.g. append some fields\n myForm.appendFieldRowsTo(\"#emailField\", [\"email\"]);\n // perhaps call fillValues again if there is dynamic content\n myForm.fillValues();\n // everything is done, hide loading div\n $(\".loading\").hide();\n });\n</script>", "language": "html" } ] } [/block] #Prevent user to submit or navigate to fast You have to wait for the init-event so the form works properly. If you don't use an overlay we recommend to deactivate the submit button and also the navigation, if you have one and you want to add the session hash to the navigation. [block:code] { "codes": [ { "code": "<ul class=\"nav\">\n <li><a href=\"1.html\">1.Step</a></li>\n ...\n</ul>\n<form id=\"form\">\n ...\n</form>\n<script>\n ...\n // deactivate form and navigation\n $(\"#form\").on(\"submit.init\", function() { return false; });\n\t$(\".nav a\").on(\"click.init\", function() { return false; });\n // init form\n myForm = $(\"#form\").fundraisingBoxForm({\n hash: \"{your_form_hash}\", // replace {your_form_hash} with your hash without {}-brackets\n addSessionHashTo: \".nav a\"\n });\n // reactivate form and navigation after init\n myForm.on(\"fundraisingBox:init\", function() {\n $(\"#form\").off(\"submit.init\");\n $(\".nav a\").off(\"click.init\");\n });\n</script>", "language": "html" } ] } [/block] #Payment method handling You can visualize the payment methods like you want, e.g. as radio buttons with nice logos. Consider the ability to handle recurring payments of the single methods. [block:code] { "codes": [ { "code": "<script>\n ...\n // add payment methods\n $.each(myForm.getPaymentMethods(), function(key, method) {\n $(\"#paymentMethods\").append($('<div class=\"radio '+(method.recurring ? \"\" : \"notRecurring\")+'\"><label><input type=\"radio\" name=\"payment[payment_method]\" value=\"'+key+'\">'+method.label+'</label></div>'));\n });\n // hide not recurring methods if recurring donation\n $(\"#payment_interval\").change(function() {\n if($(this).val() == 0)\n {\n $(\"#paymentMethods .radio\").show();\n }\n else\n {\n $(\"#paymentMethods .notRecurring\").hide();\n $(\"#paymentMethods .notRecurring input\").prop(\"checked\", false);\n }\n });\n</script>", "language": "html" } ] } [/block] #Adding sorted choices dynamically Some choices (interval, wants_receipt, fb_item_id, payment_method) can be managed and sorted in your FundraisingBox form settings. If this should also apply to your form, you have to add the options via javascript. [block:code] { "codes": [ { "code": "<select id=\"intervals\"></select>\n...\n<script>\n ...\n myForm.on(\"fundraisingBox:init\", function () {\n\t\t\t\t// append available intervals dynamically\n\t\t\t\t$.each(myForm.getFormFields().interval.options, function (index, option) {\n\t\t\t\t\t$(\"#intervals\").append($(\"<label class='radio-inline'><input type='radio' name='payment[interval]' value='\" + option.key + \"'>\" + option.value + \"</label>\"));\n\t\t\t\t});\n\t\t\t\tmyForm.fillValues(); // call fill values manually again because of dynamic intervals append\n\t\t\t});\n</script>", "language": "html" } ] } [/block]