{"_id":"57e104f89ff1e21900a721ac","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"},"__v":1,"parentDoc":null,"project":"571f5e8cd8667f0e00a3c498","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"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-20T09:44:24.166Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"You can call these functions on your jQuery-form-object: \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Important note\",\n  \"body\": \"The form is initialized asynchronously, so you have to handle the init-event, if you want to use these functions. See [Events](doc:form-api-events) for further information.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"myForm = $(\\\"#form\\\").fundraisingBoxForm({\\n  hash: \\\"{your_form_hash}\\\" // replace {your_form_hash} with your hash without {}-brackets\\n});\\nmyForm.on(\\\"fundraisingBox:init\\\", function() {\\n  var suggestions = myForm.getAmountSuggestions();\\n  myForm.updateSession();\\n  ...\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Config getter functions\"\n}\n[/block]\nThese functions provide the configuration of your form, defined by your form settings in your FundraisingBox. Please have a look on the [Form Configuration JSON](doc:form-configuration-json) for further details.\n\n#getAmountSuggestions()\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n    \\\"amount\\\": \\\"10\\\",\\n    \\\"description\\\": \\\"Auch eine kleine Spende hilft!\\\"\\n  },\\n\\t{\\n    \\\"amount\\\": \\\"50\\\",\\n    \\\"description\\\": \\\"Vielen Dank für diese Spende!\\\"\\n  },\\n  ...\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#getItems()\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n    \\\"id\\\" : \\\"1234\\\",\\n\\t\\t\\\"title\\\": \\\"Hund 10€\\\",\\n    \\\"amount\\\": 10,\\n  \\t\\\"visible\\\": true,\\n    \\\"order\\\": 1\\n  },\\n  {\\n    \\\"id\\\": \\\"5678\\\",\\n    \\\"title\\\": \\\"Katze 20€\\\",\\n    \\\"amount\\\": 20,\\n    \\\"visible\\\": false,\\n    \\\"order\\\": 0\\n  },\\n  ...\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#getPaymentMethods()\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"sepa_direct_debit\\\":\\n   {\\n      \\\"countries\\\": \\\"DE AT CH\\\",\\n      \\\"amount_min\\\": 0.01,\\n      \\\"amount_max\\\": 50000,\\n      \\\"label\\\": \\\"SEPA-Lastschrift\\\",\\n      \\\"recurring\\\": true\\n   },\\n   ...\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#getFormFields()\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"first_name\\\":\\n   {\\n      \\\"id\\\": \\\"payment_first_name\\\",\\n      \\\"label\\\": \\\"Vorname\\\",\\n      \\\"type\\\": \\\"text\\\",\\n      \\\"validator\\\":\\n      {\\n          \\\"type\\\": \\\"text\\\",\\n          \\\"required\\\": true,\\n          \\\"max_length\\\": 100,\\n          \\\"min_length\\\": 2\\n      },\\n      \\\"field_html\\\": \\\"<input maxlength=\\\\\\\"100\\\\\\\" type=\\\\\\\"text\\\\\\\" name=\\\\\\\"payment[first_name]\\\\\\\" id=\\\\\\\"payment_first_name\\\\\\\" />\\\",\\n      \\\"label_html\\\": \\\"<label for=\\\\\\\"payment_first_name\\\\\\\">Vorname&nbsp;*</label>\\\",\\n      \\\"error_html\\\": \\\"<div id='payment_first_name_error' class='error'></div>\\\"\\n   },\\n   ...\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Contextual getter-functions\"\n}\n[/block]\n#getSession()\nReturns [Session JSON](doc:session-json).\n\n#getTransaction()\nReturns [Transaction JSON](doc:transaction-json).\n**Only available after payment on a success page.**\n\n#getErrors()\nReturns [Errors JSON](doc:errors-json).\n\n#getTranslatedValues()\nReturns [Translated Values JSON](doc:translated-values-json).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"View helper functions\"\n}\n[/block]\nThese functions can help you to create highly dynamical foms, maintained by the form settings in your FundraisingBox.\n\n#target \nCan be a css selection string or a jQuery-object\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div id=\\\"myAmount\\\"></div>\\n<div id=\\\"myInterval\\\">\\n  <label>Interval</label>\\n\\t<select name=\\\"payment[interval]\\\">...</select>\\n</div>\\n<script>\\n  ...\\n  myForm.appendFieldRowsTo(\\\"#myAmount\\\", [\\\"amount\\\"]);\\n\\tmyInterval = $(\\\"#myInterval\\\");\\n\\tmyForm.appendErrorDivTo(myInterval, \\\"interval\\\");\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n#addSessionHashTo(target)\nAdds the current session hash to the href attribute of the target-elements, e.g. useful for a navigation of a multi-step-form. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Constructor option\",\n  \"body\": \"You can also use the \\\"addSessionHashTo\\\" constructor option to do this automatically on init.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<ul class=\\\"nav\\\">\\n  <li><a href=\\\"1.html\\\">1.Step</a></li>\\n  <li><a href=\\\"2.html?param=true\\\">2.Step</a></li>\\n</ul>\\n<script>\\n  ...\\n  myForm.addSessionHashTo(\\\".nav a\\\");\\n</script>\\n\\n//RESULT:\\n<ul class=\\\"nav\\\">\\n  <li><a href=\\\"1.html?fbSessionHash={your_session_hash}\\\">1.Step</a></li>\\n  <li><a href=\\\"2.html?param=true&fbSessionHash={your_session_hash}\\\">2.Step</a></li>\\n</ul>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n#appendFieldRowsTo(target, fieldnames, classes)\nAppends to the target a div containing wrapper-divs with label, field and error-div.\n**fieldnames:** optional, array of fieldnames. If undefined, all fields of the form are added to the target. This can be helpful to get a quick overview for a developer.\n**classes:** optional, object with optional \"row\", \"label\", field-type (\"text\", \"select\", \"textarea\", \"radio\", \"checkbox\", \"hidden\") and \"error\" attributes to add certain classes to the elements. If no classes-object is provided, the default classes of the contructor options are used if exist.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"AutoFillValues\",\n  \"body\": \"If the constructor option autoFillValues is true, the fields are automatically filled with the corresponding existing values of the session.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div id=\\\"donationFields\\\"></div>\\n<div id=\\\"personFields\\\"></div>\\n<script>\\n  ...\\n  myForm = $(\\\"#form\\\").fundraisingBoxForm({\\n    hash: \\\"{your_form_hash}\\\",\\n    classes: {\\n      row: \\\"myRowClass\\\",\\n      label: \\\"myLabelClass\\\",\\n      text: \\\"myInputClass\\\", //for input type text\\n      textarea: \\\"myTextareaClass\\\",\\n      select: \\\"mySelectClass myOtherSelectClass\\\",\\n      radio: \\\"myRadioClass\\\",\\n      checkbox: \\\"myCheckboxClass\\\",\\n      error: \\\"myErrorClass\\\"\\n  });\\n  myForm.appendFieldRowsTo(\\\"#donationFields\\\", [\\\"amount\\\", \\\"interval\\\"]);\\n  myForm.appendFieldRowsTo(\\\"#personFields\\\", [\\\"first_name\\\", \\\"last_name\\\"], {\\n    row: \\\"nameRowClass\\\",\\n    text: \\\"nameInputClass\\\"\\n  });\\n</script>\\n\\n// RESULT:\\n<div id=\\\"donationFields\\\">\\n  <div>\\n    <div id=\\\"payment_amount_wrapper\\\" class=\\\"myRowClass\\\">\\n      <label for=\\\"payment_amount\\\" class=\\\"myLabelClass\\\">Betrag</label>\\n      <input type=\\\"text\\\" id=\\\"payment_amount\\\" name=\\\"payment[amount]\\\" class=\\\"myInputClass\\\">\\n      <div class=\\\"error myErrorClass\\\" id=\\\"payment_amount_error\\\"></div>\\n    </div>\\n    <div id=\\\"payment_interval_wrapper\\\" class=\\\"myRowClass\\\">\\n      <label for=\\\"payment_interval\\\" class=\\\"myLabelClass\\\">Rhythmus</label>\\n      <select id=\\\"payment_interval\\\" name=\\\"payment[interval]\\\" class=\\\"mySelectClass myOtherSelectClass\\\">\\n        <option value=\\\"1\\\">monatlich</option>\\n        <option value=\\\"3\\\">vierteljährlich</option>\\n        <option value=\\\"6\\\">halbjährlich</option>\\n        <option value=\\\"12\\\">jährlich</option>\\n        <option value=\\\"0\\\">einmalig</option>\\n      </select>\\n      <div class=\\\"error myErrorClass\\\" id=\\\"payment_interval_error\\\"></div>\\n    </div>\\n  </div>\\n</div>\\n<div id=\\\"personFields\\\">\\n  <div>\\n    <div id=\\\"payment_first_name_wrapper\\\" class=\\\"nameRowClass\\\">\\n      <label for=\\\"payment_first_name\\\">Vorname</label>\\n      <input type=\\\"text\\\" id=\\\"payment_first_name\\\" name=\\\"payment[first_name]\\\" class=\\\"nameInputClass\\\">\\n      <div class=\\\"error\\\" id=\\\"payment_first_name_error\\\"></div>\\n    </div>\\n    <div id=\\\"payment_last_name_wrapper\\\" class=\\\"nameRowClass\\\">\\n      <label for=\\\"payment_last_name\\\">Nachname</label>\\n      <input type=\\\"text\\\" id=\\\"payment_last_name\\\" name=\\\"payment[last_name]\\\" class=\\\"nameInputClass\\\">\\n      <div class=\\\"error\\\" id=\\\"payment_last_name_error\\\"></div>\\n    </div>\\n  </div>\\n</div>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n#appendFieldTo(target, fieldname, class)\nAppends to the target the default field HTML.\n**class:** optional class string. If not provided, the default class of the contructor options is used if exists.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"AutoFillValues\",\n  \"body\": \"If the constructor option autoFillValues is true, the field is automatically filled with the corresponding existing value of the session.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<label for=\\\"payment_first_name\\\">What is your first name?</label>\\n<div id=\\\"myFirstName\\\"></div>\\n<script>\\n  ...\\n  myForm.appendFieldTo(\\\"#myFirstName\\\", \\\"first_name\\\", \\\"myFieldClass\\\");\\n</script>\\n\\n//RESULT\\n<label for=\\\"payment_first_name\\\">What is your first name?</label>\\n<div id=\\\"myFirstName\\\">\\n  <input maxlength=\\\"100\\\" type=\\\"text\\\" name=\\\"payment[first_name]\\\" id=\\\"payment_first_name\\\" class=\\\"myFieldClass\\\" />\\n</div>\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n#appendLabelTo(target, fieldname, class)\nAppends to the target the default label HTML.\nThe default label contains `&nbsp;`, required-asterisk and possibly links (terms and privacy label).\n**class:** optional class string. If not provided, the default class of the contructor options is used if exists.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div id=\\\"myFirstNameLabel\\\"></div>\\n<input type=\\\"text\\\" name=\\\"payment[first_name]\\\" id=\\\"payment_first_name\\\" />\\n<script>\\n  ...\\n  myForm.appendLabelTo(\\\"#myFirstNameLabel\\\", \\\"first_name\\\", \\\"myLabelClass\\\");\\n</script>\\n\\n//RESULT\\n<div id=\\\"myFirstNameLabel\\\">\\n  <label for=\\\"payment_first_name\\\" class=\\\"myLabelClass\\\">Vorname&nbsp;*</label>\\n</div>\\n<input type=\\\"text\\\" name=\\\"payment[first_name]\\\" id=\\\"payment_first_name\\\" />\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n#appendErrorDivTo(target, fieldname, class)\nAppends to the target the default error div HTML, required for automatic error rendering.\n**class:** optional class string. If not provided, the default class of the contructor options is used if exists.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<label for=\\\"payment_first_name\\\">What is your first name?</label>\\n<input type=\\\"text\\\" name=\\\"payment[first_name]\\\" id=\\\"payment_first_name\\\" />\\n<div id=\\\"myFirstNameError\\\"></div>\\n<script>\\n  ...\\n  myForm.appendErrorDivTo(\\\"#myFirstNameError\\\", \\\"first_name\\\", \\\"myErrorClass\\\");\\n</script>\\n\\n//RESULT\\n<label for=\\\"payment_first_name\\\">What is your first name?</label>\\n<input type=\\\"text\\\" name=\\\"payment[first_name]\\\" id=\\\"payment_first_name\\\" />\\n<div id=\\\"myFirstNameError\\\">\\n  <div id=\\\"payment_first_name_error\\\" class=\\\"error myErrorClass\\\"></div>\\n</div>\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n#getLabelString(fieldname)\nReturns the cleaned string of the label. There are no HTML-entities, asterisk and links.\nFor example \"Vorname\" instead of `Vorname&nbsp;*` \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<label id=\\\"myLabel\\\" for=\\\"payment_first_name\\\"></label>\\n<script>\\n  ...\\n\\t$(\\\"#myLabel\\\").html(\\\"Wie ist dein \\\"+myForm.getLabelString(\\\"first_name\\\")+\\\"?\\\");\\n</script>\\n\\n//RESULT\\n<label for=\\\"payment_first_name\\\">Wie ist dein Vorname?</label>\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n#renderErrors()\nFirst removes all currently visible errors in the form: \n- searches for \".error\" classes and deletes the content\n- removes \".has-error\" classes from wrapper-divs and inputs\n\nThen adds the \"current_fields\"-errors of the session to the corresponding error-divs and adds \".has-error\" class to corresponding wrapper-divs and inputs.\nIf a generalErrorElement is defined in the constructor options, this element will be shown.\n**If nextUrl is empty:** adds also the \"other_fields\"-errors and \"globals\"-errors to the div with the ID \"global_error\".\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Constructor option\",\n  \"body\": \"This function is called automatically if constructor option \\\"autoRenderErrors\\\" is true.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div id=\\\"payment_amount_wrapper\\\">\\n  <label for=\\\"payment_amount\\\">Betrag</label>\\n  <input type=\\\"text\\\" id=\\\"payment_amount\\\" name=\\\"payment[amount]\\\">\\n  <div class=\\\"error\\\" id=\\\"payment_amount_error\\\"></div>\\n</div>\\n\\n<script>\\n  ...\\n  myForm.renderErrors();\\n</script>\\n\\n//RESULT:\\n<div id=\\\"payment_amount_wrapper\\\" class=\\\"has-error\\\">\\n  <label for=\\\"payment_amount\\\">Betrag</label>\\n  <input type=\\\"text\\\" id=\\\"payment_amount\\\" name=\\\"payment[amount]\\\" class=\\\"has-error\\\">\\n  <div class=\\\"error\\\" id=\\\"payment_amount_error\\\">Dies ist ein Pflichtfeld.</div>\\n</div>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n#fillValues()\nFills the exisiting form-fields with the corresponding values stored in the current session, considering the difference between checkboxes, radio-buttons, inputs and selects.\n\n**Additionally:**\nReplaces also all corresponding {{variables}} with the translated values in all elements with the class **\"replace_vars\"**. This is very helpful e.g. for a confirmation overview page or to personalize the form steps. You have to use the available keys of the [Translated Values JSON](doc:translated-values-json). For example *{{amount}}* or *{{first_name}}*. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Constructor option\",\n  \"body\": \"This function is called automatically if constructor option \\\"autoFillValues\\\" is true.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"replace_vars class\",\n  \"body\": \"We **strongly recommend** to set this class only where it's necessary. The fillValues-function performs a HTML replace, so if there are elements with e.g. click-observers, these observers are gone after the replace!\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<input type=\\\"text\\\" name=\\\"payment[amount]\\\" />\\n<input type=\\\"text\\\" name=\\\"payment[interval]\\\" />\\n<input type=\\\"text\\\" name=\\\"payment[fb_item_id]\\\" />\\n<p class=\\\"replace_vars\\\">\\n  Ich spende {{interval}} {{amount}} € für {{fb_item_id}}.\\n</p>\\n<scrip>\\n  ...\\n  myForm.fillValues();\\n</script>\\n\\n//RESULT:\\n<input type=\\\"text\\\" name=\\\"payment[amount]\\\" value=\\\"12.5\\\" />\\n<input type=\\\"text\\\" name=\\\"payment[interval]\\\" value=\\\"1\\\" />\\n<input type=\\\"text\\\" name=\\\"payment[fb_item_id]\\\" value=\\\"123\\\" />\\n<p class=\\\"replace_vars\\\">\\n  Ich spende monatlich 12,50 € für Bedrohte Tiere.\\n</p>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n#bankAccountReset()\nResets the bank fields to empty value. Useful on payment method change.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<input type=\\\"text\\\" name=\\\"payment[bank_iban]\\\" value=\\\"DE123456...\\\" />\\n<input type=\\\"text\\\" name=\\\"payment[bank_bic]\\\" value=\\\"AUGSDE...\\\" />\\n<script>\\n  ...\\n  $(\\\"[name='payment[payment_method]']\\\").change(function() {\\n    if($(this).val() != \\\"sepa_direct_debit\\\")\\n    {\\n      myForm.bankAccountReset();\\n    }\\n  });\\n</script>\\n\\n//RESULT:\\n<input type=\\\"text\\\" name=\\\"payment[bank_iban]\\\" value=\\\"\\\" />\\n<input type=\\\"text\\\" name=\\\"payment[bank_bic]\\\" value=\\\"\\\" />\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API endpoint functions\"\n}\n[/block]\n#updateSession()\nRetrieves the values of the current form and sends it to the [app/createSession-endpoint](doc:appcreatesession) or [app/updateSession-endpoint](doc:appupdatesession).\nTriggers the event **fundraisingBox:updateSession** after successful api call.\nIf autoRenderErrors: triggers renderErrors() if there are errors.\nIf autoRedirect and nextUrl: redirects to nextUrl with appended session_hash-parameter.\nIf autoPayment: triggers doPayment() if there are no errors and no nextUrl.\n\n#doPayment()\nSends the current session to the [app/payment-endpoint](doc:apppayment).\nTriggers the event **fundraisingBox:payment** after successful api call.\nIf autoRenderErrors: triggers renderErrors() if there are errors.\nIf autoRedirect: redirects to the returned redirect_url.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Credit card functions\"\n}\n[/block]\nCredit card fields are special fields in iframes. They need a special treatment of styling and cannot be manipulated directly. \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Important note:\",\n  \"body\": \"These functions work only after the event **fundraisingBox:creditCardReady** has been triggered!\"\n}\n[/block]\n#creditCardStyle(css)\nSets the style of the inputs. We recommend to do minimal styling to the iframe-inputs and do the main styling on the surrounding div. \n**Hint:** for security reasons custom fonts are not possible.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"myForm.on(\\\"fundraisingBox:creditCardReady\\\", function() {\\n  myForm.creditCardStyle(\\\"color: #00F; font-size: 14px;\\\");\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n#creditCardCopyStyleFromTemplate()\nCopies the current font styles (and height if micropayment credit card) from the defined \"creditCardFieldTemplate\" (default \"payment_credit_card_owner\") to the secure credit card fields. This function is called initially and on every windows resize. You can call this function manually, e.g. if you've changed the style dynamically or when you toggle the div with the credit cards inputs.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$(\\\"#payment_payment_method\\\").change(function() {\\n  if($(this).val() == \\\"micropayment_credit_card\\\")\\n  {\\n    $(\\\"#creditCardFields\\\").show();\\n    myForm.creditCardCopyStyleFromTemplate();\\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n#creditCardReset()\nResets and shows the iframe-inputs and hides the readonly-fields. This function should be used if the payment_method is changed to another method than credit card.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$(\\\"#payment_payment_method\\\").change(function() {\\n  if($(this).val() != \\\"micropayment_credit_card\\\")\\n  {\\n    myForm.creditCardReset();\\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n#creditCardMakeToken()\nThis function is automatically called if autoSubmit is active and payment_method is credit card. So in general you do not need to call this action by yourself. Removes possibly existing errors on the credit card fields, sends and validates the credit card data to the payment provider.\n\n**On success:**\n- fills the payment_credit_card_token-field with the retrieved token\n- shows and fills the readonly-fields with the obfuscated credit card data\n- hides the iframe-inputs\n- triggers the event *fundraisingBox:creditCardSuccess*\n- if autoSubmit: triggers **updateSession()**\n\n**On failure:**\n- retrieves the errors\n- if autoRenderErrors: triggers *renderErrors()*\n- triggers the event *fundraisingBox:creditCardError*","excerpt":"","slug":"form-api-functions","type":"basic","title":"Functions"}
You can call these functions on your jQuery-form-object: [block:callout] { "type": "warning", "title": "Important note", "body": "The form is initialized asynchronously, so you have to handle the init-event, if you want to use these functions. See [Events](doc:form-api-events) for further information." } [/block] [block:code] { "codes": [ { "code": "myForm = $(\"#form\").fundraisingBoxForm({\n hash: \"{your_form_hash}\" // replace {your_form_hash} with your hash without {}-brackets\n});\nmyForm.on(\"fundraisingBox:init\", function() {\n var suggestions = myForm.getAmountSuggestions();\n myForm.updateSession();\n ...\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Config getter functions" } [/block] These functions provide the configuration of your form, defined by your form settings in your FundraisingBox. Please have a look on the [Form Configuration JSON](doc:form-configuration-json) for further details. #getAmountSuggestions() [block:code] { "codes": [ { "code": "[\n {\n \"amount\": \"10\",\n \"description\": \"Auch eine kleine Spende hilft!\"\n },\n\t{\n \"amount\": \"50\",\n \"description\": \"Vielen Dank für diese Spende!\"\n },\n ...\n]", "language": "json" } ] } [/block] #getItems() [block:code] { "codes": [ { "code": "[\n {\n \"id\" : \"1234\",\n\t\t\"title\": \"Hund 10€\",\n \"amount\": 10,\n \t\"visible\": true,\n \"order\": 1\n },\n {\n \"id\": \"5678\",\n \"title\": \"Katze 20€\",\n \"amount\": 20,\n \"visible\": false,\n \"order\": 0\n },\n ...\n]", "language": "json" } ] } [/block] #getPaymentMethods() [block:code] { "codes": [ { "code": "{\n \"sepa_direct_debit\":\n {\n \"countries\": \"DE AT CH\",\n \"amount_min\": 0.01,\n \"amount_max\": 50000,\n \"label\": \"SEPA-Lastschrift\",\n \"recurring\": true\n },\n ...\n}", "language": "json" } ] } [/block] #getFormFields() [block:code] { "codes": [ { "code": "{\n \"first_name\":\n {\n \"id\": \"payment_first_name\",\n \"label\": \"Vorname\",\n \"type\": \"text\",\n \"validator\":\n {\n \"type\": \"text\",\n \"required\": true,\n \"max_length\": 100,\n \"min_length\": 2\n },\n \"field_html\": \"<input maxlength=\\\"100\\\" type=\\\"text\\\" name=\\\"payment[first_name]\\\" id=\\\"payment_first_name\\\" />\",\n \"label_html\": \"<label for=\\\"payment_first_name\\\">Vorname&nbsp;*</label>\",\n \"error_html\": \"<div id='payment_first_name_error' class='error'></div>\"\n },\n ...\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Contextual getter-functions" } [/block] #getSession() Returns [Session JSON](doc:session-json). #getTransaction() Returns [Transaction JSON](doc:transaction-json). **Only available after payment on a success page.** #getErrors() Returns [Errors JSON](doc:errors-json). #getTranslatedValues() Returns [Translated Values JSON](doc:translated-values-json). [block:api-header] { "type": "basic", "title": "View helper functions" } [/block] These functions can help you to create highly dynamical foms, maintained by the form settings in your FundraisingBox. #target Can be a css selection string or a jQuery-object [block:code] { "codes": [ { "code": "<div id=\"myAmount\"></div>\n<div id=\"myInterval\">\n <label>Interval</label>\n\t<select name=\"payment[interval]\">...</select>\n</div>\n<script>\n ...\n myForm.appendFieldRowsTo(\"#myAmount\", [\"amount\"]);\n\tmyInterval = $(\"#myInterval\");\n\tmyForm.appendErrorDivTo(myInterval, \"interval\");\n</script>", "language": "html" } ] } [/block] #addSessionHashTo(target) Adds the current session hash to the href attribute of the target-elements, e.g. useful for a navigation of a multi-step-form. [block:callout] { "type": "info", "title": "Constructor option", "body": "You can also use the \"addSessionHashTo\" constructor option to do this automatically on init." } [/block] [block:code] { "codes": [ { "code": "<ul class=\"nav\">\n <li><a href=\"1.html\">1.Step</a></li>\n <li><a href=\"2.html?param=true\">2.Step</a></li>\n</ul>\n<script>\n ...\n myForm.addSessionHashTo(\".nav a\");\n</script>\n\n//RESULT:\n<ul class=\"nav\">\n <li><a href=\"1.html?fbSessionHash={your_session_hash}\">1.Step</a></li>\n <li><a href=\"2.html?param=true&fbSessionHash={your_session_hash}\">2.Step</a></li>\n</ul>", "language": "html" } ] } [/block] #appendFieldRowsTo(target, fieldnames, classes) Appends to the target a div containing wrapper-divs with label, field and error-div. **fieldnames:** optional, array of fieldnames. If undefined, all fields of the form are added to the target. This can be helpful to get a quick overview for a developer. **classes:** optional, object with optional "row", "label", field-type ("text", "select", "textarea", "radio", "checkbox", "hidden") and "error" attributes to add certain classes to the elements. If no classes-object is provided, the default classes of the contructor options are used if exist. [block:callout] { "type": "info", "title": "AutoFillValues", "body": "If the constructor option autoFillValues is true, the fields are automatically filled with the corresponding existing values of the session." } [/block] [block:code] { "codes": [ { "code": "<div id=\"donationFields\"></div>\n<div id=\"personFields\"></div>\n<script>\n ...\n myForm = $(\"#form\").fundraisingBoxForm({\n hash: \"{your_form_hash}\",\n classes: {\n row: \"myRowClass\",\n label: \"myLabelClass\",\n text: \"myInputClass\", //for input type text\n textarea: \"myTextareaClass\",\n select: \"mySelectClass myOtherSelectClass\",\n radio: \"myRadioClass\",\n checkbox: \"myCheckboxClass\",\n error: \"myErrorClass\"\n });\n myForm.appendFieldRowsTo(\"#donationFields\", [\"amount\", \"interval\"]);\n myForm.appendFieldRowsTo(\"#personFields\", [\"first_name\", \"last_name\"], {\n row: \"nameRowClass\",\n text: \"nameInputClass\"\n });\n</script>\n\n// RESULT:\n<div id=\"donationFields\">\n <div>\n <div id=\"payment_amount_wrapper\" class=\"myRowClass\">\n <label for=\"payment_amount\" class=\"myLabelClass\">Betrag</label>\n <input type=\"text\" id=\"payment_amount\" name=\"payment[amount]\" class=\"myInputClass\">\n <div class=\"error myErrorClass\" id=\"payment_amount_error\"></div>\n </div>\n <div id=\"payment_interval_wrapper\" class=\"myRowClass\">\n <label for=\"payment_interval\" class=\"myLabelClass\">Rhythmus</label>\n <select id=\"payment_interval\" name=\"payment[interval]\" class=\"mySelectClass myOtherSelectClass\">\n <option value=\"1\">monatlich</option>\n <option value=\"3\">vierteljährlich</option>\n <option value=\"6\">halbjährlich</option>\n <option value=\"12\">jährlich</option>\n <option value=\"0\">einmalig</option>\n </select>\n <div class=\"error myErrorClass\" id=\"payment_interval_error\"></div>\n </div>\n </div>\n</div>\n<div id=\"personFields\">\n <div>\n <div id=\"payment_first_name_wrapper\" class=\"nameRowClass\">\n <label for=\"payment_first_name\">Vorname</label>\n <input type=\"text\" id=\"payment_first_name\" name=\"payment[first_name]\" class=\"nameInputClass\">\n <div class=\"error\" id=\"payment_first_name_error\"></div>\n </div>\n <div id=\"payment_last_name_wrapper\" class=\"nameRowClass\">\n <label for=\"payment_last_name\">Nachname</label>\n <input type=\"text\" id=\"payment_last_name\" name=\"payment[last_name]\" class=\"nameInputClass\">\n <div class=\"error\" id=\"payment_last_name_error\"></div>\n </div>\n </div>\n</div>", "language": "html" } ] } [/block] #appendFieldTo(target, fieldname, class) Appends to the target the default field HTML. **class:** optional class string. If not provided, the default class of the contructor options is used if exists. [block:callout] { "type": "info", "title": "AutoFillValues", "body": "If the constructor option autoFillValues is true, the field is automatically filled with the corresponding existing value of the session." } [/block] [block:code] { "codes": [ { "code": "<label for=\"payment_first_name\">What is your first name?</label>\n<div id=\"myFirstName\"></div>\n<script>\n ...\n myForm.appendFieldTo(\"#myFirstName\", \"first_name\", \"myFieldClass\");\n</script>\n\n//RESULT\n<label for=\"payment_first_name\">What is your first name?</label>\n<div id=\"myFirstName\">\n <input maxlength=\"100\" type=\"text\" name=\"payment[first_name]\" id=\"payment_first_name\" class=\"myFieldClass\" />\n</div>", "language": "javascript" } ] } [/block] #appendLabelTo(target, fieldname, class) Appends to the target the default label HTML. The default label contains `&nbsp;`, required-asterisk and possibly links (terms and privacy label). **class:** optional class string. If not provided, the default class of the contructor options is used if exists. [block:code] { "codes": [ { "code": "<div id=\"myFirstNameLabel\"></div>\n<input type=\"text\" name=\"payment[first_name]\" id=\"payment_first_name\" />\n<script>\n ...\n myForm.appendLabelTo(\"#myFirstNameLabel\", \"first_name\", \"myLabelClass\");\n</script>\n\n//RESULT\n<div id=\"myFirstNameLabel\">\n <label for=\"payment_first_name\" class=\"myLabelClass\">Vorname&nbsp;*</label>\n</div>\n<input type=\"text\" name=\"payment[first_name]\" id=\"payment_first_name\" />", "language": "javascript" } ] } [/block] #appendErrorDivTo(target, fieldname, class) Appends to the target the default error div HTML, required for automatic error rendering. **class:** optional class string. If not provided, the default class of the contructor options is used if exists. [block:code] { "codes": [ { "code": "<label for=\"payment_first_name\">What is your first name?</label>\n<input type=\"text\" name=\"payment[first_name]\" id=\"payment_first_name\" />\n<div id=\"myFirstNameError\"></div>\n<script>\n ...\n myForm.appendErrorDivTo(\"#myFirstNameError\", \"first_name\", \"myErrorClass\");\n</script>\n\n//RESULT\n<label for=\"payment_first_name\">What is your first name?</label>\n<input type=\"text\" name=\"payment[first_name]\" id=\"payment_first_name\" />\n<div id=\"myFirstNameError\">\n <div id=\"payment_first_name_error\" class=\"error myErrorClass\"></div>\n</div>", "language": "javascript" } ] } [/block] #getLabelString(fieldname) Returns the cleaned string of the label. There are no HTML-entities, asterisk and links. For example "Vorname" instead of `Vorname&nbsp;*` [block:code] { "codes": [ { "code": "<label id=\"myLabel\" for=\"payment_first_name\"></label>\n<script>\n ...\n\t$(\"#myLabel\").html(\"Wie ist dein \"+myForm.getLabelString(\"first_name\")+\"?\");\n</script>\n\n//RESULT\n<label for=\"payment_first_name\">Wie ist dein Vorname?</label>", "language": "javascript" } ] } [/block] #renderErrors() First removes all currently visible errors in the form: - searches for ".error" classes and deletes the content - removes ".has-error" classes from wrapper-divs and inputs Then adds the "current_fields"-errors of the session to the corresponding error-divs and adds ".has-error" class to corresponding wrapper-divs and inputs. If a generalErrorElement is defined in the constructor options, this element will be shown. **If nextUrl is empty:** adds also the "other_fields"-errors and "globals"-errors to the div with the ID "global_error". [block:callout] { "type": "info", "title": "Constructor option", "body": "This function is called automatically if constructor option \"autoRenderErrors\" is true." } [/block] [block:code] { "codes": [ { "code": "<div id=\"payment_amount_wrapper\">\n <label for=\"payment_amount\">Betrag</label>\n <input type=\"text\" id=\"payment_amount\" name=\"payment[amount]\">\n <div class=\"error\" id=\"payment_amount_error\"></div>\n</div>\n\n<script>\n ...\n myForm.renderErrors();\n</script>\n\n//RESULT:\n<div id=\"payment_amount_wrapper\" class=\"has-error\">\n <label for=\"payment_amount\">Betrag</label>\n <input type=\"text\" id=\"payment_amount\" name=\"payment[amount]\" class=\"has-error\">\n <div class=\"error\" id=\"payment_amount_error\">Dies ist ein Pflichtfeld.</div>\n</div>", "language": "html" } ] } [/block] #fillValues() Fills the exisiting form-fields with the corresponding values stored in the current session, considering the difference between checkboxes, radio-buttons, inputs and selects. **Additionally:** Replaces also all corresponding {{variables}} with the translated values in all elements with the class **"replace_vars"**. This is very helpful e.g. for a confirmation overview page or to personalize the form steps. You have to use the available keys of the [Translated Values JSON](doc:translated-values-json). For example *{{amount}}* or *{{first_name}}*. [block:callout] { "type": "info", "title": "Constructor option", "body": "This function is called automatically if constructor option \"autoFillValues\" is true." } [/block] [block:callout] { "type": "warning", "title": "replace_vars class", "body": "We **strongly recommend** to set this class only where it's necessary. The fillValues-function performs a HTML replace, so if there are elements with e.g. click-observers, these observers are gone after the replace!" } [/block] [block:code] { "codes": [ { "code": "<input type=\"text\" name=\"payment[amount]\" />\n<input type=\"text\" name=\"payment[interval]\" />\n<input type=\"text\" name=\"payment[fb_item_id]\" />\n<p class=\"replace_vars\">\n Ich spende {{interval}} {{amount}} € für {{fb_item_id}}.\n</p>\n<scrip>\n ...\n myForm.fillValues();\n</script>\n\n//RESULT:\n<input type=\"text\" name=\"payment[amount]\" value=\"12.5\" />\n<input type=\"text\" name=\"payment[interval]\" value=\"1\" />\n<input type=\"text\" name=\"payment[fb_item_id]\" value=\"123\" />\n<p class=\"replace_vars\">\n Ich spende monatlich 12,50 € für Bedrohte Tiere.\n</p>", "language": "html" } ] } [/block] #bankAccountReset() Resets the bank fields to empty value. Useful on payment method change. [block:code] { "codes": [ { "code": "<input type=\"text\" name=\"payment[bank_iban]\" value=\"DE123456...\" />\n<input type=\"text\" name=\"payment[bank_bic]\" value=\"AUGSDE...\" />\n<script>\n ...\n $(\"[name='payment[payment_method]']\").change(function() {\n if($(this).val() != \"sepa_direct_debit\")\n {\n myForm.bankAccountReset();\n }\n });\n</script>\n\n//RESULT:\n<input type=\"text\" name=\"payment[bank_iban]\" value=\"\" />\n<input type=\"text\" name=\"payment[bank_bic]\" value=\"\" />", "language": "html" } ] } [/block] [block:api-header] { "type": "basic", "title": "API endpoint functions" } [/block] #updateSession() Retrieves the values of the current form and sends it to the [app/createSession-endpoint](doc:appcreatesession) or [app/updateSession-endpoint](doc:appupdatesession). Triggers the event **fundraisingBox:updateSession** after successful api call. If autoRenderErrors: triggers renderErrors() if there are errors. If autoRedirect and nextUrl: redirects to nextUrl with appended session_hash-parameter. If autoPayment: triggers doPayment() if there are no errors and no nextUrl. #doPayment() Sends the current session to the [app/payment-endpoint](doc:apppayment). Triggers the event **fundraisingBox:payment** after successful api call. If autoRenderErrors: triggers renderErrors() if there are errors. If autoRedirect: redirects to the returned redirect_url. [block:api-header] { "type": "basic", "title": "Credit card functions" } [/block] Credit card fields are special fields in iframes. They need a special treatment of styling and cannot be manipulated directly. [block:callout] { "type": "warning", "title": "Important note:", "body": "These functions work only after the event **fundraisingBox:creditCardReady** has been triggered!" } [/block] #creditCardStyle(css) Sets the style of the inputs. We recommend to do minimal styling to the iframe-inputs and do the main styling on the surrounding div. **Hint:** for security reasons custom fonts are not possible. [block:code] { "codes": [ { "code": "myForm.on(\"fundraisingBox:creditCardReady\", function() {\n myForm.creditCardStyle(\"color: #00F; font-size: 14px;\");\n});", "language": "javascript" } ] } [/block] #creditCardCopyStyleFromTemplate() Copies the current font styles (and height if micropayment credit card) from the defined "creditCardFieldTemplate" (default "payment_credit_card_owner") to the secure credit card fields. This function is called initially and on every windows resize. You can call this function manually, e.g. if you've changed the style dynamically or when you toggle the div with the credit cards inputs. [block:code] { "codes": [ { "code": "$(\"#payment_payment_method\").change(function() {\n if($(this).val() == \"micropayment_credit_card\")\n {\n $(\"#creditCardFields\").show();\n myForm.creditCardCopyStyleFromTemplate();\n }\n});", "language": "javascript" } ] } [/block] #creditCardReset() Resets and shows the iframe-inputs and hides the readonly-fields. This function should be used if the payment_method is changed to another method than credit card. [block:code] { "codes": [ { "code": "$(\"#payment_payment_method\").change(function() {\n if($(this).val() != \"micropayment_credit_card\")\n {\n myForm.creditCardReset();\n }\n});", "language": "javascript" } ] } [/block] #creditCardMakeToken() This function is automatically called if autoSubmit is active and payment_method is credit card. So in general you do not need to call this action by yourself. Removes possibly existing errors on the credit card fields, sends and validates the credit card data to the payment provider. **On success:** - fills the payment_credit_card_token-field with the retrieved token - shows and fills the readonly-fields with the obfuscated credit card data - hides the iframe-inputs - triggers the event *fundraisingBox:creditCardSuccess* - if autoSubmit: triggers **updateSession()** **On failure:** - retrieves the errors - if autoRenderErrors: triggers *renderErrors()* - triggers the event *fundraisingBox:creditCardError*