neo.mjs 6.18.3 → 6.19.0

package/resources/data/deck/learnneo/pages/Earthquakes-Lab-06-use-a-view-model.md

@@ -0,0 +1,301 @@
+<details>
+<summary>Look at network traffic</summary>
+
+Before making any changes, open devtools in the Network tab and refresh _earthquakes_. You'll see two
+calls to the web service.
+
+<img style="width:80%" src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/EarthquakesTwoTablesTwoCalls.png"></img>
+
+</details>
+
+<details>
+<summary>Copy the store config to the view model</summary>
+
+View models have two key configs: `data` and `stores`.
+
+- `data` holds name/value pairs where the value can be a simple value, or object references
+- `stores` holds configs of stores
+
+Add a `stores` property to the view model config that holds a copy of the store.
+
+<pre data-javascript>
+import Base             from '../../../node_modules/neo.mjs/src/container/Base.mjs';
+import Controller       from './MainViewController.mjs';
+import EarthquakesTable from './earthquakes/Table.mjs';
+import Store            from '../../../node_modules/neo.mjs/src/data/Store.mjs';
+import ViewModel        from './MainViewModel.mjs';
+
+class MainView extends Base {
+    static config = {
+        className: 'Earthquakes.view.MainView',
+        ntype: 'earthquakes-main',
+
+        controller: {module: Controller},
+        model: {
+            module: ViewModel,
+            stores: {
+                earthquakes: {
+                    module: Store,
+                    model: {
+                        fields: [{
+                            name: "humanReadableLocation"
+                        }, {
+                            name: "size"
+                        }, {
+                            name: "timestamp",
+                            type: "Date"
+                        }]
+                    },
+                    url: "https://apis.is/earthquake/is",
+                    responseRoot: "results",
+                    autoLoad: true
+                },    
+            }
+        },
+
+        layout: {
+            ntype: 'vbox', align: 'stretch'
+        },
+        items: [{
+            module: EarthquakesTable,
+            store: {
+                module: Store,
+                model: {
+                    fields: [{
+                        name: "humanReadableLocation"
+                    }, {
+                        name: "size"
+                    }, {
+                        name: "timestamp",
+                        type: "Date"
+                    }]
+                },
+                url: "https://apis.is/earthquake/is",
+                responseRoot: "results",
+                autoLoad: true
+            },
+            style: {width: '100%'}
+        },{
+            module: EarthquakesTable,
+            store: {
+                module: Store,
+                model: {
+                    fields: [{
+                        name: "humanReadableLocation"
+                    }, {
+                        name: "size"
+                    }, {
+                        name: "timestamp",
+                        type: "Date"
+                    }]
+                },
+                url: "https://apis.is/earthquake/is",
+                responseRoot: "results",
+                autoLoad: true
+            },
+            style: {width: '100%'}
+        }],
+    }
+}
+
+Neo.setupClass(MainView);
+
+export default MainView;
+
+</pre>
+
+In the `stores` config we named the store _earthquakes_. We could have named it anything, like _foo_
+or _myStore_. We're calling it _earthquakes_ simply because that seems like a good descriptive name
+of the data the store holds.
+
+At this point we have _three_ identical store configs! Save and refresh, and look at network traffic &mdash; you
+should see three calls.
+
+Having an instance in the view model means we can share it. It can be shared anywhere in the containment
+hierarchy. The app doesn't have much of a hierarchy: it's just the main view and two child components (the two
+tables). But now that the store is in the parent's view model we can share it.
+
+</details>
+
+<details>
+<summary>Use the shared store</summary>
+
+The way to bind an instance to a view model property is with the `bind` config. For example
+
+    bind: {
+        store: 'stores.earthquakes' 
+    }
+
+binds a `store` property to a store called `foo`. The code is saying _in the future, when the value
+of "stores.earthquakes" changes, assign it to this object's "store" property_. In this case, `stores.earthquakes`
+starts out undefined, then at runtime within a few milliseconds as the view model is processed, the configured
+store is created and a reference is assigned to `stores.earthquakes`. That wakes the binding up, and the
+value is assigned to the table's `store` property.
+
+Replace each table's `store` config with the binding.
+
+<pre data-javascript>
+
+import Base             from '../../../node_modules/neo.mjs/src/container/Base.mjs';
+import Controller       from './MainViewController.mjs';
+import EarthquakesTable from './earthquakes/Table.mjs';
+import Store            from '../../../node_modules/neo.mjs/src/data/Store.mjs';
+import ViewModel        from './MainViewModel.mjs';
+
+class MainView extends Base {
+    static config = {
+        className: 'Earthquakes.view.MainView',
+        ntype: 'earthquakes-main',
+        controller: {module: Controller},
+        model: {
+            module: ViewModel,
+            stores: {
+                earthquakes: {
+                    module: Store,
+                    model: {
+                        fields: [{
+                            name: "humanReadableLocation"
+                        }, {
+                            name: "size"
+                        }, {
+                            name: "timestamp",
+                            type: "Date"
+                        }]
+                    },
+                    url: "https://apis.is/earthquake/is",
+                    responseRoot: "results",
+                    autoLoad: true
+                },    
+            }
+        },
+
+        layout: { ntype: 'vbox', align: 'stretch' },
+        items: [{
+            module: EarthquakesTable,
+            bind: {
+                store: 'stores.earthquakes'
+            },
+            style: {width: '100%'}
+        },{
+            module: EarthquakesTable,
+            bind: {
+                store: 'stores.earthquakes'
+            },
+            style: {width: '100%'}
+        }],
+    }
+}
+
+Neo.setupClass(MainView);
+
+export default MainView;
+</pre>
+
+Save, refresh, and look at network traffic: you'll see a _single_ call to the web service.
+
+<img style="width:80%" src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/EarthquakesTwoTablesOneCall.png"></img>
+
+You can further prove we're using a shared instance by running these statements in the console.
+
+<pre data-javascript>
+a = Neo.findFirst({ntype:'earthquakes-main'}).model.stores.earthquakes;
+b = Neo.find({ntype:'earthquakes-table'})[0].store;
+c = Neo.find({ntype:'earthquakes-table'})[1].store;
+
+(a === b) && (a === c) && (b === c) // true
+</pre>
+
+</details>
+
+<details>
+<summary>Use the view model class</summary>
+
+We configured the view model in-line, in the `model` config at the top of `MainView`. But the starter app
+has a `MainViewModel` class. In theory, if you have a trivial view model you could configure it in-line. But
+in general you want to keep that code separate by coding it in a separate class. This is what we did for the
+table config &mdash; we started by coding it in-line in the main view, then we refactored it into its own
+class. The result was a simpler and more abstract main view. We want to do the same for the view model.
+
+Since the starter app already provides `MainViewModel`, all we need to do is copy the `stores` property.
+
+Here's the resulting code you should place into `MainViewModel.mjs`.
+
+<pre data-javascript>
+import Model from '../../../node_modules/neo.mjs/src/model/Component.mjs';
+import Store from '../../../node_modules/neo.mjs/src/data/Store.mjs';
+
+class MainViewModel extends Model {
+    static config = {
+        className: 'Earthquakes.view.MainViewModel',
+
+        data: {},
+        stores: {
+            earthquakes: {
+                module: Store,
+                model: {
+                    fields: [{
+                        name: "humanReadableLocation"
+                    }, {
+                        name: "size"
+                    }, {
+                        name: "timestamp",
+                        type: "Date"
+                    }]
+                },
+                url: "https://apis.is/earthquake/is",
+                responseRoot: "results",
+                autoLoad: true
+            },    
+        }
+    }
+}
+
+Neo.setupClass(MainViewModel);
+
+export default MainViewModel;
+</pre>
+
+And you need to remove the `stores` config from the main view as follows.
+
+<pre data-javascript>
+import Container        from '../../../node_modules/neo.mjs/src/container/Base.mjs';
+import Controller       from './MainViewController.mjs';
+import EarthquakesTable from './earthquakes/Table.mjs';
+import ViewModel        from './MainViewModel.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Earthquakes.view.MainView',
+        ntype: 'earthquakes-main',
+        controller: {module: Controller},
+        model: {
+            module: ViewModel
+        },
+
+        layout: { ntype: 'vbox', align: 'stretch' },
+        items: [{
+            module: EarthquakesTable,
+            bind: {
+                store: 'stores.earthquakes'
+            },
+            style: {width: '100%'}
+        },{
+            module: EarthquakesTable,
+            bind: {
+                store: 'stores.earthquakes'
+            },
+            style: {width: '100%'}
+        }]
+    }
+}
+
+Neo.setupClass(MainView);
+
+export default MainView;
+</pre>
+
+The refactorings to have separate table and view model classes means the code is more modular, more reusable,
+and each class is simpler than using complex source files that try to configure every detail.
+
+</details>
+

package/resources/data/deck/learnneo/pages/Earthquakes-Lab-07-use-the-google-maps-addon.md

@@ -0,0 +1,175 @@
+<details>
+<summary>Get the code for the custom add-on</summary>
+At the time this tutorial was written, the Neo.mjs Google Maps addon was about to be updated to 
+accomodate Google's "AdvancedMarker" class. Until that's ready, we're going to use a modified version of the add-on. 
+
+Download and unzip this file, and copy the two source files to the corresponding subdirectories in
+your workspace's `src` directory. Note that `src` already contains some files, so don't replace the whole
+directory, but instead, move the files to their individual locations.
+
+<a href="https://s3.amazonaws.com/mjs.neo.learning.images/zip/src.zip">src.zip</a>
+
+<img src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/CopyGoogleMapsFiles.png" width="30%%"></img>
+</details>
+
+<details>
+<summary>Specify the main-thread add-on</summary>
+
+Edit `apps/earthquakes/neo-config.json` and add entries for the Google Maps add-on and the map key.
+
+<pre data-javascript>
+{
+    "appPath": "../../apps/earthquakes/app.mjs",
+    "basePath": "../../",
+    "environment": "development",
+    "mainPath": "../node_modules/neo.mjs/src/Main.mjs",
+    "mainThreadAddons": [
+        "DragDrop",
+        "WS/GoogleMaps",
+        "Stylesheet"
+    ],
+    "googleMapsApiKey": "AIzaSyD4Y2xvl9mGT8HiVvQiZluT5gah3OIveCE",
+    "themes"          : ["neo-theme-neo-light"],
+    "workerBasePath": "../../node_modules/neo.mjs/src/worker/"
+}
+</pre>
+
+It's unusual to need to edit `neo-config.json`. The app theme is specified there, and so are main thread add-ons.
+In our case, we're adding `WS/GoogleMaps` which in turn requires that we specify the map key. The `WS/`
+prefix tells Neo.mjs that the add-on is in our workspace, rather than an add-on provided by Neo.mjs.
+
+Save and refresh, and you'll see a console log emanating from the plugin.
+
+<img style="width:80%" src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/GoogleMapsLoaded.png"></img>
+
+</details>
+
+<details>
+<summary>Add the required fields to the records</summary>
+
+The Google Maps component has a `markerStore` property, which is a reference to a store whose records have
+the properties `title` and `location`, where `location` is of the form `{lat: 0, lng: 0}`. The `fields:[]`
+lets us implement those via two properties:
+
+- `mapping` &mdash; the path to a feed property holding the value
+- `calculate` &mdash; a function that returns a value
+
+Edit `apps/earthquakes/view/MainViewModel.mjs` and modify `fields` as follows.
+
+<pre data-javascript>
+fields: [{
+    name: "humanReadableLocation",
+}, {
+    name: "size",
+}, {
+    name: "timestamp",
+    type: "Date",
+}, {
+    name: 'title',
+    mapping: "humanReadableLocation"
+}, {
+    name: "position",
+    calculate: (data, field, item)=>({lat: item.latitude, lng: item.longitude})
+}],
+</pre>
+
+As you can see, _title_ is mapped to the existing feed value _humanReadableLocation_, and _position_ is
+calculated by returning an object with _lat_ and _lng_ set to the corresponding values from the feed.
+
+Save and refresh _earthquakes_. You can use the debugger to inspect the store via _Shift-Ctrl-right-click_ and
+putting the main view into a global variable. Then run
+
+    temp1.getModel().stores.earthquakes.items
+
+Look at one of the items and you should see that _title_ and _location_ are in each record.
+
+<img style="width:80%" src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/StoreHasTitleAndLocation.png"></img>
+
+</details>
+
+<details>
+<summary>Use the Google Map Component</summary>
+
+We're going to replace the top table with a Google Map. To do that we need to import the Google Maps component
+and show it implace of the top table. The map should be centered on Iceland. To wit
+
+<pre>
+{
+    module: GoogleMapsComponent,
+    flex: 1,
+    center: {
+        lat: 64.8014187,
+        lng: -18.3096357
+    },
+    zoom: 6
+}
+</pre>
+
+If we replace the top table with the map, `view/MainView.mjs` ends up with this content.
+
+<pre data-javascript>
+
+import Container           from '../container/Base.mjs';
+import Controller          from './MainViewController.mjs';
+import EarthquakesTable    from './earthquakes/Table.mjs';
+import GoogleMapsComponent from '../component/wrapper/GoogleMaps.mjs';
+import ViewModel           from './MainViewModel.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Earthquakes.view.MainView',
+        ntype: 'earthquakes-main',
+        controller: {module: Controller},
+        model: {
+            module: ViewModel
+        },
+
+        layout: { ntype: 'vbox', align: 'stretch' },
+        items: [{
+            module: GoogleMapsComponent,
+            flex: 1,
+            center: {
+                lat: 64.8014187,
+                lng: -18.3096357
+            },
+            zoom: 6
+        },{
+            module: EarthquakesTable,
+            bind: {
+                store: 'stores.earthquakes'
+            },
+            style: {width: '100%'},
+            wrapperStyle: {
+                height: 'auto' // Because neo-table-wrapper sets height:'100%', which it probably shouldn't
+            }
+        }],
+    }
+}
+
+Neo.setupClass(MainView);
+
+export default MainView;
+</pre>
+
+<img style="width:80%" src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/CenteredMap.png"></img>
+
+
+</details>
+
+<details>
+<summary>Show the markers</summary>
+
+The markers are shown by setting up the marker store, which is a regular store whose records must contain
+_location_ and _title_. We assign the store using a `bind`, just like we did with the tables.
+
+Add this config to the map.
+
+<pre data-javascript>
+bind: {
+    markerStore: 'stores.earthquakes'
+},
+</pre>
+<img style="width:80%" src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/InitialMapWithMarkers.png"></img>
+
+</details>
+

package/resources/data/deck/learnneo/pages/Earthquakes-Lab-08-events.md

@@ -0,0 +1,38 @@
+In this lab you'll set up an event handler for the table and map.
+
+<details>
+<summary>Add a listener to the table</summary>
+
+Tables fire a select event, passing an object that contains a reference to the corresponding row.
+
+Add this table config:
+
+    listeners: {
+        select: (data) => console.log(data.record)
+    }
+
+Save and refresh, then click on a table row. If you look at the debugger console you'll see the record being logged.
+
+Just for fun, expand the logged value and look for the size property. If you recall, that's a value from the feed, and one of the things we configured in the store's fields:[].
+
+In the console, click on the ellipses by size and enter a new value, like 2.5. (Don't enter a larger value, or you may destroy that part of Iceland.)
+
+<img style="width:80%" src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/LogTableClick.png"></img>
+
+After changing the value you should immediately see it reflected in the table row.
+
+</details>
+
+<details>
+<summary>Add a listener to a map event
+</summary>
+
+Now add a `markerClick` listener to the Google Map.
+
+    listeners: {
+        markerClick: data => console.log(data.data.record)
+    },
+
+Save, refresh, and confirm that you see the value logged when you click on a map marker.
+
+</details>

package/resources/data/deck/learnneo/pages/Earthquakes.md

@@ -532,7 +532,7 @@ class MainView extends Base {
                         type: "Date",
                     }],
                 },
-                url: "https://apis.is/earthquake/is",
+                url: "https://nameless-tundra-27404.herokuapp.com/go/?fn=earthquakes",
                 responseRoot: "results",
                 autoLoad: true,
             },
@@ -604,7 +604,7 @@ Here's the config for the store.
             type: "Date",
         }],
     },
-    url: "https://apis.is/earthquake/is",
+    url: "https://nameless-tundra-27404.herokuapp.com/go/?fn=earthquakes",
     responseRoot: "results",
     autoLoad: true,
 }
@@ -773,7 +773,7 @@ static config = {
                         type: "Date",
                     }],
                 },
-                url: "https://apis.is/earthquake/is",
+                url: "https://nameless-tundra-27404.herokuapp.com/go/?fn=earthquakes",
                 responseRoot: "results",
                 autoLoad: true,
             },
@@ -896,7 +896,7 @@ class MainView extends Base {
                             type: "Date"
                         }]
                     },
-                    url: "https://apis.is/earthquake/is",
+                    url: "https://nameless-tundra-27404.herokuapp.com/go/?fn=earthquakes",
                     responseRoot: "results",
                     autoLoad: true
                 },    
@@ -920,7 +920,7 @@ class MainView extends Base {
                         type: "Date"
                     }]
                 },
-                url: "https://apis.is/earthquake/is",
+                url: "https://nameless-tundra-27404.herokuapp.com/go/?fn=earthquakes",
                 responseRoot: "results",
                 autoLoad: true
             },
@@ -939,7 +939,7 @@ class MainView extends Base {
                         type: "Date"
                     }]
                 },
-                url: "https://apis.is/earthquake/is",
+                url: "https://nameless-tundra-27404.herokuapp.com/go/?fn=earthquakes",
                 responseRoot: "results",
                 autoLoad: true
             },
@@ -1012,7 +1012,7 @@ class MainView extends Base {
                             type: "Date"
                         }]
                     },
-                    url: "https://apis.is/earthquake/is",
+                    url: "https://nameless-tundra-27404.herokuapp.com/go/?fn=earthquakes",
                     responseRoot: "results",
                     autoLoad: true
                 },    
@@ -1092,7 +1092,7 @@ class MainViewModel extends Model {
                         type: "Date"
                     }]
                 },
-                url: "https://apis.is/earthquake/is",
+                url: "https://nameless-tundra-27404.herokuapp.com/go/?fn=earthquakes",
                 responseRoot: "results",
                 autoLoad: true
             },    

package/resources/data/deck/learnneo/pages/GuideEvents.md

@@ -231,6 +231,7 @@ relating to changes to the store. The event handler if a function run when the e
 A binding detects a changed view model value, and assigns it to a property. 
 
 
+
 ### When to use an event
 
 Events and event handlers are used when you need to run non-trivial logic in response to the event. For example, you 
@@ -245,9 +246,87 @@ like a button click or component focus.
 A binding is a way to keep properties in sync with values in the view model hierarchy. For example, button text, 
 field values, or store properties, can simultaneously reflect the same view model property. That's pretty handy, 
 but keep in mind that a class can define a property as a _lifecycle property_. That means that updating a property
-can may result in complex logic being triggered. Furthermore, a _two way binding_ meansx 
+can may result in complex logic being triggered. Furthermore, a _two way binding_ means a change to a property 
+will automatically be reflected in the view model.
+
+### A simple comparison
+
+To contrast syntax, and to illustrate the simplicity of a binding, let's look at two exmaples of updating a component
+to reflect the value of a text field. THe first example uses events; the second uses bindings.
+
+<pre data-neo>
+import Container from '../container/Base.mjs';
+import TextField from '../form/field/Text.mjs';
+import Component from '../component/Base.mjs';
 
+class MainView extends Container {    
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'start'},
 
+        items: [{
+            module   : TextField,
+            labelText: 'Text',
+            reference: 'textFieldOne',
+            value: 'Hello',
+            listeners: {
+                change    : 'up.onTextChange'
+            }
+        }, {
+            module   : TextField,
+            labelText: 'Text',
+            reference: 'textFieldTwo',
+            value: 'world!',
+            listeners: {
+                change    : 'up.onTextChange'
+            }
+        }, {
+            module: Component,
+            reference: 'foo',
+        }]        
+    }
+    onTextChange(data){
+        this.getReference('foo').html = `${this.getReference('textFieldOne').value} ${this.getReference('textFieldTwo').value}`
+    }
+}
+Neo.setupClass(MainView);
+</pre>
+
+<pre data-neo>
+import Container from '../container/Base.mjs';
+import TextField from '../form/field/Text.mjs';
+import Component from '../component/Base.mjs';
+
+class MainView extends Container {    
+    static config = {
+        className: 'Example.view.MainView',
+        model: {
+            data: {
+                foo: 'Hello',
+                bar: 'world!'
+            }
+        },
+        layout   : {ntype:'vbox', align:'start'},
+        
+        items: [{
+            module   : TextField,
+            labelText: 'Text',
+            bind: {value: {twoWay: true, value: data => data.foo}}
+        }, {
+            module   : TextField,
+            labelText: 'Text',
+            bind: {value: {twoWay: true, value: data => data.bar}}
+        }, {
+            module: Component,
+            bind: {html: data => `${data.foo} ${data.bar}`}
+        }]
+    }
+    onTextChange(data){
+        this.getReference('foo').html = data.value;
+    }
+}
+Neo.setupClass(MainView);
+</pre>
 
 ##