neo.mjs 6.9.9 → 6.9.11

package/resources/data/deck/training/p/2023-01-14T13-50-28-199Z.md

@@ -0,0 +1,19 @@
+The component base class introduces many important properties.
+
+- `html:string` — for simple content or placeholder text
+
+
+- `height`, `minHeight`, `maxHeight`
+- `width`, `minWidth`, `maxWidth`
+
+- `style:{}` — sometimes convenient, although using css styles via `cls` is probably better
+- `cls:[string]` — a array of CSS class strings
+
+- `disabled:boolean`
+
+- `_vdom` — for low-level content
+
+
+- `mounted:boolean` — useful for `afterSetMounted`
+
+There are also drag-and-drop hooks, and many other properties.

package/resources/data/deck/training/p/2023-01-14T13-59-20-275Z.md

@@ -0,0 +1,6 @@
+Component also introduces a few events:
+
+- `focusEnter`
+- `focusChange`
+- `focusLeave`
+- `focusMove`

package/resources/data/deck/training/p/2023-01-14T14-03-29-456Z.md

@@ -0,0 +1,3 @@
+- `up(config)` — Finds a parent container using `Neo.find()` syntax
+
+- `addCls(str)`, `removeCls(str)`, `toggleCls(str)` 

package/resources/data/deck/training/p/2023-01-14T14-27-57-678Z.md

@@ -0,0 +1,7 @@
+You've seen that get/set properties (using the underscore suffix)
+have `afterSet...` methods.
+
+Recall that `Neo.component.Base` introduces some key properties. 
+Since these properties have `afterSet` methods, you can easily
+"detect" when those properties change by overriding the corresponding `afterSet`
+method.

package/resources/data/deck/training/p/2023-01-14T17-30-18-228Z.md

@@ -0,0 +1,33 @@
+To conditionally call the ancestor for `afterSet...` methods.<small><sup>*</sup></small>
+use the _optional chaining_ operator.
+
+    super.afterSetBar?.(value, oldValue);
+
+<pre class="runnable readonly text 280">
+class Simple extends Base {
+    static getConfig() {
+        return {
+            className: 'ComponentBasics.view.component.Simple',
+
+            bar_: null, // A get/set field
+
+        }
+    }
+    afterSetBar(value, oldValue) {
+        // Do important processing here.
+    }
+}
+</pre>
+
+<pre class="runnable readonly text 140">
+class ExtendsSimple extends Simple {
+    afterSetBar(value, oldValue) {
+        super.afterSetBar?.(value, oldValue);
+        // Do important processing here.
+    }
+}
+</pre>
+<br>
+<small>* The framework doesn't actually create the `beforeSet...`, 
+`afterSet...`, and `beforeGet...` methods. Instead, the framework
+conditionally calls the methods using the chaining operator.</small>

package/resources/data/deck/training/p/2023-01-14T18-28-39-316Z.md

@@ -0,0 +1 @@
+Used when the container has one item — the item fills the entire container.

package/resources/data/deck/training/p/2023-01-14T18-28-44-115Z.md

@@ -0,0 +1,4 @@
+Multiple child items, with one visible. The visible item
+fills the container.
+
+To change the visible item assign a value to `this.layout.activeIndex` 

package/resources/data/deck/training/p/2023-01-14T18-28-49-548Z.md

@@ -0,0 +1,18 @@
+    layout:{
+        ntype: 'vbox',
+        pack: 'start', // 'start', 'center', 'end', null
+        align: 'start', // 'start', 'center', 'end', 'stretch', null
+    }
+
+The _pack_ config species how items are packed on the major
+axis. 
+- _start_ — items at the top
+- _center_ — items at the top-to-bottom middle 
+- _end_ — items at the end
+
+The _align_ config specifies how items are justified on the minor
+axis. 
+- _start_ — items are left justified
+- _center_ — items ae center justified 
+- _end_ — items are right justified
+- _stretch_ — items take up the full width

package/resources/data/deck/training/p/2023-01-14T18-40-13-758Z.md

@@ -0,0 +1,10 @@
+Uses CSS flexbox. 
+
+    style: {
+        overflow: 'scroll', // For the container
+        alignContent: 'flex-start', // For the flexbox
+    },
+    layout: {
+        ntype: 'flexbox',
+        wrap: 'wrap', // nowrap, wrap, wrapreverse
+    },

package/resources/data/deck/training/p/2023-01-14T19-29-15-291Z.md

@@ -0,0 +1,12 @@
+The `style` config takes an object, with the names
+being a camel-case version of the style you're specifying.
+
+    style: { 
+        backgroundColor: 'red',
+        fontSize: '2em',
+    },
+
+
+The kinds of things you'd use style for should be done as CSS classes,
+but using `style:{}` might be handy until you get around to coding
+the CSS.

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
+    }