Documentation
Uray Web Library (UWeb)
Uray Web Library (UWeb) is a collection of tools for web development.
It is particularly suitable for:
UWeb is written mainly in PHP (≥ 8.0), except the client-facing parts, which are written in standard web languages: JavaScript, CSS and HTML.
The main design goals of UWeb are:
UWeb is fully in UTF-8 encoding, including all source files and generated files, especially the generated HTML pages.
UWeb is pronounced /uwɛb/ (after Uray /urɒi/), not /juːwɛb/.
1.1. Server-side functionality
1.2. Client-side functionality
UWeb provides the following PHP files to be included by any PHP script (e.g. require_once __DIR__."/uweb/page.php";):
page.php: tools for generating an HTML page. It contains basic_page, the base class for all user-defined pages. This file is therefore needed by most uses of UWeb. utils.php: common utilities, including basic HTML generator functions such as alink() (for <a href='...'>), multi-language support and other basic tools. This PHP file is included by all other files in this list. html.php: more HTML generator functions (e.g. lists, table of contents, etc.). active.php: HTML generator functions for dynamic elements such as buttons, form input elements, popup boxes etc. params.php: tools for handling and validating GET and POST parameters (coming from URL query strings, HTML forms, AJAX queries etc.). time.php: time-related utilities, e.g. functions for converting time to user-friendly text. active.php) on the webpage, either by using UWeb's pregenerated .js file, or by generating one that has only the needed features (which is more efficient). .css files, or by generating one with customized parameters (e.g. colors) and with only the needed features. The following example shows how to generate a page using UWeb. It can be used either to generate an HTML file offline (and then e.g. upload it to a web server), or to run this PHP code directly on a web server, which will generate the HTML dynamically, on demand.
<?php
require_once __DIR__."/uweb/page.php";
class example_page extends basic_page {
function title () { return "Example page"; }
function css () { return "uweb.css"; }
function content () {
echo "<p> All human beings are born free. </p>\n";
}
}
generate(new example_page);
See Basic page for more information about generating pages.
A simple way to try this example is to copy it to a PHP file (e.g. example.php), and then run the command-line interface of PHP on it, redirecting the output to a new HTML file (e.g. php example.php >example.html), which can be opened in a web browser.
This example requires that UWeb's directory, uweb/, is next to the example PHP file, and that UWeb's basic CSS stylesheet is available as uweb.css, next to the generated HTML file. The latter can be done e.g. by copying (or symlinking) uweb/basic.css to uweb.css, see Generating CSS for more information.
The following example demonstrates some of UWeb's helper functions for generating HTML code. The example page is organized into sections and subsections, whose titles are listed in the "Table of contents" (TOC) in the beginning of the page, after a short introduction (in the same way as this documentation page).
<?php
require_once __DIR__."/uweb/page.php";
require_once __DIR__."/uweb/html.php";
class example_page extends basic_page {
function title () { return "Example page"; }
function css () { return "uweb.css"; }
function content () {
$this->intro();
print_toc_content($this, [
[3, "*toc"],
[3, "first"],
[6, "subfirst"],
[3, "second"],
]);
}
function intro () {
echo "<p> Introduction of the page, above the TOC. </p>\n";
}
const toc_title = "Table of contents";
const first_title = "First section";
function first () {
echo "<p> First line of the first section. </p>\n";
echo "<p> ",
"The second line contains ",bold("bold")," and ",
italic("italic")," text. ",
"</p>\n";
}
const subfirst_title = "Subsection";
function subfirst () {
echo "<p> This subsection contains a ",alink("link", "other.html"),". </p>\n";
}
const second_title = "Second section";
function second () {
echo "<p> Here is a bullet list: </p> ";
print_list([
"First element,",
bold("Second")." element,",
alink("Third is a link", "https://example.com"),
]);
}
}
generate(new example_page);
The function print_toc_content() generates the table of contents, and then the content of all sections and subsections listed in the TOC. It calls the methods first(), subfirst() and second() to generate the content of the sections, and uses the corresponding *_title constants for the section titles (both in the TOC and in the content).
This example also shows several other UWeb functions, such as bold() to make the text bold, alink() to create an HTML link, and print_list() to create a bullet list.
See utils.php and html.php for more information.
The following example demonstrates several capabilities of UWeb: how to create a multi-language page, how to process GET parameters (and handle if they are incorrect), and how to print the current date (in the correct language).
This PHP code needs to run on a web server, and it can be displayed in two languages, English and Hungarian, depending on the GET parameter lang, e.g. example.php?lang=hu. If lang is invalid, it will display an error page (in English). Normally, the page contains two paragraphs, and the second one displays the current date in the selected language (e.g. "Today is 6 Aug 2024.").
<?php
require_once __DIR__."/uweb/page.php";
require_once __DIR__."/uweb/params.php";
require_once __DIR__."/uweb/time.php";
class example_page extends basic_page {
// No title(), but see example_*::title below
function css () { return "uweb.css"; }
function __construct () {
try {
$lang = get_param_str_opt("lang") ?? "en";
if ($lang != "en" && $lang != "hu") {
$lang = "en";
get_param_error("lang");
}
} catch (basic_error $error) { // see Error handling
$this->fatal_error($error);
}
define("lang", $lang); // global constant 'lang'
}
function lng_obj () {
return lng_obj("example"); // example_en or example_hu, depending on 'lang'
}
function content () {
$lng = $this->lng_obj();
echo "<p> ",$lng::first_line," </p>";
$date = time_to_text(now, ["date", "long"]); // also uses 'lang'
echo "<p> ",$lng::current_date($date)," </p>";
}
}
class example_en { // see Language classes
const lang = "en";
const title = "Example page";
const first_line = "This is the first paragraph of the page.";
static function current_date ($date) { return "Today is $date."; }
}
class example_hu {
const lang = "hu";
const title = "Példa oldal";
const first_line = "Ez az oldal első bekezdése.";
static function current_date ($date) { return "Ma $date van."; }
}
execute(new example_page);
For more information, see:
A simple way to try this example is to create a local web server, which can be done by the command-line interface of PHP:
php -S localhost:8000
Run this in the same directory as the example PHP file, and then the page can be opened in a web browser, e.g.:
http://localhost:8000/example.php?lang=en
The following example demonstrates how to update parts of the page from the server using AJAX, without reloading the whole page. The button on this example page will send an AJAX query to the server, which will send a command back to the client to manipulate the page (insert a new paragraph above the button).
<?php
require_once __DIR__."/uweb/page.php";
require_once __DIR__."/uweb/active.php";
class example extends basic_page {
function title () { return "Example"; }
function css () { return "uweb.css"; }
function js () { return "uweb.js"; }
function content () {
echo "<div data-id='box'></div>";
echo "<p> ",button("Do AJAX", "q:do-ajax")," </p>";
}
function q_do_ajax () {
echo "<!append id='box'>";
echo "<p> This line was inserted by AJAX. </p>";
}
}
execute(new example);
See AJAX for more information and more examples.
This example requires uweb.css and uweb.js to be available, which can e.g. be copied (or symlinked) from uweb/all.css and uweb/all.js respectively (see Generating CSS and Generating JS for more information).