Customization
How to customize your forms, behaviour and design
While default CSS themes were designed to blend in with some simple blog designs, you might want or even require (in certain) cases to customize the look of your form to match existing content. There are two types of customization you can do: behaviour and design. The behaviour customization allows you to control certain functionality of your form, while design may change your form's look completely by modification to CSS classes provided with the form.
All of the files loaded by Odamae are not minified. We decided to give up the benefit of few kilobytes size in favour of readability for purposes of customization (excluding some of the third-party libraries). The JavaScript code and CSS file driving the forms are pretty simple and straight forward. You should not find anything out of the ordinary in those files, they were done as simple as possible. We should note, that jQuery is required in order to run Odamae form.
Design
Few notes on how to change the design
The easier way to change the design is to modify the CSS file and that where a small trick comes in. To avoid unnecessary steps (copy this here, copy that there), we have created a single block of code to load your form, which required a few simple modifications to way files are loaded. The main (and only) CSS file for the form based on light/dark theme is loaded via the JavaScript file provided with your form's code. The CSS file is appended to the <head> element.
In certain cases you may want not want to load CSS dynamically and we've created a simple way to direct our script not to load CSS style if hidden field with id odamae-use-css is present and set to true. To disable default CSS from being loaded, just include this hidden field anywhere on your page. In fact, you can include it right next to the form code, but remember not to place it under <form> element to prevent it from being sent with your form. For example:
<script type="text/javascript" src="http://path-to-odamae/api/js/light.js"></script>
<input type="hidden" id="odamae-use-css" value="true">
<form id="odamae-contact-form" method="post">
<div class="odamae-row">...
You can then download the CSS code, include it to your main style sheet, and modify as needed. We assume that if you are reading this, you have some basic CSS experience and we trust you'll find your way around. Just in case we have a few comments in our CSS files and we'll be adding more as we go along.
!important trick
In some cases you might want to change a single element style, button, etc. You can load the default style as usual, but add required style class into your main CSS and mark your changes with !important property for them to take priority over the style loaded by Odamae.
Download CSS for light themes here and for dark themes here.
Behaviour
How to change the form behaviour
As with CSS styles, the one and only JavaScript file is loaded with no minification (besides the third-party scripts which do not require any modification). One may download the JavaScript file and modify the code directly to perform all types of validation, effects, etc. But...for some ease, we provided way to control most of the actions via outside functions, part of window object, which you may define and use.
window.invalidInput()
The default behaviour for invalid input is an error message which displays below all of the fields. You may modify this behaviour by defining this function in your main JavaScript file or inline next to the form code. The example below shows a simple way to inline the definition of the code and applies to all functions discussed in this section.
<script type="text/javascript" src="http://path-to-odamae/api/js/light.js"></script>
<script>
window.invalidInput = function() {
alert('invalid input to contact form example');
}
</script>
<form id="odamae-contact-form" method="post">
window.odamaeValidateInput()
If defined, this function will be executed before sending AJAX request with the data found in the form. The data is passed as key-value object with ALL fields marked with Odamae's CSS class (.odamae-input, .odamae-textarea). Please note, the data object will contain required field named "apiKey" which should not be removed or modified by this function in order for a form to work properly.
window.odamaeBeforeLoad()
The default "wait" action is a simple change in action button text. You might want to modify this by providing your own (ex. spinner). Define window.odamaeBeforeLoad function to execute just before your form is submitted to our servers.
window.odamaeComplete()
If defined, this function will execute on completion of AJAX request. The execution of this function does not mean successful result and the parameter must be inspected to determine the outcome of your request. Please refer to original JavaScript files code (below) for information on return codes and messages (those are pretty easy and outlined in the JS file).
window.odamaeError()
This function will only be executed if AJAX request fails or returns unexpected result. For example, if the service is unavailable (we'll try to make this event extremely unlikely), then this function will executed if defined.
That's all
In addition to above functions, you may download the entire JavaScript code file and change it as you like. However, you should keep in mind to leave out the URLs and any of the components of those URLs in order to send requests correctly. In addition, please make sure you are sending the correct data to avoid unwanted responses.