add instructsion for elmish.init function to elmish.md for #44

Author: nelsonic

README.md

@@ -46,12 +46,14 @@ of a completely new (_functional_) programming language!
 _Organizing_ `code` in a Web (_or Mobile_) Application
 is _really easy_ to ***over-complicate***, <br />
 _especially_ when you are just starting out and there
-are dozens of competing ideas <br />
-all claiming to be the "_right way_"...
+are _dozens_ of competing ideas
+all _claiming_ to be the "***right way***"...
 
 When we encounter this type of "_what is the **right way**_?"
-question <br />
-we always follow [***Occam's Razor***](https://en.wikipedia.org/wiki/Occam%27s_razor) and _ask_:
+question, <br />
+we always follow
+[***Occam's Razor***](https://en.wikipedia.org/wiki/Occam%27s_razor)
+and _ask_:
 what is the ***simplest way***? <br />
 In the case of web application organization,
 the ***answer*** is:
@@ -73,6 +75,14 @@ very easy!
   such as
 [Model-view-Presenter](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93presenter) or "Model-View-ViewModel" (MVVM) which is "overkill" for most apps_.)
 
+> _**Note**: **don't panic** if any of the terms above are strange
+or even confusing to you right now.
+> Our **quest** is to put all the concepts into **context**.
+> And if you get "**stuck**" at any point, we are here to help!
+> Simply **open a question** on GitHub:_
+[github.com/dwyl/**learn-elm-architecture**-in-javascript/**issues**](https://github.com/dwyl/learn-elm-architecture-in-javascript/issues)
+
+
 ## _Who? (Should I Read/Learn This...?)_
 
 [![everybodys-gotta-learn-sometime](https://cloud.githubusercontent.com/assets/194400/25806590/a1619644-33fb-11e7-8b84-1a21be188fb7.png)](https://www.youtube.com/results?q=The+Korgis+-+Everybody%27s+Gotta+Learn+Sometime)
@@ -83,7 +93,7 @@ their code/app in a _sane_, predictable and testable way.
 
 ### _Prerequisites_?
 
-![all-you-need-is-less](https://cloud.githubusercontent.com/assets/194400/25772135/a4230490-325b-11e7-9f12-da19fa4eb5e9.png)
+[![all-you-need-is-less](https://cloud.githubusercontent.com/assets/194400/25772135/a4230490-325b-11e7-9f12-da19fa4eb5e9.png)](https://www.ted.com/talks/graham_hill_less_stuff_more_happiness)
 
 + **_Basic_ JavaScript Knowledge**.
 see: [github.com/dwyl/**Javascript**-the-**Good-Parts**-notes](https://github.com/iteles/Javascript-the-Good-Parts-notes)
@@ -99,16 +109,18 @@ If you have **_any_ questions**, ***please ask***: <br />
 
 ## _What?_
 
-![image](https://cloud.githubusercontent.com/assets/194400/25772120/3fa2492c-325b-11e7-9aee-90b059360c14.png)
+[![image](https://cloud.githubusercontent.com/assets/194400/25772120/3fa2492c-325b-11e7-9aee-90b059360c14.png)](https://youtu.be/yYCmhHFhopA?t=4s)
 
 ### A _Complete Beginner's_ Guide to "MUV"
 
 Start with a few definitions:
 
-+ **Model** - or "data model" is the place where all data stored;
++ **Model** - or "data model" is the place where all data is stored;
 often referred to as the application's `state`.
 + **Update** - how the app handles `actions` performed
-by people and `update` the `state`.
+by people and `update` the `state`,
+usually organised as a `switch` with various `case` statements corresponding
+to the different "_actions_" the user can take in your App.
 + **View** - what people using the app can _see_;
 a way to `view` the Model (counter) as `HTML`
 rendered in a web browser.
@@ -135,7 +147,14 @@ Creative Commons License
 
 </div>
 
-If this diagram is not clear (_yet_), again, don't panic,
+In the "View Theatre" diagram, the:
++ **`model`** is the ensamble of characters (_or "**puppets**"_)
++ **`update`** is the function that transforms (_"changes"_) the `model`
+(_the "**puppeteer**"_).
++ **`view`** what the audience sees through "view port" (_stage_).
+
+
+> If this diagram is not clear (_yet_), again, don't panic,
 it will all be clarified when you start seeing it in _action_ (_below_)!
 
 

elmish.md

@@ -1,6 +1,6 @@
 # `Elm`(_ish_)
 
-### How to Build a Front-end Micro-Framework _From Scratch_
+### (How to Build a Front-end Micro-Framework _From Scratch_)
 
 ![elmlogo-ish](https://user-images.githubusercontent.com/194400/43213139-b70a4c68-902d-11e8-8162-3c7cb56b6360.png)
 <!-- the colors are deliberately "a bit off" to emphasize that
@@ -78,26 +78,18 @@ please see:
 and
 [front-end-with-tape.md](https://github.com/dwyl/learn-tape/blob/master/front-end-with-tape.md)
 
-### Start by Creating the Files
-
-It's "OK" to ask: "_Where do I **start** (my **TDD** quest)?_" <br />
-The answer is: create **two** new files:
-`examples/todo-list/elmish.js` and `test/elmish.test.js`
-
-We will create a couple of tests and their corresponding functions _next_
-but first, let's take a moment to think about what we _can_ generalise
-from the code we wrote for our "counter" example at the start of this tutorial.
 
 ### What _Can_ We _Generalise_ ?
 
-Our **first step** in creating `Elm`(_ish_) is to consider
-what _can_ be _generalised_ into
+Our **first step** in creating `Elm`(_ish_)
+is to _re-visit_ the functions we wrote for the "counter app"
+and consider what _can_ be _generalised_ into
 an application-independent re-useable framework.
 
 > Our **rule-of-thumb** is: anything that creates (_or destroys_)
 a DOM element or looks like "plumbing"
-(_e.g: "routing" or "managing state"_) is _generic_
-and should thus be abstracted into the `Elm`(_ish_) framework.
+(_that which is common to **all apps**, e.g: "routing" or "managing state"_)
+is _generic_ and should thus be abstracted into the `Elm`(_ish_) framework.
 
 
 Recall that there are **3 parts** to the Elm Architecture:
@@ -134,21 +126,106 @@ these _can_ (_will_) be generalised (_below_).
 
 
 Let's start with a couple of "_familiar_" _generic_ functions
-(_which we saw and used in the "counter" example_):
-`empty` and `mount`. <br />
+(_which we used in the "counter-reset" example_):
+`init`, `empty` and `mount`. <br />
 
 <br />
 
-#### `empty` the DOM
+### Start by Creating the Files
+
+It's _essential_ to ask: "_Where do I **start** (my **TDD** quest)?_" <br />
+The answer is: create **two** new files:
+`examples/todo-list/elmish.js` and `test/elmish.test.js`
+
+
+### Test Setup
+
+In order to run our test, we need some "setup" code
+that "requires" the libraries so we can _execute_ the functions.
+
+In the `test/elmish.test.js` file, type the following code:
+```js
+const test = require('tape');       // https://github.com/dwyl/learn-tape
+const fs = require('fs');           // to read html files (see below)
+const path = require('path');       // so we can open files cross-platform
+const html = fs.readFileSync(path.resolve(__dirname,
+  '../examples/todo-list/index.html')); // sample HTML file to initialise JSDOM.
+require('jsdom-global')(html);      // https://github.com/rstacruz/jsdom-global
+const elmish = require('../examples/todo-list/elmish.js'); // functions to test
+elmish.init(document);              // pass JSDOM into elmish for DOM functions
+const id = 'test-app';              // all tests use 'test-app' as root element
+```
+
+> Most of this code should be _familiar_ to you
+if you have followed previous tutorials.
+> If anything is _unclear_ please revisit
+https://github.com/dwyl/learn-tape
+and
+
+If you attempt to run this code using the command:
+```sh
+node test/elmish.test.js
+```
+
+you will see something like the following:
+![no-init-function](https://user-images.githubusercontent.com/194400/43359605-b8cc9418-929c-11e8-92d6-97feb8c67596.png)
+
+This is because we do not have anything in the `elmish.js`, yet.
+Let's address that now!
+
+
+### Add `init` function
+
+Open the `examples/todo-list/elmish.js` file and add the following code:
+
+```js
+
+
+/**
+ * `init` initialises the document (Global) variable for DOM operations.
+ * @param  {Object} doc window.document in browser and JSDOM.document in tests.
+ * @return {Object} document returns whatever is passed in.
+ */
+function init(doc){
+  document = doc; // this is used for instantiating JSDOM for testing.
+  return document;
+}
+```
+
+This code is simply to allow us to "initialise" `Elm`(_ish_)
+with a "fake" DOM (`JSDOM`) so that we can _test_ it.
+
+
+### Add `module.exports` to "export" the `init` function
+
+Adding the function to the `elmish.js` file is a good _start_,
+but we need to ***`export`*** it to be able to _invoke_ it in our test.
+Let's add the following code at the end of `examples/todo-list/elmish.js`:
+
+```js
+/* module.exports is needed to run the functions using Node.js for testing! */
+/* istanbul ignore next */
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    init: init
+  }
+} else { init(document);
+```
+
+
+
+
+### `empty` the DOM
 
 Start by _describing_ what the `empty` function _does_. <br />
 This is both to clarify our _own_ understanding
 as the people _writing_ the code <br />
 and to _clearly communicate_ with the **`humans` _reading_** the code.
 
-##### Function Description
+#### `empty` Function _Description_
 
-The `empty` function clears the DOM elements out of a specific "root" element.
+The `empty` function deletes all DOM elements
+from within a specific "root" element.
 We use it to erase the DOM before re-rendering our app.
 
 Following "**_Document(ation)_ Driven Development**",
@@ -158,12 +235,13 @@ with _just_ the function description:
 
 ```js
 /**
- * `empty` clears the DOM elements out of a specific "root" element.
+ * `empty` deletes all the DOM elements from within a specific "root" element.
  * it is used to erase the DOM before re-rendering the app.
  */
 ```
 Writing out the function documentation _first_
-helps us _think_ about the functionality.
+allows (_our subconscious_) time to _think_ about the functionality
+and how to _test_ for the "_acceptance criteria_".
 Even if you know _exactly_ what code needs to be written,
 _resist_ the temptation to write the code until it is documented.
 Even if you are writing code alone,
@@ -172,12 +250,15 @@ who does _not_ (_already_) "know the solution"
 and you are _explaining_ it to them.
 
 
+#### `empty` Function _Test_
 
-Given that we _know_ we are going to use the `empty`
-
-function we used previously in our `counter`,
+We previously used the `empty` function in our `counter`,
 `counter-reset` and `multiple-counters` examples (_in the "basic" TEA tutorial_)
-we can write a _test_ for the `empty` function quite easily.
+so we have a "head start" on writing the test.
+
+> _The **reason**(s) we write the **test first**
+even when we (already) know the "solution" is:_ <br />
+>
 
 
 In the `test/elmish.test.js` file, type the following code:
@@ -187,7 +268,7 @@ const fs = require('fs');           // to read html files (see below)
 const path = require('path');       // so we can open files cross-platform
 const elmish = require('../examples/todo-list/elmish.js'); // functions to test
 const html = fs.readFileSync(path.resolve(__dirname,
-  '../examples/todo-list/index.html')); // sample HTML file for JSDOM to load
+  '../examples/todo-list/index.html')); // sample HTML file to initialise JSDOM.
 require('jsdom-global')(html);      // https://github.com/rstacruz/jsdom-global
 elmish.init(document);              // pass JSDOM into elmish for DOM functions
 const id = 'test-app';              // all tests use 'test-app' as root element
@@ -223,17 +304,19 @@ issue***!](https://github.com/dwyl/learn-elm-architecture-in-javascript/issues)
 _It's **essential** that you **understand** each **character**
 in the code **before** continuing to **avoid** "**confusion**" later._
 
+#### `empty` Function _Implementation_
+
 Now that we have the **test** for our `empty` function written,
 we can add the `empty` function to `examples/todo-list/elmish.js`:
 ```js
 /**
- * `empty` the contents of a given DOM element "node" (before re-rendering).
+ * `empty` deletes all the DOM elements from within a specific "root" element.
+ * it is used to erase the DOM before re-rendering the app.
  * This is the *fastest* way according to: stackoverflow.com/a/3955238/1148249
- * @param  {Object} node the exact DOM node you want to empty
+ * @param  {Object} node the exact ("parent") DOM node you want to empty
  * @example
  * // returns true (once the 'app' node is emptied)
- * const node = document.getElementById('app');
- * empty(node);
+ * empty(document.getElementById('app'));
  */
 function empty(node) {
   while (node.lastChild) {
@@ -242,12 +325,18 @@ function empty(node) {
 }
 ```
 
-If the **comment syntax**
-above the function definition
-is _unfamiliar_,
+If the **comment syntax** above the function definition is _unfamiliar_,
 please see:
 [https://github.com/dwyl/**learn-jsdoc**](https://github.com/dwyl/learn-jsdoc)
 
+When you run the test in your terminal with the command
+`node test/elmish.test.js`
+you should see something _similar_ to this:
+
+
+
+
+
 
 ### `mount` the App