neo.mjs 6.9.10 → 6.9.11

package/resources/data/deck/training/p/2023-01-15T18-51-52-134Z.md

@@ -0,0 +1,83 @@
+#Introduction
+
+In this lab you'll add `city` and `category` properties.
+
+#Steps
+
+??Define a city_ property
+
+Add a `city_:''` config. 
+
+As you know, this creates a get/set property.
+
+Save your changes, then in the Chrome debugger's app-worker context
+get a reference to the filter component and confirm that the property
+exists.
+
+Is the property there? This statement should evaluate to '' (and not undefined).
+
+    Neo.findFirst({ntype:'yelp-filter'}).city
+
+Assign a value.
+
+    Neo.findFirst({ntype:'yelp-filter'}).city = 'Madison'
+
+Read the value. This should evaluate the city you assigned above.
+
+    Neo.findFirst({ntype:'yelp-filter'}).city
+
+None of this is very surprising yet. The `city` property would behave
+the same whether it was a simple property or a get/set property.
+
+
+??Detect when `city` changes
+
+We need a function to be run when the city property changes. Later,
+we'll use that function to update the text field.
+
+How do you detect a change to a get/set property? Via its `afterSet...`
+method!
+
+Add that method, with a single statement that logs the passed value.
+
+<pre class="runnable readonly text 320">
+import Base from '../../../../node_modules/neo.mjs/src/container/Base.mjs';
+import TextField from '../../../../node_modules/neo.mjs/src/form/field/Text.mjs';
+class Filter extends Base {
+    static config = {
+        ...
+    }
+
+    afterSetCity(city) {
+        console.log(city);
+    }
+}
+
+Neo.applyClassConfig(Filter);
+
+export default Filter;
+</pre>
+
+??Test the filter on the command line
+
+Use the debugger's console (in the app worker context) and verify that
+you see the value logged. In other words, runing the following should result
+in `afterSetCity()` being run.
+
+    Neo.findFirst({ntype:'yelp-filter'}).city = 'Madison'
+
+
+??Add a `category` get/set
+
+Now add a `category_:'',` config, and a corresponding `afterSetCategory()`
+method. The code will be almost identical to what you did for city.
+
+Test your code by setting and getting `category` on the command line.
+
+    Neo.findFirst({ntype:'yelp-filter'}).category
+
+    Neo.findFirst({ntype:'yelp-filter'}).category = 'pizza'
+
+    Neo.findFirst({ntype:'yelp-filter'}).category
+
+You should see the value updating and the value being logged.

package/resources/data/deck/training/p/2023-01-15T20-03-30-073Z.md

@@ -0,0 +1,11 @@
+`Neo.component.Base` also has a `reference` config.
+
+If you code a component with `reference:'foo',`, then you can get
+a reference from the view or controller via `this.getReference('foo')`.
+
+This is similar to using the Neo find methods, but references are
+resolved in a more efficient manner and the scope is limited to 
+what the view can "see".
+
+<span style="color:lightgray">(Controllers keep a map of references, keyed by the reference name. The <code style="color:lightgray">getReference()</code> method 
+uses bracket notiation to retrieve the value from the map &mdash; it's lighting fast.)</span>

package/resources/data/deck/training/p/2023-01-15T22-07-52-073Z.md

@@ -0,0 +1,16 @@
+Those labs were lengthy because we worked _very_ slowly and methodically.
+
+On a project, encapsulating code like this isn't usually needed. You code
+views that show data, and you nest those in containers.
+
+But if you need a propertly encapsulated class you'll do something like you
+did with the `Yelp.view.businesses.Filter`. 
+
+But there isn't much code in there! 
+
+- It has a property
+- Updates to the properties are reflected in the view
+- Updates to the view are reflected in the properies
+
+After you code a couple of such classes it becomes a matter of minutes
+to code them.

package/resources/data/deck/training/p/2023-01-15T22-22-13-517Z.md

@@ -0,0 +1,12 @@
+The following four labs are elaborate.
+
+They give you 
+practice with a common coding task: creating a de-coupled
+class with a well-defined API.
+
+Neo has features that makes this easy. Later we'll cover
+additional techniques for having a de-coupled class interact
+with the rest of an application via events and bindings.
+
+The labs feature common coding use-cases. Take your time —
+make sure everything makes sense!

package/resources/data/deck/training/p/2023-01-15T22-28-57-508Z.md

@@ -0,0 +1,131 @@
+#Introduction
+
+In this lab you'll udpate the text fields as the properties change.
+
+#Steps
+
+??Add `reference` to the fields
+
+First, add a `reference:'city',` to the city field config
+and `reference:'category',` to the category field.
+
+As you recall from lecture, `reference` is used in component
+or controller methods to get a reference to the field via
+`this.getReference()`.
+
+??Update the city field
+You already have an `afterSetCity()` method.
+
+Modify it to udpdate the city.
+
+    this.getReference('city').value = city;
+
+If you save and run the code you get a runtime error!
+That happens because when the value is first applied (to assign
+the initial defined in `city_:'',`) the view hasn't
+been rendered yet! `Neo.component.Base` has a `rendered` property.
+We need a statement to test that. Add this statement before 
+you assign the city to the field.
+
+    if (!this.rendered) return;
+
+<pre style="border: thin solid gray; padding: 8px; color: lightgray; font-size:14pt;">
+import Base from '../../../../node_modules/neo.mjs/src/container/Base.mjs';
+import TextField from '../../../../node_modules/neo.mjs/src/form/field/Text.mjs';
+import Function from '../../util/Function.mjs';
+class Filter extends Base {
+    static config =  {
+        className: 'Yelp.view.businesses.Filter',
+        ntype: 'yelp-filter',
+
+        city_: '',
+        category_: '',
+
+        layout: { ntype: 'hbox' },
+        itemDefaults: {module: TextField, clearable: true,},
+        items: [
+            ...
+        ]
+    }
+    afterSetCity(city) {
+        console.log(city);
+        <span style="color:#b91010;">if (!this.rendered) return;
+        this.getReference('city').value = city;</span>
+    }
+    afterSetCategory(category) {
+        console.log(category);
+    }
+}
+
+Neo.applyClassConfig(Filter);
+
+export default Filter;
+</pre>
+
+??Test the code
+
+In the Chrome debugger update the city property. You should see the
+text field update to reflect the change.
+
+    Neo.findFirst({ntype:'yelp-filter'}).city = 'Madison'
+
+??Add the same logic for category
+
+Modify the `afterSetCategory()` method to work like the after city method.
+
+Test it in the Chrome debugger. You should see the category text field updating.
+
+    Neo.findFirst({ntype:'yelp-filter'}).category = 'pizza'
+
+??Notice a timing issue
+
+Currently, the initial city and category are just empty strings.
+But if there had some other values we'd want the city and category
+text fields to reflect those values as we start the app.
+
+For example, change the city and category like this:
+
+    city_: 'Madison',
+    category_: 'pizza',
+
+Upon refresh these values are _not_ seen in the fields, but you _will_
+see the values in the Crome debugger 
+
+    console.log(Neo.findFirst({ntype:'yelp-filter'}).city); // Logs "Madison"
+
+The initial values _are_ assigned, and the `afterSet...` methods are run, 
+but since the view hasn't been rendered the `after` methods can't initialize
+the fields.
+
+??Fix the issue
+
+We need to detect when the view is rendered, then update
+the text fields to their initial values. 
+
+Since `Neo.component.Base` has a `mounted` get/set,
+there's a corresponding `afterSetMounted()` method. We'll add the code
+there.
+
+Use the following code. Note the 20ms delay. That's there because
+after a view is mounted, the DOM may not update until one "frame" 
+later, which is about 18ms. 
+
+    afterSetMounted() {
+        // Wait for one "frame" using a framerate of 60 per second = 17.7 ms
+        setTimeout(() => {
+            this.afterSetCity(this.city);
+            this.afterSetCategory(this.category);
+        }, 20);
+    }
+
+Save and refresh. You should see the new default values as the initial
+values for the city and category text fields.
+
+??Make sure `city` and `category` have their normal default values
+
+Change city and category back to their normal default values.
+
+    city_: '',
+    category_: '',
+
+In an upcoming lab we'll use another method of initializing the city and category.

package/resources/data/deck/training/p/2023-01-15T22-36-30-913Z.md

@@ -0,0 +1,115 @@
+#Introduction
+
+In this lab you'll update the property as the text fields change.
+
+#Steps
+
+??Update `city` as the user types.
+
+We want changes in the text field to be reflected in the filter's `city` property.
+
+To do that, listen to the field's `change` event, and in the handler get a 
+reference to the parent container, and assign the value to it's `city` property.
+
+    listeners: {
+        change: (data) => data.component.up('yelp-filter').city = data.value
+    }
+
+Test this by entering text in the city field — you should see a the console
+log being run on each keypress.
+
+??Do the same for `category`
+
+Add a similer `listeners` config to the category field. 
+
+Test this by entering text in the category field — you should see a the console
+log being run on each keypress.
+
+??Plan a way to buffer or _debounce_ the updates
+
+Conceptually, `Yelp.view.business.Filter` has `city` and `category` properties.
+
+"Madison" is a city, but "M" and "Ma" and "Mad" are not cities, so the
+_city_ property shouldn't reflect those intermediate values. Therefore,
+we need code to defer updating the property until the user appears to have 
+finished typing. 
+
+There are various ways to create a _buffer_ or _debouce_ fuctions, and
+we found one via an internet search. We need a place to hold our implementation.
+
+??Add a utility class with a `debounce` function
+
+Use a terminal to navigate to the Neo workspace, and run `npm run create-class`.
+    
+- Name the class "Yelp.util.Function"
+- Extend `Neo.core.Base
+- Make it a singleton
+
+Edit the new file and add the debounce routine highlighted below.
+
+<pre style="border: thin solid gray; padding: 8px; color: lightgray;font-size:14pt;">
+import Base from '../../../node_modules/neo.mjs/src/core/Base.mjs';
+
+class Function extends Base {
+    static config = {
+        className: 'Yelp.util.Function',
+        singleton: true
+    }
+    <span style="color:#b91010;">debounce(func, wait, immediate) {
+        let timeout
+        return function (...args) {
+            clearTimeout(timeout)
+            timeout = setTimeout(() => {
+                timeout = null
+                if (!immediate) func.apply(this, args)
+            }, wait)
+            if (immediate && !timeout) func.apply(this, [...args])
+        }
+    }</span>
+}
+
+Neo.applyClassConfig(Function);
+
+let instance = Neo.create(Function);
+
+Neo.applyToGlobalNs(instance);
+
+export default instance;
+</pre>
+
+??Buffer the updates
+
+Edit `view/businesses/Filter.mjs` and add this import.
+
+    import Function from '../../util/Function.mjs';
+
+And add a method designed to do a buffered update to a property.
+
+    doBufferedUpdate(property, value) {
+        this._bufferedUpdate = this._bufferedUpdate || Function.debounce((property, value) => this[property] = value, 500);
+        this._bufferedUpdate(property, value);
+    }
+
+??Use the new function when the city text field changes 
+
+Modify the city's `change` listener to use the new function.
+
+    listeners: {
+        change: (data) => data.component.up('yelp-filter').doBufferedUpdate('city', data.value)
+    }
+
+Test the changes by running the app, and type a city name. After the 500ms delay 
+you should see the city name logged. Note that running 
+    
+    Neo.findFirst({ntype:'yelp-filter'}).city = 'Madison'
+
+logs the city name immediately. Changing the city to a new value updates
+immediately. We only need to buffer changes when the user is typing.
+
+??Have the category field do the same thing
+
+Make a similar change to the category field config.
+
+    listeners: {
+        change: (data) => data.component.up('yelp-filter').doBufferedUpdate('category', data.value)
+    }

package/resources/data/deck/training/p/2023-01-16T16-03-40-770Z.md

@@ -0,0 +1,12 @@
+You simply assign or read values to access a property.
+
+    console.log(component.bar); // Results in the secret getter being run
+    component.bar = 'hi';       // Results in the secret setter being run 
+
+You can set multiple values simultaneously via `Neo.component.Bases#set({})`
+
+    component.set({
+        bar: 'hi',
+        baz: 'there'
+    });
+

package/resources/data/deck/training/p/2023-01-16T20-21-56-859Z.md

@@ -0,0 +1,5 @@
+The `headers:[{}]` // An array of component configs
+
+Components in the headers array are tagged with a `dock` property
+used to specify where the header is placed: top, right, bottom, or left.
+

package/resources/data/deck/training/p/2023-01-16T20-24-09-690Z.md

@@ -0,0 +1,24 @@
+A tab container is a card-layout container with a tab bar and styled buttons.
+Do not specify a `layout` for tab containers.
+
+The buttons are configured via `tabButtonConfig`
+
+    activeIndex: 2,
+    tabBarPosition: 'left', // top, right, bottom, left
+    itemDefaults: { module: Button },
+    items: [{
+        tabButtonConfig: {
+            iconCls: 'fa fa-home',
+            text: 'Tab 1'
+        }
+    }, {
+        tabButtonConfig: {
+            iconCls: 'fa fa-play-circle',
+            text: 'Tab 2'
+        }
+    }, {
+        tabButtonConfig: {
+            iconCls: 'fa fa-bell',
+            text: 'Tab 3'
+        }
+    }]

package/resources/data/deck/training/p/2023-01-20T12-51-22-646Z.md

@@ -0,0 +1,21 @@
+
+
+<div class="expander" caption="High-level Goal">
+<h2>To learn how to properly encapsulate a class with a well defined API.</h2>
+<p>
+You'll code a class that's encapsulated and de-coupled, where the code creating
+the instance uses class properties and otherwise has no awareness of its
+implementation details.
+</p>
+</div>
+
+
+<div class="expander" caption="Low-level Goal">
+<h2>To get practice using the syntax and features we just learned.</h2>
+<ul>
+<li>Defining get/set properties
+<li>Using `afterSet` methods to detect property change
+<li>Using `reference` and `getReference()`
+</ul>
+</div>
+

package/resources/data/deck/training/p/2023-01-20T13-06-46-614Z.md

@@ -0,0 +1,9 @@
+- A view controller holds a view's event handlers
+- The controller can hold any other logic you might need
+
+
+The existence of a controller should be unknown outside of the class.
+The decision of the view's author to use (or not use) a controller
+should be transparent outside of the class.
+    
+    this.lookup('someComponent').controller.someMethod(); // This is bad

package/resources/data/deck/training/p/2023-01-20T13-08-51-600Z.md

@@ -0,0 +1,7 @@
+Within controller methods you can get a reference to a view component
+via 
+
+- `this.getReference('name')` returns a component with the specified reference
+- In the view, you specify the reference via `reference: 'somename`
+
+- `onComponentConstructed()` is a controller lifecycle method you can override if you need to do something at time of component creation

package/resources/data/deck/training/p/2023-01-20T15-20-13-363Z.md

@@ -0,0 +1,26 @@
+#Introduction
+
+In this lab you'll put the view model into its own class.
+
+#Steps
+
+
+??Create the view model
+
+Use `npm run create-class` to create`Yelp.view.MainViewModel` that extends `model/Component`.
+
+??Use it
+
+Move the `data` property from the main view to the view model.
+
+Then import the view model, and change the `model` config to use the new class.
+
+??Create and use a controller
+
+We don't need controller logic yet, but we will, so while we're at it, create a
+`Yelp.view.MainViewController` that extends `controller/Component`. Import it in the 
+main view, and configure a controller block to use it.
+
+    controller: {
+        module: MainViewController
+    }

package/resources/data/deck/training/p/2023-01-20T15-34-58-813Z.md

@@ -0,0 +1,75 @@
+#Introduction
+
+In this lab you'll detect changes to city and category.
+When city changes you'll geocode it to find its latitude and longitude.
+
+#Steps
+
+??Remove the view model listener in the main view
+
+To avoid being overwhelmed with `console.log()` output, edit
+the main view and remove the `listeners` config in the 
+view model config. From now on on the view model listening logic
+will be set up in the main view controller.
+
+??Detect view model property changes
+
+In the main view controller override the `onComponentConstructed()` method. The method
+should check for changes to _city_ and if so, call a new method `onCityChange(city)`.
+
+    onComponentConstructed() {
+        const model = this.getModel();
+        this.onCityChange(model.data.city);
+        model.on('dataPropertyChange', data => {
+            if (data.key === 'city') this.onCityChange(data.value);
+        });
+    }
+    onCityChange(city) {
+        if (!city) return;
+        // The code to geocode the city goes here.
+        console.log(city);
+    }
+
+Save, change the city, and look for the console log in the debugger console.
+
+??Geocode the city
+
+Use the following call to `Neo.main.addon.GoogleMaps.geocode`. The details of the
+call and the response aren't important right now, although if you're curious you
+can read <a href="https://developers.google.com/maps/documentation/geocoding/requests-geocoding" target="_blank">the Google Maps geocoding API</a>. 
+
+<pre style='padding: 4px; font-size: 13.5pt; border: thin solid gray; color:lightgray'>
+onCityChange(city) {
+    if (!city) return;
+    <span style='color:firebrick'>Neo.main.addon.GoogleMaps.geocode({ address: city })
+        .then(data => this.getModel().data.center = data.results[0].geometry.location);</span>
+}
+</pre>
+
+
+
+??Stub out a method that will eventually be fetching Yelp data
+
+Add this method.
+
+    doFetchYelpData() {
+        const model = this.getModel();
+        console.log('Fetch yelp data', model.data.center, model.data.category);
+    }
+
+And modify `onComponentConstructed()` to check for changes to _center_ and _category_.
+
+<pre style='padding: 4px; border: thin solid gray; color:lightgray'>
+onComponentConstructed() {
+    const model = this.getModel();
+    this.onCityChange(model.getData('city'));
+    model.on('dataPropertyChange', data => {
+        if (data.key === 'city') this.onCityChange(data.value);
+        <span style='color:firebrick'>if (data.key === 'center') this.doFetchYelpData();
+        if (data.key === 'category') this.doFetchYelpData();</span>
+    });
+}
+</pre>
+
+Save, refresh, and verify that `doFetchYelpData()` is logging changes to the map center
+(via changes to city), and category. 

package/resources/data/deck/training/p/2023-01-21T16-33-20-458Z.md

@@ -0,0 +1,33 @@
+Some components, such as `Neo.table.Container`, have a `store` config.
+
+<pre style="padding: 8px; border: thin solid lightgray; font-size: 11pt; ">
+{
+    module: EarthquakesTable,
+    listeners: {
+        select: 'onTableSelect'
+    },
+    store: {
+        module: Store,
+        model: {
+            fields: [{
+                name: 'humanReadableLocation'
+            }, {
+                name: 'size',
+                ntype: 'data-field-float',
+            }, {
+                name: 'timestamp',
+                type: 'Date'
+            }, {
+                name: 'title',
+                calculate: (data, field, item) => item.humanReadableLocation
+            }, {
+                name: 'position',
+                calculate: (data, field, item) => ({ lat: item.latitude, lng: item.longitude })
+            }]
+        },
+        url: 'https://apis.is/earthquake/is',
+        responseRoot: 'results',
+        autoLoad: true
+    }
+}
+</pre>

package/resources/data/deck/training/p/2023-01-21T16-45-28-263Z.md

@@ -0,0 +1,28 @@
+
+<pre style="padding: 8px; border: thin solid lightgray; font-size: 13pt; ">
+class MainViewModel extends Base {
+    static getConfig() {
+        return {
+            className: 'Earthquakes.view.MainViewModel',
+            data: {},
+            stores: {
+                earthquakes: {
+                    module: Store,
+                    model: {
+                        ...
+                    },
+                    ...
+                }
+            }
+        }
+    }
+}</pre>
+
+<pre style="padding: 8px; border: thin solid lightgray; font-size: 13pt; ">
+{
+    module: EarthquakesTable,
+    bind: {
+        store: 'stores.earthquakes'
+    },
+}
+</pre>

package/resources/data/deck/training/p/2023-01-21T16-56-25-452Z.md

@@ -0,0 +1,3 @@
+You may also define the store as a class. You might do this if you need to create multiple instances.
+Once you've defined the type you can use it the same way you'd create any store — in a config or a view model
+

package/resources/data/deck/training/p/2023-01-21T17-28-31-493Z.md

@@ -0,0 +1,6 @@
+Finally, you can procedurally create a store via Neo.create(). But it's always preferable to create a store — or any object — declaratively.
+
+    const store = Neo.create({
+        module : Store,
+    });
+    this.getReference('mytable').store = store;

package/resources/data/deck/training/p/2023-01-21T19-49-51-918Z.md

@@ -0,0 +1,13 @@
+If the record's value isn't a simple conversion from the value in the feed
+you can provide a `calculate` method. For example:
+
+    {
+        name: 'position',
+        calculate: (record, field, data) => ({ lat: data.latitude, lng: data.longitude })
+    }
+
+- _record_ is the record instance
+- _field_ is the field config
+- _data_ is the value from the data feed
+
+You can use `calculate` to convert a value from the feed, or to define a new record value.

package/resources/data/deck/training/p/2023-01-21T20-08-24-452Z.md

@@ -0,0 +1,15 @@
+A recod config contains a `fields:[]` that describes the record's fields.
+
+The field config can have these values:
+
+| Config Property | Description                                                        | 
+|-----------------|--------------------------------------------------------------------|
+|`name`           | Required. The name of the feed value.                              |
+|`type`           | Date/html/string                                                   |
+|`mapping`        | The path to feed property.                                         |
+|            |                                                                    |
+|`calculate`      | A function used to calculate the value of the field.               |
+|            |                                                                    |
+|`maxLength`      | Limits values to the specific length.                              |
+|`minLength`      | Limits values to the specific length.                              |
+|`nullable`       | Flags whether the value can be null/undefined.                     |