neo.mjs 6.13.0 → 6.14.0

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

@@ -0,0 +1,180 @@
+## Introduction
+
+Neo.mjs views are made up of components and containers. 
+
+A component is a visual widget, such as a button, label, or text field. A container is a visual 
+collection of components.
+
+`Neo.component.Base` is the base class for all components. It introduces some common features, such as
+event handling, binding, and some life-cycle methods.
+
+`Neo.container.Base` is the base class for all containers. Containers are also components.
+
+## Neo.container.Base
+
+Containers are commonly used, although there are many specialized sub-classes, such as panels and toolbars.
+
+
+Containers have two key properties: 
+
+- `items`, which are the components within the container, and 
+- `layout`, which describes how the items are arranged
+
+## Neo.component.Base
+
+The component base class introduces common component features, but is rarely used itself because it's so
+primitive. Components introduce various properties, such as `width`, `height`, `cls` (to specify CSS classes for the component).
+
+Here's a container, with one child item.
+
+<pre data-neo>
+import Container from '../../../../src/container/Base.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'start'},
+        items    : [{
+            ntype : 'component', // Or module:Component
+            style : {border: 'thin solid red;'}, // Styling is usually done via "cls"
+            height: 100,
+            width : 200
+        }]
+    }
+}
+
+Neo.setupClass(MainView);
+</pre>
+
+Components also have an `html`. The `html` property is rarely used, and goes against the abstract philosophy of Neo.mjs, but
+sometimes it's handy as a placeholder as you stub out views.
+
+<pre data-neo>
+import Container from '../../../../src/container/Base.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'start'},
+        items    : [{
+            ntype : 'component', // Or module:Component
+            style : {border: 'thin solid red;'}, // Styling is usually done via "cls"
+            html  : 'This is a placeholder for a more sophisticated component we\'ll add later.',
+            height: 100,
+            width : 200
+        }]
+    }
+}
+
+Neo.setupClass(MainView);
+</pre>
+
+
+## Layout
+
+The `layout` config specifies how components are arranged within a container. Here are examples of 
+some commonly-used layouts.
+
+### Fit layout
+
+Fix is used when there's a single child. The component is sized to fit the container.
+
+<pre data-neo>
+import Container from '../../../../src/container/Base.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : 'fit', // If no configs are needed, simply use the ntype of the layout
+        items    : [{
+            ntype: 'component',
+            style: {backgroundColor: 'lightgreen'}, // The camel-cased property converts to the hyphenated css style
+        }]
+    }
+}
+
+Neo.setupClass(MainView);
+</pre>
+
+### Vbox and hbox
+
+Items are arranged vertically or horizontally. On-axis and off-axis alignment can be specified.
+
+<pre data-neo>
+import Button    from '../../../../src/button/Base.mjs';
+import Container from '../../../../src/container/Base.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'start'}, // Change the ntype to 'hbox'
+        items    : [{
+            module : Button,
+            iconCls: 'fa fa-home',
+            text   : 'Home'
+        }, {
+            module : Button,
+            iconCls: 'fa fa-star',
+            text   : 'Star'
+        }]
+    }
+}
+
+Neo.setupClass(MainView);
+</pre>
+
+### Card
+
+Having multiple child items, one of which is visible. 
+
+<pre data-neo>
+import Button    from '../../../../src/button/Base.mjs';
+import Base from '../../../../src/container/Base.mjs';
+
+class MainView extends Base {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : 'vbox',
+        items    : [{
+            ntype: 'toolbar',
+            dock : 'top',
+            items: [{
+                ntype: 'button',
+                text: 'Click me to cycle through the cards',
+                ui: 'ghost',
+                iconCls: 'fa fa-chevron-right',
+                iconPosition: 'right',
+                handler: data => {
+                    const container = data.component.up('container').getReference('cardContainer');
+                    container.layout.activeIndex = (container.layout.activeIndex +1) % container.items.length;
+                }
+            }]
+        }, {
+            ntype: 'container',
+            reference: 'cardContainer',
+            layout: 'card',
+            flex: 1,
+            items: [{
+                ntype : 'component',
+                style: {backgroundColor: 'lightsalmon'}, // The camel-cased property converts to the hyphated css style
+            }, {
+                ntype : 'component',
+                style: {backgroundColor: 'darkseagreen'} // https://drafts.csswg.org/css-color/#named-colors
+            }, {
+                ntype : 'component',
+                style: {backgroundColor: 'cornflowerblue'} // Who came up with these names?
+            }]
+        }]
+    }
+}
+
+Neo.setupClass(MainView);
+</pre>
+
+
+
+
+## Reusing containers
+
+
+## Lifecycle methods

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

@@ -1,9 +1,13 @@
+## Introduction 
+
 As you've probably noticed, Neo.mjs classes have a `static config` property. 
 
 The config describes properties you can specify as you create an instance of the class.
 Any config in the class, or its ancestors, can be specified. 
 
-In addition, Neo.mjs uses that information to set up propoerty lifecycle 
+## Simple properties and lifecycle properties
+
+In addition, Neo.mjs uses that information to set up property lifecycle 
 methods.
 
 Here's an example of a new component class `Simple` with three config properties:
@@ -12,6 +16,9 @@ Here's an example of a new component class `Simple` with three config properties
 2. `foo` — an instance property 
 2. `bar_` — another instance property 
 
+The `Simple` class introduces syntax. It doesn't have any content, so if you run the code you won't 
+see anything. We'll change that in the next example.
+
 <pre data-neo>
 import Component  from '../../../../src/component/Base.mjs';
 import Container  from '../../../../src/container/Base.mjs';
@@ -46,8 +53,7 @@ class MainView extends Container {
 Neo.setupClass(MainView);
 </pre>
 
-The `Simple` class doesn't have any content, so if you run the code you won't see anything. We'll 
-change that in the next example.
+## Detecting when a value changes
 
 Note that the `bar` property is defined with an underscore at the end. That tags the property as
 a _lifecyle property_. A lifecycle property provides methods that are run as the property is
@@ -75,7 +81,6 @@ class Simple extends Component {
     }
     afterSetBar(value, oldValue){
         this.html = value;
-        this.fire('barChange', {component: this, value, oldValue});
     }
 
 }
@@ -103,6 +108,8 @@ This time if you run the code you'll see "hi there" in the view. That's because
 configured with `bar: 'hi there'`, and since that's a lifecycle property the `afterSetBar()` method
 is run. That method updates the view with the passed value.
 
+## Firing an event when a value changes
+
 Typically, the _afterSet_ method is used to update a view or to fire an event.
 
 Look at this code: `afterSetBar()` fires an event, and the config in the `items[]` is listening to it.

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

@@ -1,3 +1,5 @@
+## Introduction 
+
 A Neo.mjs view is comprised of components and containers. A component is a visual widget, like a button,
 and a container is a visual collection of components. 
 
@@ -8,6 +10,8 @@ have a few key configs, including `text` and `iconCls`. The configs are properti
 use to describe the component you're creating> You can also access or set the properties dynamically.
 
 
+## A view with one component
+
 <pre data-neo>
 import Button    from '../../../../src/button/Base.mjs';
 import Container from '../../../../src/container/Base.mjs';
@@ -42,6 +46,8 @@ Containers also have a `layout` property, which describes how the items are arra
 
 Let's put a second button in the container.
 
+## A view with two components
+
 <pre data-neo>
 import Button    from '../../../../src/button/Base.mjs';
 import Container from '../../../../src/container/Base.mjs';

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

@@ -120,7 +120,7 @@ As you can see, `MicroLoader.mjs` runs `Main.mjs`, which in turn spawns the thre
 - `neomjs-app-worker` is where app logic is run
 
 Neo.mjs apps run in multiple webworkers, and each webworker is run in a separate parallel thread.  
-Parallel processing — along wih the efficient way the `neomjs-vdom-worker` applies delta updates — is why Neo.mjs applications run so fast. 
+Parallel processing — along wih the efficient way the vdom worker applies delta updates — is why Neo.mjs applications run so fast. 
 
 ##Commonly-used Scripts
 
@@ -294,7 +294,7 @@ layout: {
 
 ## Debugging
 
-At startup a Neo.mjs application launches three Web Workers:
+At startup, a Neo.mjs application launches three Web Workers:
 
 - neomjs-app-worker
 - neomjs-data-worker
@@ -1153,7 +1153,7 @@ and each class is simpler than using complex source files that try to configure
 
 <!-- /lab -->
 
-### Google Maps Add-on
+## Google Maps Add-on
 
 Neo.mjs has a Google Map component. This component is a little different than a button or table, 
 becauase it's implemented as a _main thread add-on_. 
@@ -1169,14 +1169,10 @@ to also provide a wrapper class so it can be used like any other component withi
 Maps is implemented: there's a main-thread add-on and a corresponding Neo.mjs component. The add-on is 
 specified in _neo-config.json_, and the component is imported and used like any other component.
 
-Ultimately, normal components are responsible for specifying how 
-they're rendered (which is usually handled by Neo.mjs).
-
 How do you specify which main-thread add-ons you want? If you recall the script you used to create the starter
 app, it has a step that asks what add-ons you want. That results in populating the `mainThreadAddons` property
-in `neo-config.json`. We didn't choose Google Maps when we ran the script, but we need it. That means we
-need to edit `neo-config.json` and add it. Google Maps also requires an API key, which is also configured in
-`neo-config.json`.
+in `neo-config.json`. We didn't choose Google Maps when we ran the script, but we need it, which means we'll
+need to edit `neo-config.json`. Google Maps also requires an API key, which is also configured there.
 
 The Google Maps component has a few key configs:
 
@@ -1193,6 +1189,20 @@ Marker store records are required to have these properties:
 
 <!-- lab -->
 
+<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>
 
@@ -1215,6 +1225,10 @@ Edit `apps/earthquakes/neo-config.json` and add entries for the Google Maps add-
 }
 </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>
@@ -1406,3 +1420,16 @@ Save, refresh, and confirm that you see the value logged when you click on a map
 
 
 <!-- /lab -->
+
+## Summary
+
+Congratulations on completing the tutorial! 
+
+The goals was to give you hands-on coding a simple app to let you get a feel for syntax
+and to introduce some basic Neo.mjs concepts
+
+- Declarative, abstract code
+- Class-based coding, and the ability to extend any class, such as `view/earthquakes/Table.mjs`
+- View models, to share properties and objects, such as the store shared by the table and map
+- Events, specified via `listeners:{}`
+- Controllers, to hold event listeners and other procedural logic

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

@@ -1,3 +1,5 @@
+## Introduction
+
 All components fire events. For example, form fields fire a `change` event, various 
 focus events, and others. Some other types fire events too, such as `Neo.data.Store`, 
 which fires a `load` event after the store is loaded with data.
@@ -5,34 +7,35 @@ which fires a `load` event after the store is loaded with data.
 Some terminology related to events is that events are _fired_, and as a result, some 
 event _handler_ — or _listener_ — is run.
 
+## Listeners
+
 To specify an event handler, use `listeners: {}`, specifying in as many event/handler
 pairs as you need. 
 
 The code below shows two text fields, with `listeners` for `change` and `focusEnter`.
-(The events for any component are documened in the API docs.)
+(The events for any component are documented in the API docs.)
 
 <pre data-neo>
-import Base from '../../../../src/container/Base.mjs';
+import Container from '../../../../src/container/Base.mjs';
 import TextField from '../../../../src/form/field/Text.mjs';
-class MainView extends Base {
+
+class MainView extends Container {
     static config = {
-        className : 'Example.view.MainView',
-        layout: {ntype:'vbox', align:'start'},
-        items : [{
-            module: TextField,
-            labelText  : 'First name',
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'start'},
+
+        itemDefaults: {
+            module   : TextField,
             listeners: {
-                change: data => Neo.Main.log({value:data.value}),
+                change    : data => Neo.Main.log({value:data.value}),
                 focusEnter: data => Neo.Main.log({value: `Entering ${data.component.labelText}`}) 
             }
         },
-        {
-            module: TextField,
-            labelText  : 'Last name',
-            listeners: {
-                change: data => Neo.Main.log({value: data.value}),
-                focusEnter: data => Neo.Main.log({value: `Entering ${data.component.labelText}`}) 
-            }
+
+        items: [{
+            labelText: 'First name'
+        }, {
+            labelText: 'Last name'
         }]
     }
 }
@@ -42,37 +45,39 @@ Neo.setupClass(MainView);
 If you run the example, and open the browser's debugger, you'll see the console being logged as you type or give
 focus to either field.
 
+## In-line or separated into a controller
+
 Note that the handlers specify an in-line function. For trivial cases, that might be ok. But normally
 you'd want better separation of concerns by placing those event handlers in a separate class. Neo.mjs provides
 that with a _component controller_. 
 
 A `Neo.controller.Component` is a simple class associated with a component class. As a view is created, an 
-instance of its associated contoller is automatically created. 
+instance of its associated controller is automatically created. 
 
 <pre data-neo>
-import Base        from  '../../../../src/container/Base.mjs';
-import Controller  from  '../../../../src/controller/Component.mjs';
-import TextField  from   '../../../../src/form/field/Text.mjs';
+import Container  from '../../../../src/container/Base.mjs';
+import Controller from '../../../../src/controller/Component.mjs';
+import TextField  from  '../../../../src/form/field/Text.mjs';
 
 class MainViewController extends Controller {
     static config = {
         className: 'Example.view.MainViewController'
     }
-    onChange(data){
-        console.log(data.value);
+    onChange(data) {
+        Neo.Main.log({value: data.value})
     }
 }
 Neo.setupClass(MainViewController);
 
 
-class MainView extends Base {
+class MainView extends Container {
     static config = {
         className : 'Example.view.MainView',
         controller: MainViewController,
-        layout: {ntype:'vbox', align:'start'},
-        items : [{
-            module: TextField,
-            labelText  : 'Name',
+        layout    : {ntype:'vbox', align:'start'},
+        items     : [{
+            module   : TextField,
+            labelText: 'Name',
             listeners: {
                 change: 'onChange'
             }
@@ -88,12 +93,16 @@ to make it easier to see the source code for every class being used. But in an
 actual applications the controller class would be coded in its own source file &mdash; named something
 like `MainViewController.mjs` &mdash; and that would be imported into the view.)
 
+## Neo.core.Observable
+
 The ability to fire events and add listeners is provided by `Neo.core.Observable`, which is mixed into 
 classes that need that ability. All components are observable, `Neo.data.Store` is observable, and some
 others. `Neo.core.Observable` introduces a few methods and properties, such as `listeners`, which
 is used in the examples above, `on()` for procedurally adding an event listener, and `fire()`, which is 
 how you fire events in the custom classes you create.
 
+## Firing an event when a value changes
+
 Here's example illustrating how `fire()` is used. The code defines a `ToggleButton`
 class, which is just a button with a `checked` property: the button shows a checked or unchecked
 checkbox depending on the value of `checked`. 
@@ -103,37 +112,40 @@ We'll discuss that at length later, but in a nutshell, config properties ending
 automatically get lifecycle methods run before the value is assigned, after the value is assigned, and 
 before the value is accessed. We're using the _after_ method to fire a `change` event.
 
+
 <pre data-neo>
-import Base        from  '../../../../src/container/Base.mjs';
-import Button  from  '../../../../src/button/Base.mjs';
-import TextField  from   '../../../../src/form/field/Text.mjs';
+import Button    from '../../../../src/button/Base.mjs';
+import Container from '../../../../src/container/Base.mjs';
 
 class ToggleButton extends Button {
     static config = {
         className: 'Example.view.ToggleButton',
-        checked_: false
+        checked_ : false
     }
-    afterSetChecked(checked){
-        this.iconCls = checked?'fa fa-square-check':'fa fa-square';
-        this.fire('change', {component: this, checked}); // This is where our custom event is being fired
+    afterSetChecked(checked) {
+        this.iconCls = checked ? 'fa fa-square-check' : 'fa fa-square';
+        
+        // This is where our custom event is being fired
+        this.fire('change', {component: this, checked})
     }
-    onClick(data){
+    onClick(data) {
         super.onClick(data); 
-        this.checked = !this.checked;      
+        this.checked = !this.checked
     }
 }
 Neo.setupClass(ToggleButton);
 
 
-class MainView extends Base {
+class MainView extends Container {
     static config = {
-        className : 'Example.view.MainView',
-        layout: {ntype:'vbox', align:'start'},
-        items : [{
-            module: ToggleButton,
-            text: 'Toggle',
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'start'},
+        items    : [{
+            module   : ToggleButton,
+            text     : 'Toggle',
             listeners: {
-                change: data => console.log(data.checked) // Here, we're listening to the custom event
+                // Here, we're listening to the custom event
+                change: data => Neo.Main.log({value: data.checked})
             }
         }]
     }

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

@@ -1,12 +1,13 @@
 [Add content on listeners options here]
 
-How are events set up? We don't really care, but in case you're curious: Neo.mjs has a `Neo.core.Observable` class
-that can be mixed into any class. It maintains a `listeners` object map that's a key-value pair, where
-the key is the event name, and the value is an array of function references. The first time a listener is 
-added an entry is added to the map using the event name as the key, and the event handler added as the first
-item in the associated array. If another listener is added for the same event, a second item is added to the
-array. If a new event is added, a new entry is added. Etc. When the event is fired, Neo.mjs looks up the map
-entry for the event name, then runs each function in the array, passing whatever data is specified in the
-call to `fire()`.
+How are events set up? The details don't really matter, but in case you're curious: 
+Neo.mjs has a `Neo.core.Observable` class that can be mixed into any class. It maintains 
+a `listeners` object map that's a key-value pair, where the key is the event name, and 
+the value is an array of function references. The first time a listener is added, an 
+entry is added to the map using the event name as the key, and the event handler added 
+as the first item in the associated array. If another listener is added for the same 
+event, a second item is added to the array. If a new event is added, a new entry is 
+added. Etc. When the event is fired, Neo.mjs looks up the map entry for the event name, 
+then runs each function in the array, passing whatever data is specified in the call to `fire()`.
 
 <img style="width:80%" src="https://s3.amazonaws.com/mjs.neo.learning.images/gettingStarted/events/ObservableInMemory.png"></img>

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

@@ -1,3 +1,5 @@
+## Introduction
+
 Controllers often need to get references to components in order to update 
 the UI or access component properties. 
 There are two common ways of doing that:
@@ -5,11 +7,13 @@ There are two common ways of doing that:
 - Using the component references passed to the event handler
 - Tagging a component with a `reference` and using `this.getReference()` in the controller
 
+## References are usually passed to event handlers
+
 Here's an example with one button. Clicking on the button will disable it. 
 As you can see, the handler uses the component reference pass in via `data.component`.
 
 <pre data-neo>
-import Button     from '../../../../src/Button/Base.mjs';
+import Button     from '../../../../src/button/Base.mjs';
 import Container  from '../../../../src/container/Base.mjs';
 import Controller from '../../../../src/controller/Component.mjs';
 
@@ -39,12 +43,14 @@ class MainView extends Container {
 Neo.setupClass(MainView);
 </pre>
 
+## Using getReference() 
+
 But what if we need to get a reference to another component in the view? In that case
 you tag the component you need with a `reference` config, then use `getReference()` in
 the controller.
 
 <pre data-neo>
-import Button     from '../../../../src/Button/Base.mjs';
+import Button     from '../../../../src/button/Base.mjs';
 import Container  from '../../../../src/container/Base.mjs';
 import Controller from '../../../../src/controller/Component.mjs';
 
@@ -53,10 +59,10 @@ class MainViewController extends Controller {
         className: 'Example.view.MainViewController'
     }
     onDisableButtonClick(data){
-        data.component.disabled = true;
+        data.component.disabled = true
     }
     onEnableButtonClick(data){
-        this.getReference('myButton').disabled = false;
+        this.getReference('myButton').disabled = false
     }
 }
 Neo.setupClass(MainViewController);
@@ -82,6 +88,7 @@ class MainView extends Container {
 Neo.setupClass(MainView);
 </pre>
 
+## Getting a reference when debugging
 
 There are other ways of getting references, but these are either non-standard or for debugging.
 For example, components have an `up()` method, and containers have a `down()` method. These look 
@@ -98,7 +105,7 @@ The following example gets a reference to the _Learn_ button at the top of this
 Again &mdash; that use of `Neo.findFirst()` might be handy when debugging, but it should never be used in app logic.
 
 <pre data-neo>
-import Button    from '../../../../src/Button/Base.mjs';
+import Button    from '../../../../src/button/Base.mjs';
 import Container from '../../../../src/container/Base.mjs';
 
 class MainView extends Container {
@@ -110,14 +117,14 @@ class MainView extends Container {
             text   : 'Change Learn caption',
             handler: data=>{
                 const component = Neo.findFirst({text:'Learn'});
-                component?.set({text: 'Yikes!', ui: 'primary'});
+                component?.set({text: 'Yikes!', ui: 'primary'})
             }
         }, {
             module : Button,
             text   : 'Restore Learn caption',
             handler: data=>{
                 const component = Neo.findFirst({text:'Yikes!'});
-                component?.set({text: 'Learn', ui: 'ghost'});
+                component?.set({text: 'Learn', ui: 'ghost'})
             }
         }]
     }