N2O is an unusual framework that solves problems in different web development domains while staying small and concise at the same time.

Started off as a Nitrogen concept of server-side framework it can also build client-side offline applications using same site sources. This becomes possible with the powerful Erlang JavaScript Parse Transform which extends Erlang language to JavaScript platform with two-side interoperability. You can as well use Elixir, LFE and Joxa languages to develop your back-end.

Author: Maxim Sokhatsky

Editors: Anton Logvinenko, Vladimir Kirillov, Viktor Sovietov, Dmitriy Sukhomlynov

---

Table of contents:

1 N2O: Web Framework 7

1.1 Wide Coverage . . . . . . . . . . . . . . . . . . . . . . . 7

1.2 Rich and Lightweight Applications . . . . . . . . . . . 9

1.3 JSON and BERT . . . . . . . . . . . . . . . . . . . . . . . 10

1.4 DSL and Templates . . . . . . . . . . . . . . . . . . . . . 10

2 Setup 13

2.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.2 Kickstart Bootstrap . . . . . . . . . . . . . . . . . . . . . 13

2.3 Manual Setup . . . . . . . . . . . . . . . . . . . . . . . . 14

3 Erlang Processes 15

3.1 Reduced Latency . . . . . . . . . . . . . . . . . . . . . . 15

3.2 Page Process . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.3 Transition Process . . . . . . . . . . . . . . . . . . . . . 16

3.4 Events Process . . . . . . . . . . . . . . . . . . . . . . . 16

3.5 Async Processes . . . . . . . . . . . . . . . . . . . . . . . 16

3.6 SPA Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4 Endpoints 18

4.1 HTML Pages over HTTP . . . . . . . . . . . . . . . . . . 18

4.2 JavaScript Events over WebSocket . . . . . . . . . . . . 19

4.3 HTTP API over REST . . . . . . . . . . . . . . . . . . . 20

5 Handlers 21

5.1 Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5.2 Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5.3 Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

6 Protocols 23

6.1 Heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . 24

6.2 Nitrogen Compatibility Layer . . . . . . . . . . . . . . . 24

6.3 Client/Server . . . . . . . . . . . . . . . . . . . . . . . . 25

6.4 Binary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6.5 Rails-like State Protocol . . . . . . . . . . . . . . . . . . 27

7 JavaScript Compiler 28

7.1 Compilation and Macros . . . . . . . . . . . . . . . . . . 28

7.2 Erlang Macro Functions . . . . . . . . . . . . . . . . . . 28

7.3 JavaScript File Compilation . . . . . . . . . . . . . . . . 29

7.4 Mapping Erlang/OTP to JavaScript/OTP . . . . . . . . 30

8 API 31

8.1 Update DOM wf:update . . . . . . . . . . . . . . . . . . 31

8.2 Wire JavaScript wf:wire . . . . . . . . . . . . . . . . . . 32

8.3 Async Processes wf:async and wf:flush . . . . . . . . . 33

8.4 Message Bus wf:reg and wf:send . . . . . . . . . . . . . 34

8.5 Parse URL and Context parameters wf:q and wf:qs . . 34

8.6 Render wf:render . . . . . . . . . . . . . . . . . . . . . . 34

8.7 Redirects wf:redirect . . . . . . . . . . . . . . . . . . . . 35

8.8 Session Information wf:session . . . . . . . . . . . . . . 35

8.9 Bridge information wf:header and wf:cookie . . . . . . 35

9 Elements 36

9.1 Static Elements: HTML . . . . . . . . . . . . . . . . . . 36

9.2 Active Elements: HTML and JavaScript . . . . . . . . . 37

9.3 Base Element . . . . . . . . . . . . . . . . . . . . . . . . 38

9.4 DTL Template #dtl . . . . . . . . . . . . . . . . . . . . . 39

9.5 Button #button . . . . . . . . . . . . . . . . . . . . . . . 40

9.6 Link #dropdown . . . . . . . . . . . . . . . . . . . . . . 40

9.7 Link #link . . . . . . . . . . . . . . . . . . . . . . . . . . 42

9.8 Text Editor #textarea . . . . . . . . . . . . . . . . . . . . 42

10 Actions 43

10.1 JavaScript DSL #jq . . . . . . . . . . . . . . . . . . . . . 43

10.2 Page Events #event . . . . . . . . . . . . . . . . . . . . . 44

10.3 API Events #api . . . . . . . . . . . . . . . . . . . . . . . 44

10.4 Message Box #alert . . . . . . . . . . . . . . . . . . . . . 45

10.5 Confirmation Box #confirm . . . . . . . . . . . . . . . . 45

11 UTF-8 46

11.1 Erlang . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

11.2 JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . 46

12 MAD: Build and Packaging Tool 47

12.1 History . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

12.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 48

12.3 Single-File Bundling . . . . . . . . . . . . . . . . . . . . 48

12.4 Templates . . . . . . . . . . . . . . . . . . . . . . . . . . 49

12.5 Deploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

12.6 OTP Compliant . . . . . . . . . . . . . . . . . . . . . . . 50

12.7 Apps Ordering . . . . . . . . . . . . . . . . . . . . . . . 50

13 KVS: Abstract Erlang Database 51

13.1 Polymorphic Records . . . . . . . . . . . . . . . . . . . 51

13.2 Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

13.3 Containers . . . . . . . . . . . . . . . . . . . . . . . . . . 52

13.4 Extending Schema . . . . . . . . . . . . . . . . . . . . . 53

13.5 KVS API . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

13.6 Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

13.7 Schema Change . . . . . . . . . . . . . . . . . . . . . . . 54

13.8 Meta Info . . . . . . . . . . . . . . . . . . . . . . . . . . 54

13.9 Chain Ops . . . . . . . . . . . . . . . . . . . . . . . . . . 55

13.10 Raw Ops . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

13.11 Read Ops . . . . . . . . . . . . . . . . . . . . . . . . . . 55

14 Afterword 56