neo.mjs 6.18.2 → 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
             },    
@@ -1298,10 +1298,10 @@ If we replace the top table with the map, `view/MainView.mjs` ends up with this
 
 <pre data-javascript>
 
-import Container           from '../../../node_modules/neo.mjs/src/container/Base.mjs';
+import Container           from '../container/Base.mjs';
 import Controller          from './MainViewController.mjs';
 import EarthquakesTable    from './earthquakes/Table.mjs';
-import GoogleMapsComponent from '../../../src/component/wrapper/GoogleMaps.mjs';
+import GoogleMapsComponent from '../component/wrapper/GoogleMaps.mjs';
 import ViewModel           from './MainViewModel.mjs';
 
 class MainView extends Container {

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

@@ -14,8 +14,8 @@ The code below shows two text fields, with `listeners` for `change` and `focusEn
 (The events for any component are documented in the API docs.)
 
 <pre data-neo>
-import Container from '../../../../src/container/Base.mjs';
-import TextField from '../../../../src/form/field/Text.mjs';
+import Container from '../container/Base.mjs';
+import TextField from '../form/field/Text.mjs';
 
 class MainView extends Container {
     static config = {
@@ -53,7 +53,7 @@ A `Neo.controller.Component` is a simple class associated with a component class
 instance of its associated controller is automatically created. 
 
 <pre data-neo>
-import Base from '../../../../src/controller/Component.mjs';
+import Base from '../controller/Component.mjs';
 
 class MainViewController extends Base {
     static config = {
@@ -67,8 +67,8 @@ class MainViewController extends Base {
 Neo.setupClass(MainViewController);
 
 
-import Container from '../../../../src/container/Base.mjs';
-import TextField from '../../../../src/form/field/Text.mjs';
+import Container from '../container/Base.mjs';
+import TextField from '../form/field/Text.mjs';
 
 class MainView extends Container {
     static config = {
@@ -118,8 +118,8 @@ before the value is accessed. We're using the _after_ method to fire a `change`
 
 
 <pre data-neo>
-import Button    from '../../../../src/button/Base.mjs';
-import Container from '../../../../src/container/Base.mjs';
+import Button    from '../button/Base.mjs';
+import Container from '../container/Base.mjs';
 
 class ToggleButton extends Button {
     static config = {

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

@@ -6,9 +6,9 @@ to test.
 Consider this code. It's a panel with a header and a table. The table has a store. 
 
 <pre data-neo>
-import Button from '../../../../src/button/Base.mjs';
-import Panel  from '../../../../src/container/Panel.mjs';
-import Table  from '../../../../src/table/Container.mjs';
+import Button from '../button/Base.mjs';
+import Panel  from '../container/Panel.mjs';
+import Table  from '../table/Container.mjs';
 
 class MainView extends Panel {
     static config = {
@@ -49,10 +49,10 @@ have been refactored into their own classes, and the main view is using them. Th
 more abstract, and each class can be reused, tested, and maintained independently. 
 
 <pre data-neo>
-import Button from '../../../../src/button/Base.mjs';
-import Panel  from '../../../../src/container/Panel.mjs';
-import Store  from '../../../../src/data/Store.mjs';
-import Table  from '../../../../src/table/Container.mjs';
+import Button from '../button/Base.mjs';
+import Panel  from '../container/Panel.mjs';
+import Store  from '../data/Store.mjs';
+import Table  from '../table/Container.mjs';
 
 class BeatlesButton extends Button {
     static config = {