add mmm.dom docs

2 files changed, 181 insertions, 1 deletions

diff --git a/root/meta/init.moon b/root/meta/init.moon
index cd2baed..626cd9e 100644
--- a/root/meta/init.moon
+++ b/root/meta/init.moon
@@ -10,7 +10,7 @@ Fileder {
       h3 @gett 'title: text/plain', style: { 'margin-bottom': '-.5em' },
       ul for child in *@children
         name = child\gett 'name: alpha'
-        desc = child\gett 'description: text/plain'
+        desc = child\gett 'description: mmm/dom'
         li {
           a name, {
             href: child.path,
@@ -22,6 +22,7 @@ Fileder {
         }
     }
 
+  require '.mmm_dom'
   require '.todo'
   require '.test_component'
 }
diff --git a/root/meta/mmm_dom.moon b/root/meta/mmm_dom.moon
new file mode 100644
index 0000000..13ce257
--- /dev/null
+++ b/root/meta/mmm_dom.moon
@@ -0,0 +1,179 @@
+import define_fileders from require 'mmm.mmmfs'
+Fileder = define_fileders ...
+
+import article, h1, h2, p, a, span, div, pre, code from require 'mmm.dom'
+
+mmmdom = -> code 'mmm.dom'
+
+source = do
+  build = (lang) -> if MODE == 'SERVER'
+    (str) -> code (str\match '^ *(..-) *$'), class: "hljs lang-#{lang}"
+  else
+    (str) ->
+      result = window.hljs\highlight lang, (str\match '^ *(..-) *$'), true
+      with code class: 'hljs'
+        .innerHTML = result.value
+
+  mklua, mkmoon = (build 'lua'), build 'moonscript'
+
+  (moon, lua, demo=true) ->
+    the_code = pre (mkmoon moon), (mklua lua), class: 'dual-code'
+
+    return the_code unless demo
+
+    example = assert load lua
+    div the_code, div example!, class: 'example'
+
+Fileder {
+  'name: alpha': 'mmm.dom'
+  'description: mmm/dom': span mmmdom!, ' documentation'
+  'mmm/dom': article {
+    h1 mmmdom!
+    p mmmdom!, " is a DSL for creating HTML documents in Lua and Moonscript."
+
+    p do
+      fengari = a "fengari.io", href: '//fengari.io'
+
+      "The same API is supported both on the server / in native Lua, where it outputs an HTML string,
+      as well as on the client (using ", fengari, "), where it dynamically creates DOM Nodes that can
+      be further manipulated using Lua or JavaScript. The API behaves exactly the same way in both modes
+      so that you can write code once that works both for rendering offline/serverside and in the browser.
+      This enables you to build websites and applications with dynamic content as well as perfect static
+      views for clients with JS disabled and SEO."
+
+    h2 "API"
+    p "Begin by requiring ", mmmdom!, ". The module returns a 'magic table' that allows you to instantiate
+      HTML elements of any type. Compare the usage in Lua and Moonscript:"
+
+    source [[
+import div, h1, p, a from require 'mmm.dom'
+
+-- or just use dom.div etc. if you want to keep your
+-- namespace clean, they are cached automatically
+
+dom = require 'mmm.dom'
+    ]], [[
+local dom = require 'mmm.dom'
+
+local div, h1, p, a = dom.div, dom.h1, dom.p, dom.a
+
+-- or just use dom.div etc. if you want to keep your
+-- namespace clean, they are cached automatically
+    ]], false
+
+    p "Each of these constructor functions can now be used to instantiate elements of the specified type.
+      In the simplest case, you may want to a simple element with no attributes or children, for example a ",
+      (code '<br />'), " line break tag:"
+
+    source [[
+import br from require 'mmm.dom'
+
+br!
+    ]], [[
+local dom = require 'mmm.dom'
+
+return dom.br()
+    ]], false
+
+    p "You can pass any number of children as arguments when you create an element. They will be joined without spaces:"
+
+    source [[
+import h3, i, code from require 'mmm.dom'
+
+h3 "this is a ",
+  (i 'headline'),
+  " with some ",
+  code 'rich text'
+  ]], [[
+local d = require 'mmm.dom'
+
+return d.h3(
+  "this is a ",
+  d.i 'headline',
+  " with some ",
+  d.code 'rich text'
+)
+    ]]
+
+    p "As you can see, ", mmmdom!, " can be used quite comfortably both in Lua and Moonscript."
+    p "As you build bigger structures, you may find that constructing HTML trees via argument lists can get a bit
+      confusing (especially with Moonscript and indentation rules).
+      Because of this ", mmmdom!, " also supports passing a table with children in the integer keys 1, 2, ...
+      This is particularily useful when you make use of Lua's shorthand for calling functions with single arguments:"
+
+    source [[
+import article, h3, span, div, i, p from require 'mmm.dom'
+
+article {
+  h3 "This is a headline with ", i "cursive text"
+  p {
+    "The content goes ",
+    i "here."
+  }
+  p "more paragraphs can be added as well, of course."
+}
+      ]], [[
+local dom = require 'mmm.dom'
+local article, h3, span, div, i, p = dom.article, dom.h3, dom.span, dom.div, dom.i, dom.p
+
+return article{
+  h3{ "This is a headline with ", i "cursive text" },
+  p{
+    "The content goes ",
+    i"here."
+  },
+  p"more paragraphs can be added as well, of course."
+}
+    ]]
+
+    p "Of course ", mmmdom!, " also allows you to set attributes on elements."
+    p "When you are using a constructor using the single-table approach,
+      all string keys set on the table are considered attributes and set on the element:"
+
+    source [[
+import div from require 'mmm.dom'
+
+div {
+  id: 'my_div',
+  class: 'shadow',
+  "This is div matches the CSS selector `div#my_div.shadow`"
+}
+      ]], [[
+local div = require('mmm.dom').div
+
+return div{
+  id = 'my_div',
+  class = 'shadow',
+  "This is div matches the CSS selector `div#my_div.shadow`"
+}
+    ]]
+
+    p "When you are passing multiple arguments, you can attach the attributes in a table
+      as the last argument. This works very well with Moonscript syntax."
+
+    p "In general attribute values need to be strings or numbers to be rendered correctly both
+      on client on server. The only exception is the ", (code 'style'), " attribute, which,
+      if it is passed as a table, will be expanded into a valid CSS string:"
+
+    source [[
+import div from require 'mmm.dom'
+
+div "red div with white text", style: {
+  background: 'red',
+  color: '#ffffff',
+}
+      ]], [[
+local div = require('mmm.dom').div
+
+return div(
+  "red div with white text",
+  {
+    style = {
+      background = 'red',
+      color = '#ffffff',
+    }
+  }
+)
+    ]]
+  }
+}