AJAX
Upgrade your HTML/OS App
Documentation
clearjs.org is no longer registered. You can still get to the website at https://wbl.me/clearjs.org/home
AJAX Library Features and Documentation
note: If you are using this on a version of HTML/OS prior to 4.50 please see compatibility notes at the end of this document.
Loading ClearJS
Load HTML/OS Library and Javascript Code
<<expand file="/system/clearimage/DLL.lib" /expand>>
...
<script src="/apps/clear/clear.js"></script>
Specify what gets AJAX
To enable simply add the word AJAX to the form, element, or anchor. Apply AJAX to TEXT, TEXTAREA, RADIO, CHECKBOX, HIDDEN, PASSWORD, SELECT, IMAGE, and SEARCH. It will also work with custom input types. You can even add AJAX to div's, this is experimental. Add it something like <div href="theoverlay" AJAX>...</div>
Forms
<form action="theoverlay" method="POST" AJAX>
Form Elements
<input ... AJAX>
Anchors
<a href="theoverlay" name="myvar" value="myval" AJAX>
Ajax Triggers
The AJAX tag can have an event value like AJAX="keyup". This will change the event that is used to trigger the AJAX. By default the trigger event is onchange.
<input type="text" name="myname" AJAX="keyup"><br>
By default all elements of a form will be submitted when a form element has AJAX applied. To exclude a form element from being submitted use HOLD with the form element. For example to keep a textarea from submiting when other elements change do this...
<textarea name="mystory" HOLD></textarea>
Your HTML/OS pages look like this
<<
expand file="/system/clearimage/DLL.lib" /expand
>>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>CLEAR.js Page</title>
<script src="/apps/clear/clear.js"></script>
</head>
<body>
<a href="doit" AJAX>Link</a>
<div id="thehtmlelement">Hello World!</a>
</body>
</html>
<<overlay doit
writeHTML('thehtmlelement','Hello AJAX World!')
endOVERLAY()
>>
New HTML/OS Tags
These tags are for overlays
writeHTML(element,HTMLtext)
appendHTML(element,HTMLtext)
prependHTML(element,HTMLtext)
updateVARS('myvarlist')
runSCRIPT(text)
endOVERLAY()
ajaxGOTO('otherPageOrOverlay')
endOVERLAY, ajaxGOTO
Either of these tags replace goto and can be used safely even if AJAX isn't present.
updateVARS
This tag will update any client side variable specified with the current server values
writeHTML, appendHTML, prependHTML
These tags will modify the content of the client side HTML element. For example a div with an ID of message (<div id="message"></div>) can be manipulated with writeHTML('message','Success!!') in your Overlay code.
runSCRIPT
This will run the javascript (text) at the client
AJAX.clicked
This returns the INPUT element that triggered the submission, and is used in your overlay code to determine which element changed.
Monitoring AJAX
Once you have AJAX applied to your elements you may desire to give visual feedback while the user awaits a response, or you may need to perform some validation before continuing with the submission.
To accomplish this you need to write Javascript functions to run before the AJAX is submitted to the server, and optionally a function run run after the server returns.
<script>
function onAJAX(el){
alert('AJAX will send now');
}
</script>
To do some kind of validation. "return false" this will abort the submission.
<script>
function onAJAX(el){
if (el.value==''){
alert('Aborting...empty field');
return false; // abort
} else {
alert('AJAX will send now');
}
}
</script>
These will work for very simple cases but other scenarios may require finer control. The javascript functions onAJAX, afterAJAX, and expiredAJAX will have access to the following properties element.value, and element.event. writeHTML is both an Aestiva function and also a Javascript function. If you use it with Javascript remember to add a semicolon at the end and also remember Javascript is case sensitive. Here is a more elaborate example.
<script>
function onAJAX(element){
// element is the element that the ajax is/was called on
// element.name - the name of the element, this corresponds with the aestiva variable of the same name
// element.value -
// element.event - The action that triggered the AJAX. By default it is "change".
writeHTML('ajaxprogress','Loading...');
}
function afterAJAX(element){
writeHTML('ajaxprogress','');
}
function expiredAJAX(element){
document.location='http://clearjs.org';
}
</script>
Compatibility Notes
If you are using this library with versions of Aestiva HTML/OS prior to 4.50 a few changes in the syntax are neccesary.
Generally there are two issues that could affect usage prior to version 4.5
Variable expands
- Variable expands can be disabled, so make sure they are enabled
- Expands in pre 4.5 versions can trigger an 'out of memory' condition if used inside a function
To make your code compatible with versions prior to 4.5 use an alternate syntax for endoverlay and ajaxgoto.
expand file=endOVERLAY() /expand
and ajaxgoto
expand file=ajaxGOTO('otherPageOrOverlay') /expand
Tags that are not used for assignment
In several versions prior to 4.5 you can not have a tag all by itself like this...
runSCRIPT(^alert('Hello World');^)
Overcome this by making it an assignment like...
o=runSCRIPT(^alert('Hello World');^)
Notice the lowercase o. It was chosen as it is unlikely that it will be used as a variable in any other code.
If you have a project you would like to try CLEARjs on I would love to help. Send me an email.
