Generating JavaScript
Uray Web Library (UWeb)
To use the dynamic features of UWeb (such as actions, forms, AJAX – see also active.php), the corresponding JavaScript code must be available for the generated HTML file. This documentation page describes the possible ways to make it available.
The simplest way to do this is to use the pregenerated JavaScript file. A more efficient solution is to generate a custom JavaScript file using UWeb.
One JavaScript file is automatically generated by UWeb: all.js, which contains all JavaScript code for UWeb.
However, this file may be too big if the webpage needs only a part of it.
The intended way to use this file is to copy (or better, symlink) it next to the HTML file (renamed to e.g. uweb.js for clarity), and then set basic_page::js() to this file.
There is a more efficient and flexible solution than using the pregenerated all.js file. Webpages can generate their own versions of the JavaScript file using the tools provided by UWeb. In this way, they can select exactly what functions they need, so the clients are not overloaded with unused code (as they could be with all.js). Webpages can also add new JavaScript code to the same generated file (under the same license as UWeb, i.e. GPLv3), which may improve load speed, compared to multiple separate JS files.
A JavaScript file can be generated by the following steps:
js.php). js.php, which contains templates for all the possibly included JavaScript code. generate() at the end of the file to actually generate the JavaScript code. php js.php >my.js, either directly, or through a Makefile.) Here is a simple example:
<?php
// Configure the header comment
$project = "Some Website";
$author = "Uray M. János";
$date = "2024";
// Inclusion and configuration of components
$has_highlight = false;
$has_confirm = true;
$has_ajax = true;
$has_tooltip = true;
$has_upload = true;
$lng_langs = ["en", "hu"];
// Include UWeb's JavaScript templates
require_once __DIR__."/uweb/js.php";
// Add some custom JavaScript (optionally)
open();?><script>
function some_code () {
do_something();
}
</script><?php close();
// Actually generate the content
generate();
This section lists all the variables that can be used to control which parts are included in the generated JavaScript file, and possibly to customize these parts.
The generated JavaScript file will start with a comment similar to this:
// // JavaScript -- Some Website // Generated by the Uray Web Library (UWeb). // License: GPLv3 or later, see ... // Uray M. János © 2024 //
Its content can be customized by the following variables.
The title of the JavaScript file in the header comment.
Default value: "JavaScript"
The title of the project name (website name) in the header comment, e.g. "Some Website".
This variable is required.
The author of the project in the header comment.
Default value: "Uray M. János"
The copyright date of the project in the header comment, e.g. "2024" or "2020-2024".
Include JavaScript for UWeb forms (data-form).
Default value: true
Include JavaScript for keyboard actions (data-key, add_key()).
Default value: false
Include JavaScript for data-first-action.
Default value: true
Include JavaScript for highlighting the submit button (data-highlight, highlight_submit()).
Default value: $has_form
Include the JavaScript function get_value().
Default value: $has_form
Include JavaScript for auto-focus with the data-focus attribute.
Note: this attribute is also used by confirm_popup(), and by popup_*() in active.php.
Default value: true
Include JavaScript for automatic checks in forms (data-check, data-required, uweb_check).
Default value: false
Include JavaScript for data-details.
Default value: false
Include JavaScript for confirmation popups: data-confirm, uweb_confirm, confirm_popup().
Note: this option requires $has_form.
Default value: false
Include JavaScript for AJAX.
Default value: false
Include JavaScript for data-component.
Default value: $has_ajax
Include JavaScript for data-global.
Default value: false
Include JavaScript for data-param.
Default value: false
Make send_command() work even when loading the page (i.e. outside an AJAX query).
Default value: false
Include JavaScript for popup tooltips (data-tip). See also info_text() and qmark().
Note: tooltips also require $has_tooltip in CSS.
Default value: false
Include JavaScript for form marks, see show_mark(), <!mark> and input_error().
Default value: true
Include JavaScript for popup dialog boxes, see show_popup() and <!popup>.
Default value: true
Include JavaScript for dropdown boxes, see show_dropdown(), dropdown_menu() and data-action='dropdown'.
Note: dropdowns also require $has_dropdown in CSS.
Default value: false
Include JavaScript for closing marks, popups etc., see close_box(), close_popup() and data-action='close'.
Default value: true if $has_marks, $has_popup or $has_dropdown
Include JavaScript for uploading in forms: data-upload.
Note: this option requires $has_form.
Default value: false
Include the JavaScript function load_file().
Default value: false
Include the JavaScript function save_file() and the AJAX command <!download>.
Default value: false
Include the JavaScript functions select_file(), read_file() and open_file().
Default value: false
Include the JavaScript function load_js().
Default value: false
Include JavaScript for scrolling: scroll_to(), data-action='scroll'.
Default value: true
Include scrolling modes for scroll_to() (e.g. mode = "center"), and also data-action='scroll-center'.
Default value: false
Make scroll_to() scroll relatively to the innermost scrollable element, not to the full window. (This requires substantially more code for scroll_to()).
Default value: false
Include JavaScript for multi-tab content (class='tabbed-head' and class='tabbed-body'), see tabbed().
Note: this feature also requires $has_tabbed in CSS.
Default value: false
Include JavaScript for auto-growing text area: <textarea . data-autogrow='true'>
Default value: false
Include the JavaScript function get_window_size().
Default value: false
If this option is defined, the JavaScript function lng() will be included.
The value of this variable is an array of language codes, e.g. ["hu", "en"].
Default value: null (but ["hu", "en"] in all.js)
Include the create_*() JavaScript functions.
Default value: true
Include the JavaScript functions create_image() and create_button_image() (the latter also requires $has_create_button).
Default value: false
Include the JavaScript functions create_link() and create_link_button() (the latter also requires $has_create_button).
Default value: $has_create
Include the JavaScript function create_button() and other button-related create_*() functions (some of which may also require other options).
Default value: $has_create
Include those create_*() functions which are related to form input elements, such as create_input(), create_textbox(), create_checkbox() etc.
Default value: $has_create
Include the JavaScript function create_form().
Default value: true if both $has_create and $has_form are on
Custom JavaScript code can be inserted into the generated JS file like this:
open();?><script>
function some_code () {
do_something();
}
</script><?php close();
The JavaScript code must be surrounded by the following code:
open() and close() calls, which prepare the content in between to be added to the JS file. (It will be actually added when calling generate().) ?> and <?php to turn off PHP mode temporarily, so that the content is treated as text, not PHP code. (Note: the same effect could be achieved by using echo and putting the content into a string, but the former is recommended for better readability, see the next point.) <script> and end with </script> (which will be removed from the result). The main reason for these tags is that they let the text editor know that the inner content is JavaScript, so it can do e.g. syntax highlighting properly. But these tags also aid the JS-generator to do proper formatting and error detection. The custom JavaScript code may be split into any number of blocks by open()/close() pairs. Adjacent blocks will be separated by empty lines in the generated JS file. They may also be separated by comments for better readability, see title().
Note that since this custom JavaScript code will be added to the same file as UWeb's JavaScript, they will share the same license (GPLv3). If this is not desired, the custom JavaScript must be put into a separate file.
function open ();
Open a custom JavaScript block. It must be closed by a subsequent close().
function close ();
Close the custom JavaScript block opened by the last open().
function title ($title);
Insert a title comment to the generated JS file. It can be used to separate custom JavaScript blocks.
For example, title("Initialization") generates the following comment (separated by two empty lines from the previous block and one empty line from the next one):
// // Initialization // -------------- //
Note: the title is only printed if there is any JavaScript block (open()/close()) following title() before the next title. This can be useful if the subsequent code appears conditionally, e.g. inside PHP if statements.
function include_file ($js_file);
Insert the whole content of the given JavaScript file into the generated JS file.
function generate ();
Actually generate the JavaScript code.
This must be the last statement in the PHP file that generates the JS file. Without this, no output is produced.