Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jcmoyer/html-dsl

A Lua DSL for building HTML elements
https://github.com/jcmoyer/html-dsl

Last synced: about 1 month ago
JSON representation

A Lua DSL for building HTML elements

Awesome Lists containing this project

README 

        
# What is this?



A [DSL](http://en.wikipedia.org/wiki/Domain-specific_language) for Lua 5.2+

that lets you write Lua code that resembles HTML. When you're done, you can

render the tree it builds to actual HTML!



# Example



```lua

local html = require('html')



local document = html {

  html.head {

    html.style [[

      .red {

        background: #800;

      }

    ]]

  },

  html.body {

    html.p 'hello world',

    html.ul {

      html.li 'foo',

      html.li 'bar',

      html.li {class='red', 'baz'}

    }

  }

}



-- write html to stdout

print(document:render())

```



# How does this abomination work?



Lua supports an alternate function call syntax for unary functions that take

either string literals or table constructors:



```lua

-- these are equivalent:

print 'hello world'

print('hello world')



-- these are also equivalent:

f {a=1, b=3, c=5}

f({a=1, b=3, c=5})

```



(Ab)using this this feature, we can bend Lua to do some crazy things.



# Reference

## `html` module

### `html.(data)`



Substitute `` for any valid [HTML5

element](http://www.w3.org/TR/html5/). When `data` is a table, its dictionary

elements are used as attributes and its sequence elements are used as HTML

elements and text. When `data` is a string, it is used as the only child of the

resulting element. `data` can also be omitted to obtain an element with no

children or attributes. The return value is an `element`.



#### Example



```lua

(html.p()):render()

-- 



(html.p 'hello world'):render()

-- 
hello world



(html.ul {class='list', html.li 'a', html.li 'b'}):render()

-- 
    

  • a
    • 

  • b
    • 



```



### `html.rendermixed(t)`



Accepts a sequence table of either strings or HTML elements, and passes the

strings through untouched while rendering the HTML elements to strings. The

result is a concatenated string with the strings and rendered elements

combined.



#### Example



```lua

html.rendermixed {'hello ', html.span 'world'}

-- hello world

```



### `html(t)`



The HTML module is callable. It is equivalent to calling `html.html` to create

an `` element.



#### Example



```lua

(html {html.body {html.p 'hello world'}}):render()

-- 
hello world


```



## `element`s

### `element:render()`



Converts the element to an HTML string.



#### Example



```lua

(html.p 'hello world'):render()

-- 
hello world


```



### `element:appendchild(data)`



Appends `data` to the element. `data` should be either an `element` or a

`string`.



#### Example



```lua

local para = html.p()

para:appendchild(html.span 'hello')

para:appendchild(' world')

para:render()

-- 
hello world


```



### `element:addattr(name, value)`



Adds an attribute to the element. Attempting to add an attribute when one

already exists with the same name will result in the first one being

overwritten. When `value` is a `string`, embedded quotation marks will be

escaped; otherwise, `value` remains untouched.



#### Example



```lua

local para = html.p 'hello world'

para:addattr('class', 'shiny')

para:render()

-- 
hello world


```



```lua

local para = html.p()

para:addattr('class', 'old')

para:addattr('class', 'new')

para:render()

-- 


```



```lua

local para = html.p()

para:addattr('data-desc', 'it is "cool"')

para:addattr('data-value', 123)

para:render()

-- 


```



### `element:opentag()`



Renders the opening tag for this element, which includes attributes.



#### Example



```lua

local para = html.p {class='shiny', 'hello world'}

para:opentag()

-- 


```



### `element:closetag()`



Renders the closing tag for this element, **regardless of whether or not it is

a void element**.



#### Example



```lua

local para = html.p {class='shiny', 'hello world'}

para:closetag()

-- 


```



### `html.element.type(t)`



Returns the string `'element'` if `t` is a `table` whose metatable indexes

`html.element`. Otherwise, returns `nil`.



# License

Licensed under the Apache License 2.0. Refer to the `LICENSE` file for more

information.