JavaScript
Uray Web Library (UWeb)
This documentation page describes most of the JavaScript functionality of UWeb (with the exception of AJAX, which is described in ajax.html). For example, this page describes how to define locally unique identifiers in UWeb; how to set up actions for buttons; how to deal with forms etc.
Many of UWeb's JavaScript functionality can be used without writing any JavaScript code, by defining certain special attributes which UWeb understands and processes. See UWeb attributes below for more information.
This page also describes ways to create certain HTML elements with JavaScript, including input fields and buttons, see the create_*() functions. Note: there are similar functions that can create these elements from PHP, generating HTML code, see active.php.
In order to use the JavaScript functionality of UWeb, its JavaScript code must be made available for the webpage, see Generating JS. Note that many of the features also require certain CSS styles, see Generating CSS for more information (especially its second part, active.css.php).
Note: to visually see many of the features described in this page, see e.g. the test file test/active.html (and its source, test/active.php) in UWeb's directory.
5.3. data-action='scroll-center'
The webpage can define certain attributes on HTML elements, starting with data- (e.g. data-id, data-form, data-action etc.), to invoke certain functionalities of UWeb without writing any JavaScript code. Most of these attributes are described throughout this documentation page. (Those that are specific to AJAX are described in ajax.html: data-component, data-global and data-param.)
For many of these attributes, UWeb needs to preprocess the elements in order for the functionalities to work properly. This happens automatically in most cases, e.g. if the HTML content is part of the downloaded .html file (e.g. generated by the PHP), or if it comes from UWeb's AJAX commands. However, if new HTML elements are added by JavaScript (outside of UWeb's control), then UWeb needs to be informed about this new content by calling constructor() on it, otherwise these attributes will not work properly.
data-id='id'
This UWeb attribute defines hierarchical identifiers for HTML elements.
The difference from the standard id attribute is that id must be unique in the whole document, while data-id only needs to be locally unique within the closest ancestor that has an identifier. For example:
<div data-id='a'>
<div data-id='1'> <span data-id='x'></span> </div>
<div data-id='2'> <span data-id='x'></span> </div>
</div>
<div data-id='b'>
<div>
<div data-id='1'> <span data-id='x'></span> </div>
<div data-id='2'> <span data-id='x'></span> </div>
</div>
</div>
In this example, there is no conflict between the two data-id='1''s, because they have ancestors with different identifiers; the same is true for the four data-id='x''s.
The data-id system is not independent from the id's. In fact, the data-id's are simply translated to id's, prefixed by the closest ancestor's id, if any, separated by a colon (:), as in ancestor-id:this-id. So in the above example, the data-id's will be translated to the following id's, respectively: a, a:1, a:1:x, a:2, a:2:x, b, b:1, b:1:x, b:2, b:2:x.
The function find_id() below can be used to find elements by their local data-id (as opposed to using document.getElementById() to search id's globally, which is of course also possible).
There are two other attributes that, besides their additional meanings, also act like data-id: data-form and data-name.
function find_id (id, elem = null);
Find the element with the given identifier id, relative to elem if given.
It can be used to search for the local identifier defined by the data-id attribute. For example, in the example for data-id above, if elem is the <div> in the second line, then find_id("x", elem) returns the <span> inside that elem, and find_id("2", elem) returns the <div> in the third line.
id: the identifier (id attribute) to search for. It can be the full identifier (e.g. "a:1:x" in the above example), or, if elem is given, a relative identifier (e.g. "1:x" or "x"). A special identifier is "@", which means "itself", i.e. to return elem itself. For convenience, id can be null, in which case the function also returns null.
elem: the HTML element relative to which the search is performed. If this is omitted, then the function is generally the same as document.getElementById(id) (except if id is "@" or null) – but even then, find_id(id) has the advantage of being shorter.
Return value: the HTML element found for the given identifier, or null if it does not exist.
Note: most of UWeb's functionality, including the data-* attributes, use this function to find elements by id relative to an already known element. For example, data-action='hide(id)' will search the element to hide by this function, relative to the element on which that data-action attribute is defined.
Actions can be defined for buttons, links, input elements, forms etc. to do something when they are activated, i.e. to execute a function (JS or PHP), manipulate the page etc.
There are several ways to define an action, one of which is the data-action attribute (intended to be given on static HTML, e.g. when generated by PHP), and another is the set_action() function (intended to be used in JavaScript). But in many cases, a simpler way is to generate the dynamic elements (e.g. buttons) using UWeb's functions such as create_button() (JS) or button() (PHP), which expect an action in parameter.
An action can be a string (see Action strings) or a JavaScript function (which is simply called with no argument, but it gets the fired element as this). The data-action attribute only accepts a string, but set_action() accepts both types.
For example, the PHP code
echo button("Button", "f:some-function");
generates the HTML code
<button , data-action='f:some-function'>Button</button>
which is a button that calls the JavaScript function f_some_function() when pressed (see Action strings).
A button can also be created by JavaScript: the code
create_button("Button", some_function)
returns a button that calls the JavaScript function some_function() when pressed.
data-action='action'
This UWeb attribute defines an action (see above) for a button, input element, form etc.
See the next section, Action strings about the possible values of this attribute.
See data-when about when exactly the action will be fired.
When an action is given as a string (e.g. with the data-action attribute above), it is a list of one or more atomic actions separated by semicolons (;). The most important atomic actions are the following:
q:query or q:query(args): run an AJAX query, and call the PHP method q_query() on the current page or component class, passing the arguments if given. For more information, see AJAX. (Note: dashes are converted to underscores, e.g. data-action='q:some-query' will call q_some_query()). f:function or f:function(args): call the JavaScript function f_function(), passing the arguments if given. The this inside the function will be the element on which the action was defined. (Note: dashes are converted to underscores, e.g. data-action='f:some-func' will call f_some_func()). remove(id): remove the HTML element with the given id from the page. The identifier is relative to the fired element. hide(id): hide the HTML element with the given id (relative to the fired element). Hiding means to set the CSS class off on the element, which is defined by UWeb, and it sets the CSS style display:none. (The advantage of off over directly setting display:none is that off can be easily undone, without knowing the previous value of display.) show(id): show the HTML element with the given id again, by removing the CSS class off set by hide(id) above. toggle(id): show or hide the HTML element with the given id. This is equivalent to hide(id) if the element was visible, and show(id) if it was hidden. toggle(id,class): add or remove the given CSS class to the HTML element with the given id, depending on whether the class was absent or present on it. Note: toggle(id) above is equivalent to toggle(id,off). redirect(url) or redirect(url,target): redirect the browser to the given url (which can be absolute or relative). The optional target means the same as for an HTML link (<a href='...' target='...'>), e.g. _blank opens the URL in a new browser tab. none: do nothing. (Note: this action can be useful in several cases, e.g. when another attribute, such as data-first-action requires the presence of the data-action attribute; or when an input element is not meant to execute the action of the form, which would be done by default if the input element had no action defined.) There are many other built-in actions, but they are described in other sections of this page (titled data-action='something').
data-when='load|change|enter'
This UWeb attribute defines when an action (e.g. a data-action attribute) is fired.
By default, actions are fired in the following cases, depending on the type of the element:
<textarea>, because it uses Enter to insert a new line, but it can be changed by data-when='enter', see below). <div>): the element becomes clickable, and the action is fired when the element is clicked. The above default behaviour can be changed by data-when. It accepts the following values:
load: the action fires when the element is loaded (e.g. on page load). change: the action fires when the input element is modified. This option only applies to input elements (<input>, <select> etc.). enter: same as the default, except that for <textarea>, it is also fired when pressing Enter (like for <input> elements). function set_action (elem, action);
Set an action on the HTML element (button, input element, form etc.) for when it is activated (e.g. clicked).
action: the action to be set. It can be either a function or an action string.
See data-when (its default behaviour) about when exactly the action will be fired, and see also set_action_onchange().
function get_action (elem);
Return the action of the element, which was set by e.g. set_action() or the data-action attribute.
If it has no action, return null.
function set_action_onchange (elem, action);
Set an action (a function) on an input element for when its value changes.
elem: an input field, e.g. <input>, <textarea>, <select>.
action: a JavaScript function. It can access the element as this.
function fire (elem); // 'elem' can also be given as 'this'
Fire the action of the given element, which was set by e.g. set_action() or data-action.
function fire_action (elem, action);
Fire the given action (string) on the element, regardless of its own action, if any.
action: the action string to be fired. It can only be an atomic action (i.e. not multiple actions separated by semicolons).
data-first-action='action'
This UWeb attribute is similar to data-action, except that it can only be fired once, at the first time when it is activated.
See Action strings about the possible values of this attribute.
This attribute works only if the data-action attribute also exists (but it can be none).
data-key='key:action'
This UWeb attribute defines actions for certain key combinations when this element has the focus.
For example, the following textbox can be deleted by the Ctrl+Delete key combination when it has the focus:
<input type='text' value='Delete me' data-key='ctrl+del:remove(@)'/>
The value of the data-key attribute is one or more key:action pairs, separated by semicolons (;), where action is an action string, and key represents a key combination, which can be one of the following:
A, B, ..., Z, a, b, ..., z); 0, 1, ..., 9); F1, F2, ..., F24, f1, f2, ..., f24; up, down, left, right, pgdn, pgup, home, end, enter, space, insert, del, delete, esc, escape, tab, backspace (all lowercase); ctrl+ and/or shift+ (in lowercase). Requirement: $has_key if the website generates its own JavaScript
function add_key (elem, key, action);
Add an action to the element for when a key combination is pressed.
elem: the HTML element that must have the focus for this key combination to work.
key: the key combination as a string, e.g. "ctrl+f4", see data-key above for more information.
action: the action to execute. It can be either a function or an action string.
Requirement: $has_key if the website generates its own JavaScript
A form is a collection of input elements and/or other data that, when submitted, can be processed by program code.
In UWeb, a form is defined by the attribute data-form on any HTML element (e.g. <div>). It can be used to submit an AJAX query, in which case the data will be processed by the server-side PHP code. Or, alternatively, it can be processed by JavaScript, see get_form_data() and the examples below.
The main difference from the standard <form> element is that the latter, when submitted, makes the browser load another page (or reload the same page) to make the server-side script (e.g. PHP) process the sent data, while an UWeb form can process it without affecting the whole page, e.g. with AJAX, or on the client side.
An UWeb form may have the following:
data-name attribute; data-name/data-value attribute pair (note: they can be generated e.g. by hidden_params()); data-action attribute), which defines the action of the submit button of the form, and also that of all input elements that have no actions on their own; data-highlight attribute to highlight the submit button when an input field changes in the form. A minimal example:
<div data-form='form' data-action='f:process-form'>
<input type='text' data-name='sometext'/>
<input type='checkbox' data-name='bool'/>
<button data-submit>OK</button>
</div>
<script>
function f_process_form () {
var data = get_form_data(this);
alert(data.sometext + " - " + (data.bool ? "checked" : "not checked"));
}
</script>
Or the same form generated by JavaScript:
window.onload = function () {
var form = create_form("form", process_form, [
create_textbox("sometext"),
create_checkbox("bool"),
create_submit_button("OK"),
]);
document.body.append(form);
constructor(form);
}
function process_form () {
var data = get_form_data(this);
alert(data.sometext + " - " + (data.bool ? "checked" : "not checked"));
}
data-form='form-id'
This UWeb attribute creates an UWeb form from an HTML element, see above.
The given form-id identifies the form. It behaves in the same way as the data-id attribute: its identifier must be locally unique, and it defines an identifier context like data-id.
function find_form (elem);
Return the form that belongs to the given HTML element, or null if there is none.
That form is generally the closest ancestor that has the data-form attribute. But if elem has the data-target-form attribute, then the referred form will be returned.
data-name='name'
This UWeb attribute identifies the input fields (or other data elements) within an UWeb form.
This attribute is used by e.g. get_form_data() to name the returned properties. Also, when submitting an AJAX query, the POST parameters will be named after their data-name attributes.
There is one exception, the radio button (<input type='radio'/>), where the data-name attribute must not be put directly on the input element, but instead on an ancestor element that contains the group of all mutually exclusive radio buttons. See an example at the PHP function radio_button().
Note: data-name plays a similar role in a data-form than the standard attribute name in a <form>, but they are not interchangable.
Note: the data-name attribute, in addition to its properties described above, also acts like the data-id attribute.
function get_form_data (form); // returns params function get_form_data (form, params);
Collect the values of all input fields and other data inside the given form. This function can be used to process the form data in JavaScript.
If the second parameter (params) is given, then the collected values will be added to that object, otherwise a new object will be returned with the collected values.
The function searches all elements within the form that have the data-name attribute, and inserts their values into params under the keys defined by data-name. The values will be queried as described at get_value().
For example:
<div data-form='form'> <input type='text' data-name='text' value='Some text'/> <input type='checkbox' data-name='check'/> <span style='display:none' data-name='hidden' data-value='123'></span> </div>
For the above form, get_form_data() will return {text: "Some text", check: 0, hidden: "123"} (assuming that the fields have not been changed). See a more complete example at Forms.
This function also performs checks if some elements contain the data-check or data-required attribute or the uweb_check property (and the JavaScript was generated with the $has_check option). If any of that check fails, the values are still collected, but params will contain the property params.error = true.
function get_value (elem);
Return the value of the given HTML element. It is usually an input field, in which case the entered value (usually elem.value) is returned. Or if the element has a hidden value such as data-value, then its value is returned. This function is used by e.g. get_form_data().
More precisely, the returned value is determined as follows:
elem has the JavaScript property elem.uweb_value, then its value is returned as it is (which can be a string, a number, an object etc.), except if it is a function, in which case it is called (with no argument, and this set to elem), and its returned value is returned. elem has the attribute data-value, then its value is returned (as a string). elem is an input field (e.g. <input>, <textarea>), then its entered value (usually elem.value) is returned, usually as a string, with the following exceptions: <input type='number'/>: the value is returned as a number. <input type='checkbox'/>: the state is returned as a number: 1 for checked, and 0 for unchecked checkbox. <input type='radio'/>: it can also be queried like a checkbox, but it makes more sense to query a group of radio buttons: if elem is an element that contains a group of mutually exclusive radio buttons (usually elem is the element with the data-name attribute), then the return value is the data-id of the selected radio button, or null if none is selected. <input type='file'/> (including the hidden one created by data-upload): a JavaScript File object is returned representing the selected file, or null if no file was selected. <select>: for a single-selection list, the data-id of the selected <option> is returned, or null if none is selected; for a multi-selection list (<select multiple>), a comma-separated list of data-id's is returned for the selected <option> elements, e.g. "id1,id3,id4", or the empty string ("") if none is selected. <button>: it is treated as a checkbox, depending on whether the CSS class pushed is present on it: 1 is returned if it is pushed, and 0 otherwise. The class pushed makes the button look permanently pushed. A button that automatically toggles this class when clicked can be created by e.g. setting data-action='toggle(@,pushed)'data-value='value'
This UWeb attribute defines the value of a hidden or complex data element in a form. This attribute works in combination with data-name.
The difference from the standard attribute value is that the latter is used for input elements, but data-value is used anywhere else where the value is not applicable.
For example, hidden data in a form can be defined as follows (see e.g. hidden_params()):
<span data-name='name' data-value='value'></span>
Note: the same effect can be achieved by an <input type='hidden'/> element, but the latter is less reliable, because like all <input> elements, it may be unexpectedly changed by the browser (e.g. when refreshing the page, the browser might keep the original value even if the reloaded page provides a different one). The data-name/data-value method has no such problem.
The JavaScript property uweb_value can be set on any HTML element to define its value in the same way as with data-value, but uweb_value is more convenient to be used in JavaScript, and it can have any type, not just string, e.g. it can be an object. It can also be a function, which calculates the value of the element (it takes no parameters, and it receives the HTML element as this).
A submit button is a special element in a form: when it is activated, it executes the action of the form.
It is defined by the data-submit attribute on the element, which is typically a button (or sometimes a link). Submit buttons can be easily created by the create_submit_button() (JS) or the submit_button() (PHP) function.
The submit button also serves as a visual indicator for the form. For example, when the action takes too long (such as an AJAX query), the submit button shows visual indication about it to the user (e.g. with ellipsis: "…"). It can also show that an input has been changed in the form, see the data-highlight attribute.
data-submit
If this UWeb attribute is present on an element (usually on a button), then it will serve as the submit button of the enclosing form, see above.
data-highlight
If this UWeb attribute is present on an UWeb form, then its submit button will be highlighted whenever an input field changes in the form. This can be useful e.g. if the submit button is a "Save" button, to give a strong visual indication to the user that the data has been modified but not saved yet.
Highlighting means to add the CSS class highlight to the button, which, by default, changes the text color of the button to red (but see $button_highlight_color).
function highlight_submit (elem); // 'elem' can also be given as 'this'
Highlight the submit button of the form.
elem: any element inside the form (including the form itself). The form will be found by find_form().
Highlighting means to add the CSS class highlight to the button, which, by default, changes the text color of the button to red (but see $button_highlight_color).
function unhighlight_submit (form); // 'form' can also be given as 'this'
Unhighlight the submit button of the form, i.e. undo the effect of highlight_submit().
form: either the form, or its submit button (otherwise the function does nothing).
data-required='message?'
If this UWeb attribute is present on an input field in a form, then the field must be filled by the user before it can be submitted. More precisely, if the field is left empty:
get_form_data() will set params.error = true in the returned object, and so the JavaScript code can easily check for it (see the example for data-check); message is given in the attribute, then an error mark with this message will appear next to the input field when trying to submit the form. Requirement: $has_check if the website generates its own JavaScript
data-check='js-code'
This UWeb attribute can be set on forms and input fields inside forms. It can be used to check the value of the fields before submission, by a simple inline JavaScript code. If the check fails, the form cannot be submitted.
The inline JavaScript code can refer to the following names:
data-check is on an input field, then x refers to the value of the field (as if returned by get_value()). data-check is on a form, then the values of all fields are available in the code under their data-name names (as if returned by get_form_data(), but without error checking). error (message=null, id=null) will be available in the code to report failure, where message is an optional error message that will be displayed in an error mark, and id, if given, is the identifier of the element (relative to the form) for which the error mark is displayed. The default location of the error mark is the input field on which the data-check attribute was given, or the submit button if it was given on the form. If the check fails, it has the same effect as if a data-required field is left empty.
In the following example, the user must enter two numbers, min and max, such that 1 <= min <= max <= 100. The two input fields are first checked separately by their respective data-check attributes, and then they are compared by the form's data-check.
// PHP
echo "<div data-form='form' data-action='f:process-form'";
echo " data-check='",attr_escape("if (max < min) error('max < min', 'max');"),"'";
echo ">";
echo input("number", "min", ["data-check" => "if (x < 1) error('too little');"]);
echo input("number", "max", ["data-check" => "if (x > 100) error('too many');"]);
echo submit_button("OK");
echo "</div>";
// JavaScript
function f_process_form () {
var params = get_form_data(this);
if (params.error) return;
alert(params.min + " - " + params.max);
}
Requirement: $has_check if the website generates its own JavaScript
The JavaScript property uweb_check can be set on forms and input fields inside forms to a function that checks the value of the fields before submission. It is similar to data-check, but the latter is intended to be given on static HTML (e.g. by PHP), while uweb_check can be set by JavaScript.
The given function must have the following signature:
function check (value, error);
value: for an input field, it receives its value, as if returned by get_value(); and for a form, it receives all the data in the form, as if returned by get_form_data(), but without error checking.
error: a function to report failure in the function. Its signature is error (message=null, id=null), where message is an optional error message that will be displayed in an error mark, and id, if given, is the identifier of the element (relative to the form) for which the error mark is displayed. The default location of the error mark is the input field on which the uweb_check attribute was given, or the submit button if it was given on the form.
For the exact effects of the failure, see data-required.
Requirement: $has_check if the website generates its own JavaScript
data-confirm='message|{js-code}'
This UWeb attribute causes a confirmation popup to be displayed before firing the action of the element, and the action will only be executed if the user confirms it.
If the value of the attribute is text (HTML code), it will be the message of the confirmation popup. But it can also be a JavaScript code enclosed in curly braces ({ and }), which calculates (returns) the message of the popup. The code can use this, which is the fired element.
The label of the "Yes" button will be by default the label of the button whose action is to be executed, and the label of the "No" button will be by default "Cancel", but see data-confirm-yes and confirm_popup().
Examples (in PHP):
echo button("Delete me (1)", "remove(@)", ["data-confirm" => "Are you sure?"]);
echo button("Delete me (2)", "remove(@)", [
"data-confirm" => "{return 'Delete the button called \"' + this.textContent + '\"?';}",
"data-confirm-yes" => "Delete it",
]);
Requirement: $has_confirm if the website generates its own JavaScript
Note: this attribute has no effect if there is no action (e.g. data-action attribute) on the element.
data-confirm-yes='label'
This UWeb attribute defines the label of the "Yes" button for data-confirm.
The JavaScript property uweb_confirm causes a confirmation popup to be displayed before firing the action of the element, and the action will only be executed if the user confirms it.
It is similar to data-confirm, but the latter is intended to be given on static HTML (e.g. by PHP), while uweb_confirm can be set by JavaScript.
This property must be a function with the following signature:
function confirm ();
It receives the fired element as this, and it must return the content of the confirmation popup either as text, or as an HTML element object.
Requirement: $has_confirm if the website generates its own JavaScript
Note: this property has no effect if there is no action (e.g. data-action attribute) on the element.
function submit_form (elem); // 'elem' can also be given as 'this'
Submit the form that contains the given element, i.e. execute its action.
elem: any element inside the form (including the form itself). The form will be found by find_form().
data-action='submit'
This action submits the form that contains the fired element (see find_form()), i.e. executes its action.
data-target-form='form-id'
This UWeb attribute allows an action to be taken on behalf of a form even if this element is not contained inside that form.
form-id: the identifier of the form, i.e. its data-form attribute (relative to this element).
When the element in question fires an action, it will act as if it were contained within that form, e.g. all input fields in the form will be submitted for an AJAX query, and the form will be found by find_form().
This attribute can be useful for popup windows which logically belong to a certain form (e.g. confirmation popup), but which are not technically inside that form.
data-details='details-id'
This UWeb attribute assigns additional details to a checkbox, radio button or list selection (<select>/<option>).
The details-id is the identifier of the element (relative to the current input element) that contains additional details (e.g. text) about the input field. That element will only be visible while the checkbox, radio button or <option> is selected.
Example (PHP):
echo "<p data-form='form' data-name='radios' data-action='none'>";
echo radio_button("radios", "r1", ["data-details" => "d1"]);
echo radio_button("radios", "r2", ["data-details" => "d2"]);
echo radio_button("radios", "r3", ["data-details" => "d3"]);
// Only one of these will be visible at a time, depending on the radio selection:
echo span("[Details 1]", "off", ["data-id" => "d1"]);
echo span("[Details 2]", "off", ["data-id" => "d2"]);
echo span("[Details 3]", "off", ["data-id" => "d3"]);
echo "</p>";
This attribute works only if the input field has an action (e.g. a data-action attribute), either directly, or through its form, like in the above example (but the action can be none).
Requirement: $has_details if the website generates its own JavaScript
data-tip='text'
This UWeb attribute defines a popup tooltip for the element, which is displayed when the mouse hovers over the element.
The value of the attribute is the text (HTML code) that appears in the popup tooltip.
See also info_text(), qmark().
Optionally, a data-dir='dir' attribute can also be given on the element to specify the direction of the popup tooltip relative to this element, e.g. data-dir='bottom-right'. See the dir parameter of show_dropdown() for all possible directions.
Requirements: $has_tooltip (JS) and $has_tooltip (CSS) if the website generates its own JavaScript and/or CSS
function show_mark (elem, type, content);
Show a little popup box (mark) next to an input field (or other element). It can be used to provide a small visual feedback to the user, such as an error message about the entered value, or that an operation has been successfully completed.
elem: the mark will appear next to this element.
type: the type of the mark, or null. It determines the appearance of the mark, e.g. color, or that a specific symbol (e.g. exclamation mark) is attached to it. It works by adding the CSS class mark-type (e.g. mark-error) to the mark. The following types are supported by UWeb (other than null):
"error": indicates an error message. The mark will contain an exclamation mark (!), whose color is by default red ($mark_error_color). "info": indicates a neutral informational message. The mark will contain an exclamation mark (!), whose color is by default the text color ($mark_info_color). "success": indicates a success notification. The mark will contain a checkmark (✔), by default green ($mark_success_color), and the mark will disappear in a few seconds. "alert": indicates an important message. The text will be bold and by default red ($mark_alert_color). content: the content of the mark. It can be either a string (text content), a Node (e.g. a HTML element), an array thereof, or null.
Note: marks can also be created by the AJAX command <!mark>, and error marks are also automatically created by form checks, such as the data-check attribute.
function hide_marks (elem);
Hide all marks created by previous show_mark() calls inside the given element (e.g. a form).
function show_popup (box);
Show a popup dialog box in the middle of the browser window.
box: the newly created HTML element (e.g. <div>) that will be displayed as the popup. (Note: the styling, e.g. border will be added by UWeb.)
By default, the popup will be automatically closed when another popup is displayed. This can be changed by setting the attribute data-permanent, which will keep this popup open behind new popups, except if the new popup has the same id as this one.
Example:
var box = create_div();
box.append(create_par("This is some information."));
box.append(create_div("buttons", [
create_button("OK", "close"),
]));
show_popup(box);
Note: popup boxes can also be created by the AJAX command <!popup>, and specifically confirmation popups can be created by the confirm_popup() function or by the data-confirm attribute.
function show_dropdown (box, button, type = null, dir = null);
Show a dropdown box next to the given element (e.g. a button). A dropdown box is a popup box that appears next to a certain button, link or similar element, when that element is clicked. It may contain a menu, or some extra information. The dropdown box can be closed by clicking that button again, or by clicking anywhere outside the box.
box: the newly created HTML element (e.g. <div>) that will be displayed as the dropdown box.
button: the button (or link etc.) that opened the dropdown, and next to which the dropdown will be displayed.
type (optional): type of the dropdown, to provide extra styles. It works by adding the CSS class dropdown-type (e.g. dropdown-big) to the element. The following types are supported by UWeb:
"big": make the border and padding thicker for the dropdown. "menu": make the dropdown's style better for a menu (this is used by the PHP function dropdown_menu()). dir: the direction of the dropdown box relative to button. Possible values:
"top-left", "top-right", "top" (= "top-center"), "bottom-left", "bottom-right", "bottom" (= "bottom-center"), the default. Note: a dropdown box can also be opened by data-action='dropdown', by the AJAX command <!dropdown>, and a dropdown menu can be created by the PHP function dropdown_menu().
Requirements: $has_dropdown (JS) and $has_dropdown (CSS) if the website generates its own JavaScript and/or CSS
data-action='dropdown' data-dropdown='content' data-action='dropdown(type)' data-dropdown='content'
This action opens a dropdown box next to the element on which the action was fired.
See show_dropdown() above for more information.
type (optional): the type of the dropdown (big, menu). See the type parameter of show_dropdown() for more information.
Further information can be given by the following attributes:
data-dropdown='content': the content of the dropdown box, in HTML. (Note: the string must be properly escaped, e.g. by attr_escape(), or a generator function such as button() can be used, which does this automatically, as in the example below.)
data-dir='dir' (optional): the direction of the dropdown box relative to the element that opened it, e.g. data-dir='bottom-right'. See the dir parameter of show_dropdown() for all possible directions.
For example, the following PHP code generates a button that shows a dropdown box:
echo button("Open dropdown", "dropdown", [
"data-dropdown" => "<p>First line</p><p>Second line</p>",
]);
Requirements: $has_dropdown (JS) and $has_dropdown (CSS) if the website generates its own JavaScript and/or CSS
function close_box (elem); // 'elem' can also be given as 'this'
Close the popup box, dropdown box or mark that contains the given element. If there are multiple candidates (e.g. a mark inside a popup box), then the closest one will be closed.
In general, this function can close (delete) anything that has the CSS class closable.
function close_popup (elem); // 'elem' can also be given as 'this'
Close the popup box that contains the given element.
data-action='close'
This action closes the popup box, dropdown box or mark that contains the fired element. If there are multiple candidates (e.g. a mark inside a popup box), then the closest one will be closed.
In general, this action can close (delete) anything that has the CSS class closable.
Note: in a popup box, popup_ok() etc. use this action to close the popup.
function confirm_popup (question, action, yes = null, no = null);
Create a popup dialog box with a confirmation question to the user. If will contain two buttons: an accept ("Yes") and a decline ("No") button, and if the user accepts, the given action will be executed.
question: the confirmation question displayed in the popup box. It is either a string or an HTML element.
action: the action to be executed if the user confirms. It can be either a function or an action string.
yes, no (optional): labels for the two buttons. The default values are "Yes" and "No", except if yes is given, in which case the default decline button is "Cancel". These default values are multilingual, but currently only English and Hungarian are supported, depending on the language of the page (e.g. <html lang='hu'>), the default being English.
Note: see also the data-confirm attribute, which automates the confirmation popup before executing a data-action.
Requirement: $has_confirm if the website generates its own JavaScript
function scroll_to (elem, mode = null);
Scroll the view vertically to the given element.
elem: the HTML element to scroll to.
mode (optional): specify exactly where to scroll to. This argument is only recognized if the JavaScript was generated with the $has_scroll_modes option. It accepts the following values:
null (default): scroll just enough to fit the element into the view. If it is already fully visible, nothing happens. "top": move the top of the element to the top of the view. "bottom": move the bottom of the element to the bottom of the view. "center": move the center of the element to the center of the view. By default, the view of the whole page is scrolled. But if there is another scollable, positioned ancestor of elem (positioned = the CSS position is not static), and the JavaScript was generated with the $has_scroll_relative option, then the closest such ancestor is scrolled.
data-action='scroll(id)'
This action scrolls the view vertically to the HTML element given by id (which is relative to the fired element). If it is already fully visible, nothing happens.
This action is equivalent to calling scroll_to() with that element and with no mode.
data-action='scroll-center(id)'
This action scrolls the view vertically to the center of the HTML element given by id (which is relative to the fired element).
This action is equivalent to calling scroll_to() with that element and with mode == "center".
Requirement: $has_scroll_modes if the website generates its own JavaScript
data-action='focus(id)'
This action gives the focus to the HTML element given by id, i.e. make it receive subsequent keyboard events.
The identifier (id) is searched relatively to the fired element.
This action is equivalent to calling the JavaScript function focus() on the element.
data-focus='priority'
This UWeb attribute indicates that this element should have the focus initially, i.e. it should receive keyboard events. If multiple elements have this attribute, then the one with the highest priority (integer) will have the focus.
The focus priority makes it convenient to define focus in various circumstances. For example, consider a form with potentially two input fields, where usually the first one should have the focus, but sometimes (depending on a condition) it is missing, and then the other one should have it. This can be easily achieved by setting data-focus='2' on the first field (if present), and data-focus='1' on the second one. Another example is a popup window: if the OK button of the popup has a higher data-focus than any other element on the page, then on appearance, the OK button will have the focus, but when the popup is closed, the focus will be automatically returned to the element that previously had it. (Note: UWeb's popup functions such as confirm_popup() and popup_ok() do this already: they set data-focus='99'.)
data-autogrow
This UWeb attribute makes a <textarea> grow automatically when its content exceeds its height.
This attribute works only if the input field has an action (but it can be none).
Requirement: $has_autogrow if the website generates its own JavaScript
function constructor (root, also_root = true);
Preprocess new content that was recently added to the page. This is needed for the UWeb attributes to work. It must be called when new content is added to the page without UWeb's knowledge (see below), right after its addition. For example:
var p = create_par("Some text", {"data-id": "123"});
document.body.append(p);
constructor(p); // otherwise data-id will not work
root: the root element of the newly added content. All of its descendants will be preprocessed.
also_root: if this is false, then the root element itself will not be processed, only its descendants. It it useful if the content of an element has been replaced, but the element itself not.
This function only needs to be called if UWeb does not already know about the newly inserted elements. In particular, it need not and must not be called in the following cases:
<!append>; show_dropdown(). However, it must be called in the following case:
existing_elem.append(new_elem). Note that it does not matter whether UWeb created the element (e.g. by create_element()) or not, it only matters whether the element was added to the page by UWeb or not.
The function must not be called more than once for the same element (or the element and its ancestor). But if multiple elements are added after each other, it is sufficient for constructor() to be called only once after the whole process (e.g. on their common parent, assuming that it has no other child on which it was already called).
See also destructor().
function destructor (root, also_root = true);
Tell UWeb that an element is about to be removed from the page. This is necessary for certain UWeb attributes to work properly, similarly to constructor(). It must be called right before the content is deleted, unless it is deleted by UWeb itself.
root: the root element of the content to be deleted.
also_root: if this is false, it means that the root element itself will not be removed, only its descendants.
Similar rules apply to this function than to constructor(), e.g. this function only needs to be called if UWeb does not already know about the deletion of the elements.
function delete_element (elem);
Remove the given HTML element from the page.
Note: this function performs all the necessary actions for UWeb before removal, so it is not required (nor allowed) to call destructor() before delete_element().
function is_element (x);
Return whether the given variable is an HTML element object, and not anything else (such as a text node, comment, other kind of object, string, number, null etc.).
function foreach (root, selector, func, also_root = false);
Run the given function for each element inside root that matches the given CSS selector, in document order.
root: the root element whose descendants are searched.
selector: CSS selector to search for, e.g. "div", ".some-class", "input[type=text], textarea" etc.
func(elem): the function to be called for each element. It takes a single parameter, the current element.
also_root: if this is true, then the root element itself will also be included in the search, otherwise only its descendants.
function get_window_size ();
Return the size of the browser window area available to the webpage, as an object of the form {width: 1280, height: 1024}.
Requirement: $has_window_size if the website generates its own JavaScript
function is_touch_screen ();
Try to detect whether the device has a touch screen or not.
Requirement: $has_window_size if the website generates its own JavaScript
function lng (...);
Choose a text from multiple languages, based on the language of the page.
The arguments of the function are the same text in multiple languages. (They can be strings or of any other type.) The order of the languages is determined by the variable $lng_langs when generating the JavaScript. This variable is required for this function.
The function chooses the argument that matches the language of the page, which is defined on the root element, e.g.: <html lang='en'> (or if not, then the first argument is returned).
For example, if $lng_langs == ["en", "hu"]lng() accepts two arguments, an English and a Hungarian version of the same text, e.g. lng("apple", "alma"), which, if the root has <html lang='hu'>, will return "alma".
data-upload='file-input-id?'
This UWeb attribute allows uploading/selecting a file, without having to use a (visible) <input type='file'/>.
If this attribute is present on an element with an action in a form, then firing the action will first prompt the user to select a file, and the action will be executed only if a file was successfully selected. That file will then be part of the form's input data, i.e.:
$_FILES (under the key "file" by default, but see below); get_form_data() will return the file as a JavaScript File object (under the key file by default, but see below), which can e.g. by passed to read_file(). file-input-id (optional): if this value is present, then the form must contain a (possibly invisible) <input type='file'/> element with this data-name. This may be useful to provide additional attributes on it to place some restrictions on the uploaded file (e.g. accept, data-check). If the attribute has no value, then an invisible <input type='file'/> is automatically appended to the form with data-name='file'.
Requirement: $has_upload if the website generates its own JavaScript
Note: this attribute has no effect if there is no action (e.g. data-action attribute) on the element.
function load_file (filename, func, error_func = null);
Load a file dynamically from the server.
filename: the URL of the file, relative to the current page.
func(content): function to be called when the file is loaded. It receives a single argument, the content of the file as a string.
error_func(status) (optional): function to be called when an HTTP error happens, e.g. when the file is missing. It receives a single argument, the HTTP status code of the error (e.g. 404 for Not Found).
Requirement: $has_load_file if the website generates its own JavaScript
function save_file (filename, content);
Create a new file with the given content, and ask the user to save it on the computer.
filename: the suggested filename for the user.
content: the content of the new file as a string.
Requirement: $has_save_file if the website generates its own JavaScript
function open_file (func);
Ask the user to open a file, and read its content.
func(content, file): function to be called when the file is selected and loaded. Its first argument (content) is the content of the file as a string, and the optional second argument (file) is the File object that represents the opened file.
Requirement: $has_select_file if the website generates its own JavaScript
function select_file (func);
Ask the user to select a file on the computer.
func(file): function to be called when the file is selected. Its argument (file) is a JavaScript File object representing the selected file, which can be used e.g. by read_file() below, or by FileReader in JavaScript.
See also read_file() and open_file().
Requirement: $has_select_file if the website generates its own JavaScript
function read_file (file, func);
Read the content of a file that was already selected by the user.
file: the File object that was selected by the user (e.g. obtained by select_file() above, or by an <input type='file'/>).
func(content): function to be called when the file is loaded. Its argument (content) is the content of the file as a string.
See also select_file() and open_file().
Requirement: $has_select_file if the website generates its own JavaScript
function load_js (filename, func = null);
Load another JavaScript file dynamically.
filename: the URL of the .js file, relative to the current page.
func() (optional): function to be called when the .js file is loaded.
Requirement: $has_load_js if the website generates its own JavaScript
The following functions return newly created HTML elements.
See also active.php and utils.php for generating elements with PHP.
function create_element (name, content = null, class = null, attrs = null); function create_element (name, content = null, attrs = null);
Create a new HTML element.
name: the name of the HTML element (e.g. "div").
content: the content of the element. It can be either a string (text content), a Node (e.g. a HTML element), an array thereof, or null.
class: optional CSS class(es) of the element. It is a string, where multiple classes are separated by spaces.
attrs: optional attributes of the element. It is an object with name-value pairs.
Example:
document.body.append(create_element("ul", [
create_element("li", "First"),
create_element("li", "Second", {"style": "font-weight:bold"}),
create_element("li", "Third"),
]));
Note: create_element() is similar to document.createElement(), but with more options.
function create_div (class = null, content = null, attrs = null);
Create a <div> element.
class: optional CSS class(es) of the element. It is a string, where multiple classes are separated by spaces.
content: the content of the element. It can be either a string (text content), a Node (e.g. a HTML element), an array thereof, or null.
attrs: optional attributes of the element. It is an object with name-value pairs.
function create_par (content = null, class = null, attrs = null); function create_par (content = null, attrs = null);
Create a paragraph (<p>) element.
content: the content of the element. It can be either a string (text content), a Node (e.g. a HTML element), an array thereof, or null.
class: optional CSS class(es) of the element. It is a string, where multiple classes are separated by spaces.
attrs: optional attributes of the element. It is an object with name-value pairs.
function create_span (content = null, class = null, attrs = null); function create_span (content = null, attrs = null);
Create a <span> element.
content: the content of the element. It can be either a string (text content), a Node (e.g. a HTML element), an array thereof, or null.
class: optional CSS class(es) of the element. It is a string, where multiple classes are separated by spaces.
attrs: optional attributes of the element. It is an object with name-value pairs.
function create_image (src, alt = null, attrs = null);
Create an image (<img>) element.
src: the URL (src attribute) of the image.
alt: alternative text (alt attribute) of the image.
attrs: optional attributes of the element. It is an object with name-value pairs.
Requirement: $has_create_image if the website generates its own JavaScript
function create_link (content, href, attrs = null);
Create an HTML link (<a>) element.
content: the content of the element. It can be either a string (text content), a Node (e.g. a HTML element), an array thereof, or null.
href: the URL (href attribute) of the link.
attrs: optional attributes of the element. It is an object with name-value pairs.
function create_button (label, action = null, attrs = null);
Create a pushable button (<button>).
label: the text label of the button. It can be either a string (text content), a Node (e.g. a HTML element), an array thereof, or null.
action: the action of the button. It can be either a function or an action string.
attrs: optional attributes of the element. It is an object with name-value pairs.
function create_link_button (content, action = null, attrs = null);
Create an HTML link that has an action like a button.
content: the content of the link. It can be either a string (text content), a Node (e.g. a HTML element), an array thereof, or null.
action: the action of the link. It can be either a function or an action string.
attrs: optional attributes of the element. It is an object with name-value pairs.
function create_button_image (image, action = null, attrs = null);
Create a button (<button>) with an image (<img>) inside it.
image: the URL (src attribute) of the image, or an already created <img> element (e.g. by the create_image() function), or a more general HTML content (see the content attributes above) that contains an <img>.
action: the action of the button. It can be either a function or an action string.
attrs: optional attributes of the element. It is an object with name-value pairs.
Requirements: $has_create_image (JS) and $has_button_image (CSS) if the website generates its own JavaScript and/or CSS
function create_submit_button (label, attrs = null);
Create a submit button for a form. A submit button, when pushed, will activate the action of the form.
label: the text label of the button. It can be either a string (text content), a Node (e.g. a HTML element), an array thereof, or null.
attrs: optional attributes of the element. It is an object with name-value pairs.
function create_input (type, id = null, value = null, attrs = null);
Create an HTML <input> element.
type: the type attribute of the <input>, e.g. "text".
id: the data-name attribute of the input field, to identify it within an UWeb form. (It can be null.)
value: optional initial value (the value attribute) of the input field.
attrs: optional attributes of the element. It is an object with name-value pairs.
function create_textbox (id = null, text = null, check = null, attrs = null); function create_textbox (id = null, text = null, attrs = null);
Create an HTML textbox (<input type='text'>).
id: the data-name attribute of the textbox, to identify it within an UWeb form. (It can be null.)
text: optional initial text of the textbox.
check: function to check the value of the textbox when submitting a form, see uweb_check. Note: this argument is only recognized if the JavaScript was generated with the $has_check option.
attrs: optional attributes of the element. It is an object with name-value pairs.
function create_textarea (id = null, text = null, attrs = null);
Create a multi-line text input field (<textarea>).
id: the data-name attribute of the text field, to identify it within an UWeb form. (It can be null.)
text: optional initial content of the text field.
attrs: optional attributes of the element. It is an object with name-value pairs.
function create_checkbox (id = null, checked = false, onchange = null, attrs = null);
Create a checkbox (<input type='checkbox'>), i.e. an input field with two states: checked or unchecked.
id: the data-name attribute of the checkbox, to identify it within an UWeb form. (It can be null.)
checked: the initial state of the checkbox (true or false).
onchange: function to be called when the state of the checkbox changes.
attrs: optional attributes of the element. It is an object with name-value pairs.
function create_radio_button (name, id = null, checked = false, attrs = null);
Generate a radio button (<input type='radio'>), which is similar to a checkbox, but only one radio button can be checked in a group at a time.
name: the name attribute of the radio button, which defines the group of radio buttons that are mutually exclusive, i.e. only one radio button can be selected among those that share the same name.
id: the data-id attribute of the radio button, to identify it within the group.
checked: the initial state of the radio button (true or false).
attrs: optional attributes of the element. It is an object with name-value pairs.
function create_input_line (text, input, attrs = null);
Create an aligned input line with a text and an input field. It helps to display multiple input fields in a formatted way. These lines must be put into a container that has class='input-lines', see the example below.
text: the label (e.g. text) for the input.
input: the corresponding input field (e.g. returned by create_textbox()).
attrs: optional attributes of the element. It is an object with name-value pairs.
For example:
var lines = create_div("input-lines", [
create_input_line("Username:", create_textbox("username")),
create_input_line("Password:", create_input("password", "password")),
]);
Requirement: $has_input_lines if the website generates its own CSS
function create_form (id, action = null, content = null, attrs = null);
Create an UWeb form.
id: the data-form attribute to identify the form.
action: the action of the form. It can be either a function or an action string.
content: the content of the form. It can be either a string (text content), a Node (e.g. a HTML element), an array thereof, or null.
attrs: optional attributes of the element. It is an object with name-value pairs.