lazui ## Introduction `lazui` is a JavaScript library that allows you to create interactive websites and single page apps with less work. It extends the attribute space of typical HTML to provide a rich set of functionality. It provides the JavaScript, so you don't have to. `lazui` draws its inspiration from the varied capabilities of [htmx](https://htmx.org/), [lighterHTML](https://github.com/WebReflection/lighterhtml), [Turbo](https://turbo.hotwired.dev/), [Stimulus](https://stimulus.hotwired.dev/), [Vue](https://vuejs.org/), and [Lit](https://lit.dev). It also provides a number of features not found in these libraries. The first major release of `lazui` is feature complete; however it needs more testing, optimization, improved documentation, and some functionality to round out the automatic form generation. In this case, don't be lazy ... join us and help out by [creating issues on GitHub](https://www.github.com/anywhichway/lazui/issues). ## Documentation Conventions It is possible to completely modify the `lazui` namespace. Throughout the documentation, references to attribute directives will take the form `lz:` and sample code will use the standards compliant form `data-lz:`, but they could just as well be `data-myapp:` or even `myapp:`. Attribute Directive : A custom attribute that is used to make relatively minor modifications to the behavior of an element. For instance, `lz:src` is an attribute directive that loads content into an element. Elements can have multiple attribute directives. In some cases, the documentation will use `TypeScript` notation to make APIs clear, however, `lazui` is not written in `TypeScript`. Most of the JSON in this document is in [JSON5](https://json5.org/) format. This makes JSON easier to write and less error prone. See [Relaxed JSON Parser](#relaxed-json-parser) for more information. Unless you configure your version of `lazui` to use JSON5, you will need to modify the JSON in the examples to be valid JSON. Any time you see a CDN URL for `lazui` you could use just `/lazui` if you are running the [basic lazui server](#basic-server). If there are known issues, the document will describe the issue and provide a link to the details on GitHub. If you view the documentation from a locally installed `lazui` [server](#basic-server), it has realtime integration with GitHub. Any issues that have been logged and assigned where an anchor id in this document is referenced in the issue description will be highlighted in the document along with a link back to the issue on GitHub. This is accomplished with the `lazui` component `git-issue-ref`. See [Single Page Components](#single-page-components) ## Installation ### CDN Unless you need your own attribute directives, you can use the CDN version of `lazui`. Place the following script tag in the head of your HTML: ```html ``` `lazui` has a core size of less that 8K minimized and Brotli compressed and can be used without a build process, but [enhanced with one](#creating-a-custom-bundle). Unless you are willing to [write your own JavaScript](#using-javascript), you should always provide the `autofocus` attribute. It tells `lazui` to process all the custom attribute directives and template substitutions in the document. ### Local You can also install `lazui` from `npm`: ```bash npm install @anywhichway/lazui ``` Then run: ```bash npm run serve ``` Access `lazui` and this documentation at `http://localhost:3000/`. See [Basic Server](#basic-server) for more information on the `lazui` server you can customize. [https://lazui.org](https://lazui.org) uses this basic server and is hosted on [Render](https://render.com/). ## How To Be Lazui You can put template literals directly in your HTML. Here is the first simple example: ```html ``` A bit overwhelming? Use this shorthand: ```html ``` ### Choose Your Development Paradigm Although `lazui` can be used as a powerful JavaScript rendering engine, it really shines at reducing the amount of JavaScript required to create an interactive website or single page app. This shininess is provided through a set of attribute directives and JavaScript controller files. If you are a fan of `Turbo` or `htmx`, you probably want to write less JavaScript. Since writing HTML is easier than JavaScript, the documentation uses the `lazui` (lazy) approach and covers the use of directives and controllers before the more [JavaScript focused](#using-javascript) [html](#html) and [render](#render) functions. ## Leveraging Attribute Directives Attribute directives take the form `:=`. The default `lazui` namespace is `lz`. Attribute directives are each stored in their own JavaScript file using the name of the directive as the file name. By convention, the files are in a directory called `directives` with subdirectories for each namespace. Hence, `lz:src` should be in `/directives/lz/src.js`. If this convention is followed, `lazui` will lazy load only those directives that are used. If you want to preload directives or use a different naming/filesystem convention, you can [load the directives directly using JavaScript](#loading-attribute-directives). Attribute directives can be provided configuration values with another directive called `lz:options`. The value of `lz:options` is a JSON object. The `lz:options` directive can be placed on any element and will apply to all directives. The configuration data for a specific directive is provided through a key of the same name as the directive. For instance, ```html
``` ### Relaxed JSON Parser The directive `lz:usejson` can be used to configure the JSON parser for more flexibility. This can dramatically simplify using embedded JSON by eliminating the need for quotes around keys and allowing the use of single quotes for strings. In short, you can be lazy about your JSON. You can do this: ```json { name: "John", age: 30 } ``` instead of this: ```json { "name": "John", "age": 30 } ``` The attribute takes as its value a URL pointing to the parser. [JSON5](https://json5.org/) is a good choice. ```html
``` or, if you have a local copy of JSON5: ```html
``` ### Using State Being able to insert a date and time or do inline math may with templates in HTML be useful, but you will probably want to include general data. The `data-lz:state` attribute can be used to define a state/model. The value of the attribute is the name of the state/model. The state/model is defined as a JSON object inside an element (typically a `