Understanding the XMLUI Architecture
XMLUI has a straightforward architecture based on the reactive principle.
XMLUI takes your app's source files and precompiles them into an internal definition of the app. The framework's rendering engine uses this representation to render your app following this loop:
- The engine displays the app in its initial state according to the markup.
- The app waits for a system or user event. The engine runs the corresponding event handler when such an event is triggered.
- While the event handler runs, the engine detects state changes. If such a change occurs (and when the event handler completes), the engine initiates a UI refresh.
- This refresh process updates the part (and only that part) of the UI affected by the change.
- The loop starts again at Step 2 until the app is closed.
You do not need to know more about the engine's internals than it leverages this loop. You can consider XMLUI to be a rendering black box.
As the input, you can feed this black box with these items:
- Source code: markup with optional inline code + optional code-behind files.
- Resources: Images, logos, fonts, data files, etc., the app uses as external resources for the UI and its logic.
- Additional components (component libraries): third-party components used in your app
- Additional themes: New themes besides the ones shipped with the framework
- Configuration settings: Optional configuration settings (for example, the URLs of some backends utilized by the app for data retrieval or persistence, etc.)
XMLUI Apps
XMLUI does not require a build. A web server can immediately serve your app from the framework's core files and your app's source code.
An XMLUI app uses markup files (with the .xmlui extension) and optional accompanying code-behind files (with the .xmlui.xs extension).
By convention, your app's primary file is Main.xmlui within the app's root folder (beside index.html). If your app is simple, Main.xmlui is the only source file. If the app is more complex, it may leverage app-specific components in separate files (by convention, within the components folder).
Markup files use XML/XHTML syntax, while code-behind files contain scripts (a subset of JavaScript). XMLUI is responsible for combining them into a working app.
Hello, XMLUI!
Examine a lightweight app sample's structure and execution to get acquainted with the simplicity of an XMLUI app!
When you create a simple app, its only source code file is Main.xmlui with this markup:
<App>
Hello, XMLUI!
</App>The app (you can download the zipped version from here) contains these files:
| File/Folder | Description |
|---|---|
index.html | The default webpage to display |
Main.xmlui | The XMLUI app's entry point |
resources | The folder with static app resources (favicon.ico, xmlui-logo.svg, xmlui-logo-inverted.svg) |
xmlui | The folder with XMLUI core framework (xmlui-standalone.umd.js) |
start.bat | The batch file to start the http-server utility (assumes Node.js is installed) on Windows |
start.sh | The bash script file to start the http-server utility (assumes Node.js is installed) on Mac and Linux |
The index.html file is straightforward. It loads and starts the framework (xmlui-standalone.umd.js):
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<script src="xmlui/xmlui-standalone.umd.js"></script>
</head>
<body>
</body>
</html>The framework fetches the Main.xmlui file (it gets it from the root folder), tries to fetch its optional code-behind file (Main.xmlui.xs), compiles the app, and displays it.
Loading Application Files
An app running in the browser cannot check the app folder's structure on the web server. When fetching files, it asks the server for a particular file (using the corresponding URL in the request). The server delivers the requested file or retrieves a 404 (Not Found) status code.
After XMLUI loads the Main.xmlui file and compiles it, it has a list of unknown components (components not registered with XMLUI or any third-party component libraries). XMLUI considers them app-specific components and tries to load them from the components folder using a naming convention. For example, if the component is named CustomerForm, the engine fetches it from the components/CustomerForm.xmlui and components/CustomerForm.xmlui.xs files.
If the referenced component cannot be found, the app stops with an error message; otherwise, it registers (and caches) the loaded component.
XMLUI applies the same strategy recursively (as app-specific components may utilize other app-specific components) to obtain the entire app. The engine loads resources, themes, data files, etc., with a similar strategy.
This behavior may cause your browser's console to display "Failed to load resource 404 (Not Found)" messages. Most messages refer to .xmlui.xs files, as the engine does not know whether a code-behind file exists.
The Configuration File
XMLUI apps run without any particular configuration settings. However, you can describe these in the configuration file when you want to alter the default behavior or set app-specific configuration values.
At startup, XMLUI fetches the config.json file. If it finds the file, it sets up the app accordingly; otherwise, it uses the default configuration.
App Folder Structure
Even the more complex applications follow this simple app structure. This table summarizes the files and folders your app may have:
| File/Folder | Description |
|---|---|
index.html | The default webpage to display |
Main.xmlui | The XMLUI app's entry point |
Main.xmlui.xs | (Optional) Code-behind file for the app's entry point |
components | (Optional) The folder with the app's XMLUI components (empty) |
resources | (Optional) The folder with static app resources like images, logos, icons, etc. |
themes | (Optional) The folder theme files. |
xmlui | The folder with XMLUI core framework, optional features, emulated APIs, and third-party components |
config.json | (Optional) The app configuration file |
mockApi.js | (Optional) The service worker for emulated backend |
start.bat | (Optional) The batch file to start the http-server utility (assumes Node.js is installed) on Windows |
start.sh | (Optional) The bash script file to start the http-server utility (assumes Node.js is installed) on Mac and Linux |
All folders except xmlui are optional as your app may not contain resources, app-specific components, or themes.
Deploying XMLUI Apps
Deploying an XMLUI app is straightforward. You simply copy the app folder into your web server's public folder (the folder that serves static files), and your app is ready to use.
This approach works quickly in a company intranet's production environment but may not be adequate on the public web (because of startup time or download size).
The framework supports using XMLUI apps with optimization after a quick build process. This activity removes unused components (either components part of XMLUI or a third-party component library not leveraged in your app) and adds some code optimizations to improve startup.
We are still working on the build tools that optimize the application structure. When these tools are ready, we update this part of the documentation.
Developing Apps with HMR
XMLUI supports using a development environment (with a similar structure to the "no-build" mode, which has some extra files), which supports hot module reloading (HMR). Optionally, use this mode and its build process to create optimized files.
We are still working on the HMR environment and building tools that optimize the application structure. When these tools are ready, we update this part of the documentation.
Extensibility
XMLUI is extensible. Besides the components, resources, and themes shipped with the framework, you can extend an app with several artifacts:
- Custom (third-party) components, component libraries
- Custom themes
- Resources
- Icons and icon libraries
- JavaScript libraries
Extending XMLUI is as simple as one of these methods:
- Adding a file to your application (for example, a new theme to the
themesfolder) - Modifying the app's configuration (refer to a particular custom resource or changing a default resource, for example, the "email" icon with your own)
- Loading extra script files in the
index.htmlfile.
Our team is working on extensibility tools to support the community in contributing to XMLUI with custom extensions.