neo.mjs 6.12.1 → 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/{p → pages}/Config.md

@@ -1,7 +1,13 @@
+## Introduction 
+
 As you've probably noticed, Neo.mjs classes have a `static config` property. 
 
-The `config` specifies properties that are applied to instances as they are
-created. In addition, Neo.mjs uses that information to set up propoerty lifecycle 
+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. 
+
+## 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:
@@ -10,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';
@@ -24,7 +33,7 @@ class Simple extends Component {
     }
 
 }
-Neo.applyClassConfig(Simple);
+Neo.setupClass(Simple);
 
 
 class MainView extends Container {
@@ -41,15 +50,14 @@ class MainView extends Container {
 
     }
 }
-Neo.applyClassConfig(MainView);
+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
-updated or accessed. You're free to implment the methods to implement business rules, normalize
+updated or accessed. You're free to implment these methods to provide business rules, normalize
 values, or have side-effects, such as updating a view or firing an event.
 
 <pre data-neo>
@@ -65,20 +73,18 @@ class Simple extends Component {
 
     }
 
-    beforeGetBar(){
-
+    beforeGetBar(value){
+        return value; // Return whatever you want here. 
     }
     beforeSetBar(value, oldValue){
-        // Use value if it's not empty
-        if (value) return value; 
+        if (value) return value;  // Use value if it's not empty
     }
     afterSetBar(value, oldValue){
         this.html = value;
-        this.fire('barChange', {component: this, value, oldValue});
     }
 
 }
-Neo.applyClassConfig(Simple);
+Neo.setupClass(Simple);
 
 
 class MainView extends Container {
@@ -95,14 +101,17 @@ class MainView extends Container {
 
     }
 }
-Neo.applyClassConfig(MainView);
+Neo.setupClass(MainView);
 </pre>
 
-This time if you run the code you'll "hi there" in the view. That's because the Simple instance is
+This time if you run the code you'll see "hi there" in the view. That's because the Simple instance is
 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.
 
-Updating a view is a common use case for the _afterSet_ method. It's also often used to fire an event. 
+## 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.
 
 <pre data-neo>
@@ -117,21 +126,13 @@ class Simple extends Component {
         bar_: null     // Another instance field -- note the underscore at the end
 
     }
-
-    beforeGetBar(){
-
-    }
-    beforeSetBar(value, oldValue){
-        // Use value if it's not empty
-        if (value) return value; 
-    }
     afterSetBar(value, oldValue){
         this.html = value;
         this.fire('barChange', {component: this, value, oldValue});
     }
 
 }
-Neo.applyClassConfig(Simple);
+Neo.setupClass(Simple);
 
 
 class MainView extends Container {
@@ -152,6 +153,6 @@ class MainView extends Container {
 
     }
 }
-Neo.applyClassConfig(MainView);
+Neo.setupClass(MainView);
 </pre>
 

package/resources/data/deck/learnneo/{p → 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. 
 
@@ -7,23 +9,29 @@ For example, if you wanted to create a button, you'd look in the API docs and se
 have a few key configs, including `text` and `iconCls`. The configs are properties you can 
 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 Base from '../../../../src/container/Base.mjs';
-import Button from '../../../../src/button/Base.mjs';
-class MainView extends Base {
+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'},
-        items : [{
-            module: Button,
-            text  : 'Home',
-            iconCls: 'fa fa-home'
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'start'},
+        items    : [{
+            module : Button,
+            iconCls: 'fa fa-home',
+            text   : 'Home'
         }]
     }
 }
-Neo.applyClassConfig(MainView);
+
+Neo.setupClass(MainView);
 </pre>
 
+
 The button config is just an object describing the button being created. In the example, it has three
 properties:
 
@@ -38,25 +46,29 @@ 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 Base from '../../../../src/container/Base.mjs';
-import Button from '../../../../src/button/Base.mjs';
-class MainView extends Base {
+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,
-            text  : 'Home',
-            iconCls: 'fa fa-home'
-        },{
-            module: Button,
-            text  : 'Star',
-            iconCls: 'fa fa-star'
+        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.applyClassConfig(MainView);
+
+Neo.setupClass(MainView);
 </pre>
 
 If you run the example you'll see two buttons, arranged according to the `layout`. If you'd like, 
@@ -64,4 +76,4 @@ modify the code to specify `ntype:'hbox'` and run it again.
 
 Note that the layout specifies `ntype` rather than `module`. An `ntype` is an alias for a class
 that has already been imported. Containers import all the layout types, so since we've already
-imported container we can simply use `ntype` to specify which layout we want.
+imported container we can simply use `ntype` to specify which layout we want.