README.md
1WebAssembly
2===========
3[![beauty inside!](http://img.shields.io/badge/beauty-inside-80b0ff.svg)](http://en.wikipedia.org/wiki/Beauty)
4[![Build Status](https://travis-ci.org/herenowcoder/webassembly.svg?branch=master)](https://travis-ci.org/herenowcoder/webassembly)
5[![Coverage Status](https://img.shields.io/coveralls/herenowcoder/webassembly.svg)](https://coveralls.io/r/herenowcoder/webassembly)
6[![hex.pm version](https://img.shields.io/hexpm/v/webassembly.svg)](https://hex.pm/packages/webassembly)
7[![hex.pm downloads](https://img.shields.io/hexpm/dt/webassembly.svg)](https://hex.pm/packages/webassembly)
8
9DSL for creating html structure straight with Elixir blocks:
10
11```Elixir
12 use WebAssembly
13 builder do
14 html do
15 head do
16 meta http_equiv: "Content-Type", content: "text/html"
17 title "example"
18 end
19 body do
20 div class: "container", id: :content do
21 ul do
22 for index <- 1..3, do:
23 li "item #{index}"
24 end
25 random = :random.uniform(10)
26 if random == 5 do
27 text "Lucky! You got five"
28 end
29 end
30 span [style: "smiling"], "that was nice"
31 end
32 end
33 end
34```
35
36This results in a deeply nested list (aka [iolist])
37which you can flatten or (better!) send to the socket as it is
38([via Plug & Cowboy][via-plug] for example).
39
40Now what can be concluded from the example above:
41
42* you produce HTML elements by using macros inside `builder` block
43* [non-void] element can be used with "flat" content argument or with a `do`-block
44* element with a `do`-block means nesting
45* inside such a `do`-block you have access to **full Elixir syntax**
46* element attributes go first (but are optional), then the content
47* attributes are Elixir keywords
48* underscores in attribute keys are translated to dash signs
49* you can omit brackets around attributes when using `do`-block,
50 but not when using flat form
51* [void] HTML elements correspond to macros with attributes only,
52 like `meta` above
53* if you want to emit just text without surrounding html tags,
54 simply use `text` macro.
55
56For me it's beautiful. What about you?
57
58## Why?
59
60* to have views in pure Elixir, without HTML templates
61* to utilize Erlang's approach: you can feed sockets with iolists
62 instead of one big binary produced by template engine
63
64You can possibly mix different styles: code small snippets in
65WebAssembly and feed them to your partial templates, finally using
66your template engine to render the whole page.
67
68## Usage
69
70WebAssembly is published on [Hex], so just add `{:webassembly, "~> 0.6"}`
71to your deps and `:webassembly` to your apps in the `mix.exs`.
72
73Using it with [Plug] is a no-brainer - you just pass the doc to `send_resp/3`:
74
75```Elixir
76defmodule Plugged do
77 import Plug.Conn
78 use Plug.Router
79 use WebAssembly
80
81 plug :match
82 plug :dispatch
83
84 get "/" do
85 doc = builder do
86 html do
87 body do
88 text "hello from Plug!"
89 end
90 end
91 end
92 conn
93 |> put_resp_content_type("text/html")
94 |> send_resp(200, doc)
95 end
96end
97```
98
99API details are available at [hexdocs].
100
101## TDD
102
103WebAssembly aims to have 100% [test coverage][cov].
104
105## Type Safety
106
107As for releases `0.3.0` and above WebAssembly [dialyzes][dia] with no warnings.
108
109## Thanks
110
111Loosely inspired by [Markaby].
112
113## License
114
115The code is released under the BSD 2-Clause License.
116
117[markaby]: http://markaby.github.io/
118[plug]: http://hex.pm/packages/plug
119[cowboy]: http://hex.pm/packages/cowboy
120[iolist]: http://www.erlang.org/doc/reference_manual/typespec.html
121[hex]: http://hex.pm
122[void]: http://www.w3.org/TR/html5/syntax.html#void-elements
123[non-void]: http://www.w3.org/TR/html-markup/syntax.html#elements-html-syntax-list
124[hexdocs]: http://hexdocs.pm/webassembly
125[cov]: https://coveralls.io/r/herenowcoder/webassembly
126[dia]: https://github.com/fishcakez/dialyze
127[via-plug]: https://github.com/herenowcoder/webassembly#usage
128