Tudoforms SDK reference
This reference documents using the tudoforms.js SDK. You can use the SDK to create your own contact forms on your website without having to use our imbedded script code. This provides faster rendering, better responsive design and more control over the look and feel of your forms.
Demo
Getting started
Include the optional style sheet https://td-cdn-1.netlify.app/css/style.css.
<link rel="stylesheet" href="https://td-cdn-1.netlify.app/css/style.css">
Optionally add font-awesome.
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
Add jQuery and the plugin script (If you have jQuery already on your page you can omit our slim build include.)
Include the script at the bottom of your page inside the body tag https://td-cdn-1.netlify.app/js/tudoforms-2-1-min.js
<script src="https://td-cdn-1.netlify.app/js/jquery-3.5.1.slim.min.js"></script>
<script src="https://td-cdn-1.netlify.app/js/tudoforms-2-1-min.js"></script>
Add the HTML below for a boilerplate form.
<div class="td-form-wrapper">
<!-- success form wrapper-->
<div id="form-success" class="" style="display:none;">
<div class="form-canvas">
<div class="form-intro">
<h2 class="primary text-center">
<div class="m-b-30"><i class="fa fa-check-circle-o fa-3x"></i></div>
Thank you
</h2>
</div>
<p class="text-muted">Thanks for submitting your request. You will receive a confirmation email with a repair reference. Please make sure to check your spam folder and whitelist our emails.</p>
<p class="text-muted">One of our team will respond shortly. This normally takes 24 hours.</p>
<div class="text-center">
<button type="button" id="td-form-restart" class="btn">Submit another request?</button>
</div>
</div>
</div>
<!-- contact for wrapper-->
<div id="contact-form">
<div class="form-canvas">
<form id="td-form" action="#" data-persist="garlic" autocomplete="off">
<h1>Sample contact form</h1>
<p class="m-b-30 text-muted">Add your form instructions here: This is a sample contact form that is using the tudoforms embeded SDK. You can add the SDK to your site and use it to send submissions from your own custom form. You are free to style this form to suit, or remove any css to adopt your existing sites css design.</p>
<!-- hidden vars add your widgets api-id and domain-->
<input type="hidden" id="form-id" name="id" value="[YOUR_FORMS_ID]" autocomplete="false">
<input type="hidden" id="form-domain" name="domain" value="[YOUR_FORMS_DOMAIN]">
<!-- /hidden vars-->
<!-- standard form inputs-->
<div class="form-section">
<label>1. Tell us how to contact you.</label>
<div class="form-group">
<input type="text" name="firstname" class="form-control form-control-danger b-r-0" placeholder="First Name" required autocomplete="new-password-028601">
<div class="form-control-feedback">This field is required.</div>
</div>
<div class="form-group">
<input type="text" name="lastname" class="form-control form-control-danger b-r-0" placeholder="Last Name" required autocomplete="new-password-028602">
<div class="form-control-feedback">This field is required.</div>
</div>
<div class="form-group">
<input type="email" name="email" class="form-control form-control-danger b-r-0" placeholder="Email" required autocomplete="new-password-028603">
<div class="form-control-feedback">A valid email is required.</div>
</div>
</div>
<div class="form-section">
<label>2. How can we help?</label>
<div class="form-group">
<input type="text" name="name" class="form-control form-control-danger b-r-0" placeholder="Subject" value="" required autocomplete="new-password-028605">
<div class="form-control-feedback">This field is required.</div>
</div>
<div class="form-group">
<textarea name="info" class="form-control form-control-danger b-r-0" placeholder="Message" rows="5"></textarea>
<div class="form-control-feedback">This field is required.</div>
</div>
</div>
<!-- attachments-->
<div class="form-section">
<label>3. Upload files or attachments.</label>
<div class="form-group upload-box">
<!-- attachments THIS BLOCK IS REQUIRED-->
<button type="button" class="btn upload" data-filetype="image/*" id="td-upload_button">
<i class="fa fa-camera m-r-5" aria-hidden="true"></i>Upload files
</button>
<div id="td-attachments-html">
</div>
<!-- /attachments THIS BLOCK IS REQUIRED-->
</div>
</div>
<!-- attachments-->
<div class="form-section">
<label>4. Submit your repair.</label>
<!-- submit button THIS BLOCK IS REQUIRED-->
<button type="submit" class="btn btn-primary">Submit</button>
<!-- /submit button THIS BLOCK IS REQUIRED-->
</div>
</form>
</div>
</div>
</div>
Inserting your forms API_ID and DOMAIN into the form
In the above example we provide our forms API _ID and our application DOMAIN id. You should edit the inputs below by adding your API ID and DOMAIN ID.
<!-- hidden vars add your widgets api-id and domain-->
<input type="hidden" id="form-id" name="id" value="YOUR_FORMS_API_ID">
<input type="hidden" id="form-domain" name="domain" value="DOMAIN_ID">
How to obtain a form API ID and DOMAIN ID
Before your form can accept submissions you will need to set-up a form widget in your Tudodesk back-office. See article below:
Once you have created a form. Note you do not need to edit the forms design, or layout in the widget editor since you are using the custom SDK and plugin.
Open your form into view in your browser. You can use the Preview option in back-office. Your form will display a URL in the browser URL bar. The URL will contain both your DOMAIN ID and API ID as shown below.
https://[DOMAIN ID].tudocommerce.com/forms/[FORM API ID]
You should copy the ID's from the URL and place them into there respective hidden inputs shown above.
Initialize the plugin with the form.
tudoforms.init({
DEBUG: false,
MODE: null
});
tudoforms.initLeadForm({
formId: "td-form",
contactFormId: "contact-form",
successFormId: "form-success",
attachmentsUploadBtnId: "td-upload_button",
attachmentRemoveBtnStr: "<i class='fa fa-close'></i>",
restartBtnId: "td-form-restart",
attachmentsHolderId: "td-attachments-html",
attachmentsTemplate: null,
submitBusyStr: "<i class='fa fa-circle-o-notch fa-spin m-r-5'></i>Sending",
tditi_utilsScript: null
});
Form Inputs
The following form inputs can be added to your form, pay careful attention to the name attribute which tells the plugin how to submit your form to our API.
<!-- required inputs-->
<input type="text" name="firstname" placeholder="First Name" required>
<input type="text" name="lastname" placeholder="Last Name" required>
<input type="email" name="email" placeholder="email" required>
<input type="text" name="name" placeholder="Subject" required>
<!-- optional-->
<textarea name="info" placeholder="Message" rows="3"></textarea>
<input type="text" name="phone" placeholder="Telephone">
<input type="text" name="mobile" placeholder="Mobile">
<input type="text" name="ref" placeholder="reference">
<select name="reason" value="">
<option value="">-- Select --</option>
<option value="option-1">Option one</option>
<option value="option-2">Option two</option>
<option value="option-1">Option three</option>
</select>
<input type="number" name="total_value" placeholder="budget">
<!-- address-->
<input type="text" name="address" placeholder="Street address" required>
<input type="text" name="city" placeholder="City" required>
<input type="text" name="state" placeholder="State" required>
<input type="text" name="zipcode" placeholder="ZIP/Postal code" required>
<select name="country">
<option selected value="United States">United States</option>
<option value="United Kingdom">United Kingdom</option>
</select>
Handling form validation errors
The plugin will check for form submission errors based on the mark-up you provide. Any inputs marked as required and not submitted will stop the form from being submitted.
<input type="text" name="firstname" placeholder="First Name" required>
The plugin will apply an error class .has-danger to the parent element of the input that failed.
<!-- .has-danger is applied to the div below if an error occurs-->
<div class="form-group">
<input type="text" name="firstname" class="form-control form-control-danger" placeholder="First Name" required="">
<div class="form-control-feedback">This field is required.</div>
</div>
You can use the mark-up above to create user friendly feedback when form errors occur. If you use our style sheet the mark-up above style the input red and display the feedback text when a validation error occurs.
Initialization options
When you initialize the form argument is a has of properties (see above).
tudoforms.initLeadForm(options);
formId (required)
This is the ID of the form element that contains your form inputs. Your form input should look like this below:
<form id="td-form" action="#" data-persist="garlic" autocomplete="off">
contactFormId (required)
This is the ID of a div wrapper that contains the form.
successFormId
This is the ID of a div element that contains your submission success view. When the form is successfully submitted we will hide the contactForm and show the successForm. If you omit this property we will display a success message using the system alert box. The success form can also contain a restart button to reset the form back into view (see below)
<div id="form-success" class="" style="display:none;">
<h2>Form submitted, thank you.</h2>
<p>Your form was submitted</p>
<button type="button" id="td-form-restart">CLOSE</button>
</div>
restartBtnId
The ID of a button added to the successForm for resetting the form back into view after the form was submitted (see example above).
attachmentsUploadBtnId
This is the ID of a button that will open the filepicker for uploading of images and files. Your button should look like this below:
<!-- attachments-->
<button type="button" class="btn upload" id="td-upload_button">Upload files</button>
<div id="td-attachments-html"></div>
(Note a div "td-attachments-html") this is required to display attachments see below.)
attachmentsHolderId
This is the ID of a div container for holding each attachment or image when uploaded. See the above example.
submitBusyStr
You can provide a html string that will be inserted into the submit button when the form is submitted. This can be used to provide a visual indicator that the form is busy.
submitBusyStr: "<i class='fa fa-circle-o-notch fa-spin m-r-5'></i>Sending"
In the above example we use font-awesome to provide a spinning busy indictor.
Using the international telephone input
A JavaScript plugin for entering and validating international telephone numbers. It adds a flag dropdown to any input, detects the user's country, displays a relevant placeholder and provides formatting/validation methods.
You can initialize the International Telephone Input plugin with your form. This is required if you want to collect Mobile phone numbers for using with SMS from Tudodesk.
Include the optional style sheet.
<link rel="stylesheet" href="https://td-cdn-1.netlify.app/js/intl-input/css/intlTelInput.css">
Include the plugin script
Place this before the tudoforms plugin script.
<script src="/js/intl-input/js/intlTelInput.js"></script>
Add the mark-up for a mobile number to your form
<div class="form-group">
<input autocomplete="off" id="intl-mobile" type="tel" name="mobile" data-country="us" placeholder="Mobile phone number">
</div>
Make sure your input has the following attributes
id = "intl-mobile" (this tells the plugin to init on this input)
data-country="us" (your local country code)
name = "mobile"
Initialize the plugins util script loader
Include the property below in your plugin initialization hash:
tditi_utilsScript: "/js/intl-input/js/utils.js"
tudoforms.initLeadForm({
formId: "td-form", // add this ID to your <form>
.. YOUR FORM SETTINGS HERE ..
tditi_utilsScript: "/js/intl-input/js/utils.js"
});