neo.mjs 6.9.10 → 6.9.11

package/resources/data/deck/training/p/2022-12-29T20-37-20-344Z.md

@@ -0,0 +1,43 @@
+
+The code is also _declarative_ — it describes what you're creating.
+It's also an abstraction, because it describes _what's_ in the user interface,
+but not _how_ it's rendered.
+
+<pre class="runnable text readonly">
+import Component from '../../../node_modules/neo.mjs/src/component/Base.mjs';
+import TabContainer from '../../../node_modules/neo.mjs/src/tab/Container.mjs';
+import Viewport from '../../../node_modules/neo.mjs/src/container/Viewport.mjs';
+
+class MainContainer extends Viewport {
+    static config = {
+        className: 'Starter.view.MainContainer',
+        ntype: 'main',
+        autoMount: true,
+        style: { padding: '20px' },
+        layout: { ntype: 'fit' },
+        items: [{
+            module: TabContainer,
+            itemDefaults: {
+                module: Component,
+                cls: ['neo-examples-tab-component'],
+                style: { padding: '20px' }
+            },
+            items: [{
+                tabButtonConfig: {
+                    iconCls: 'fa fa-home',
+                    text: 'Tab 1'
+                },
+                vdom: { innerHTML: 'Welcome to your new Neo App.' }
+            }, {
+                tabButtonConfig: {
+                    iconCls: 'fa fa-play-circle',
+                    text: 'Tab 2'
+                },
+                vdom: { innerHTML: 'Have fun creating something awesome!' }
+            }]
+        }]
+    }
+}
+Neo.applyClassConfig(MainContainer);
+export default MainContainer;
+</pre>

package/resources/data/deck/training/p/2022-12-30T19-04-30-990Z.md

@@ -0,0 +1,8 @@
+Neo takes the _declarative_ approach, 
+where you configure high-level components. The details of rendering
+those to the run-time environment is handled by the framework (and 
+low-level code).
+
+Ultimately, components do need to translate into DOM and styling, and
+you may need to do that yourself occastionally, but
+Neo tries to make that the exception, rather than the rule.

package/resources/data/deck/training/p/2022-12-31T18-43-56-338Z.md

@@ -0,0 +1,7 @@
+<img style="float:left;margin-right:1em;" height="600" src="resources/images/intro/LookForSetters.png"/>
+
+Once you find the component, expand it and scroll down until you see the grayed-out 
+properties &mdash; those are the setter/getter properties.
+
+Choose whatever property you're interested in, and click on the ellipses. That
+runs the getter, and if you change the value you'll be running the setter. 

package/resources/data/deck/training/p/2022-12-31T18-51-50-682Z.md

@@ -0,0 +1 @@
+<img style="float:left;margin-right:1em;" height="600" src="resources/images/intro/ChangeText.png"/>

package/resources/data/deck/training/p/2022-12-31T18-54-04-176Z.md

@@ -0,0 +1,4 @@
+You can run methods too. And since there's no transpiling, anything you can put in your
+code will run on the command line.
+
+<img height="480" src="resources/images/intro/Add.png"/>

package/resources/data/deck/training/p/2022-12-31T22-11-55-555Z.md

@@ -0,0 +1,112 @@
+#Introduction
+
+In this lab, you'll generate a starter app, then modify it to use a table to
+show earthquakes in Iceland.
+
+#Steps
+
+??Create the application
+
+Use a terminal window to navidate to the root of your Neo project, and run the _create-app-training_
+scrip. Name the app _Earthquakes_. **Important:** Rather than taking all defaults, you _must_ choose the GoogleMaps main thread addon.
+
+    npm run create-app-training
+
+When you run the app you should get a runtime error telling you the api key is missing.
+
+    Google Maps JavaScript API warning: NoApiKeys
+
+??Add the Google Maps API key
+
+Edit `apps/earthquakes/neo-config.json` and add an entry for _googleMapsApiKey_.
+<pre style="color:lightgray;">
+{
+    "appPath": "../../apps/earthquakes/app.mjs",
+    "basePath": "../../",
+    "environment": "development",
+    "mainPath": "../node_modules/neo.mjs/src/Main.mjs",
+    "mainThreadAddons": [
+        "DragDrop",
+        "GoogleMaps",
+        "Stylesheet"
+    ],
+    <span style="font-weight:bold;color:blue">"googleMapsApiKey": "AIzaSyCRj-EPE3H7PCzZtYCmDzln6sj7uPCGohA",</span>
+    "workerBasePath": "../../node_modules/neo.mjs/src/worker/"
+}
+</pre>
+
+Refresh your browser window and you should see the starter app without any warnings.
+
+??Add the table and store to the `MainView` 
+
+Look the main view. It has an empty `items:[]`. Change it so it has one item, which
+is the config for a table and store
+
+<pre class="runnable readonly">
+{
+    module: Table,
+    flex: 1,
+    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,
+    },
+    columns: [{
+        dataField: "timestamp",
+        text: "Date",
+        renderer: (data) =>
+            data.value.toLocaleDateString(undefined, {
+                weekday: "long",
+                year: "numeric",
+                month: "long",
+                day: "numeric",
+            }),
+    }, {
+        dataField: "humanReadableLocation",
+        text: "Location",
+    }, {
+        dataField: "size",
+        text: "Magnitude",
+        align: "right",
+        width: 100,
+        renderer: (data) => data.value.toLocaleString(),
+    }],
+}
+</pre>
+
+If you were to save and refresh you'll get a runtime error 
+
+    ReferenceError: Table is not defined
+
+That's beause the new code references two classes: _Store_ and _Table_, and those haven't been imported. 
+
+??Add imports for `Store` and `Table`
+
+At the top of `MainView.mjs` add two imports:
+
+    import Table from "../../../node_modules/neo.mjs/src/table/Container.mjs";
+    import Store from "../../../node_modules/neo.mjs/src/data/Store.mjs";
+
+Save and refresh and the app should run.

package/resources/data/deck/training/p/2022-12-31T23-00-41-222Z.md

@@ -0,0 +1,6 @@
+Let's create another starter, but do something more sophisticated: We'll call
+a web service that returns information on earthquakes in Iceland, and show 
+that information in a table.
+
+Then we'll enhance and refactor the application to showcase some basic principles of Neo.
+

package/resources/data/deck/training/p/2022-12-31T23-18-55-655Z.md

@@ -0,0 +1,69 @@
+#Introduction
+
+In this lab, you'll refactor the app, making the table its own class, adding the map,
+
+
+#Steps
+
+??Move the table into its own class
+
+Create a new file named `apps/earthquakes/view/earthquakes/Table.mjs` with this content.
+
+<pre class="runnable text readonly">
+import Base from '../../../../node_modules/neo.mjs/src/table/Container.mjs';
+
+class Table extends Base {
+    static config = {
+        className: 'Earthquakes.view.earthquakes.Table',
+        ntype: 'earthquakes-table',
+        columns: [{
+            dataField: 'timestamp',
+            text: 'Date',
+            flex: 1,
+            renderer: data => data.value.toLocaleDateString(undefined, {weekday: 'long', year: 'numeric', month: 'long', day: 'numeric'})
+        }, {
+            dataField: 'humanReadableLocation',
+            text: 'Location',
+            flex: 1,
+        }, {
+            dataField: 'size',
+            text: 'Magnitude',
+            align: 'right',
+            flex: 1,
+            renderer: data => data.value.toLocaleString()
+        }]
+    }
+}
+
+Neo.applyClassConfig(Table);
+export default Table;
+</pre>
+
+??Review the code
+
+What's in the code? 
+
+- The class extends `Neo.table.Container`
+- It has an `ntype`, which we can use when creating an instance, or when debugging
+- Each column has `text` and `dataField` configs, and some have renderers
+
+??Use the new component
+
+Edit `apps/earthquakes/view/MainView` and look for the config block for the table. 
+
+- Import the new class: `import EarthquakesTable from './earthquakes/Table.mjs';`
+- Replace the `module: Table` with `module: EarthquakesTable`
+- Remove the `columns:[]` config
+- Leave the `store` config alone
+
+Save and refresh the browser, and your app should run as before. 
+
+You can confim that the  new class _is being loaded_ by using DevTools to try to open `earthquakes/Table` &mdash; if it
+was imported, it'll be listed.
+
+You can conrim that an instance _was created_ by using the DevTools console and searching for it via
+
+    Neo.first('earthquakes-table')
+
+That will return a component reference if there's a match.
+

package/resources/data/deck/training/p/2022-12-31T23-25-40-735Z.md

@@ -0,0 +1,21 @@
+Neo comes with a Google maps wrapper. Its key properties are:
+
+
+##center
+
+    {lat: 1.1234, lng:23.4456}
+
+<br>
+
+##markerStore
+
+A store whose records contain
+
+    {title: 'String', location:{lat: 1.1234, lng:23.4456}}
+
+<br>
+
+
+##zoom
+
+The Google Maps zoom level. It defaults to 8. 

package/resources/data/deck/training/p/2022-12-31T23-25-51-014Z.md

@@ -0,0 +1,7 @@
+`Neo.core.Base` is the Neo base class. It mixes in `Neo.core.Observable`.
+This means all Neo classes have the ability to fire events or configure
+event listeners.
+
+The API docs have an _events_ section for each class. 
+
+Tables fire a _select_ event. Google Maps components fire a _markerClick_ event

package/resources/data/deck/training/p/2023-01-01T17-49-18-429Z.md

@@ -0,0 +1,3 @@
+We can use DevTools and our debugging skills to inspect the store.
+
+<img height="400" src="resources/images/intro/InspectTheStore.png"/>

package/resources/data/deck/training/p/2023-01-01T18-44-07-034Z.md

@@ -0,0 +1,34 @@
+<pre class="runnable text readonly">
+import Base from '../../../../node_modules/neo.mjs/src/table/Container.mjs';
+
+class Table extends Base {
+    static config = {
+        className: 'Earthquakes.view.earthquakes.Table',
+        ntype: 'earthquakes-table',
+        columns: [{
+            dataField: 'timestamp',
+            text: 'Date',
+            flex: 1,
+            renderer: data => data.value.toLocaleDateString(undefined, { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' })
+        }, {
+            dataField: 'humanReadableLocation',
+            text: 'Location',
+            flex: 1,
+        }, {
+            dataField: 'size',
+            text: 'Magnitude',
+            align: 'right',
+            flex: 1,
+            // width: 100,
+            renderer: data => data.value.toLocaleString()
+        }]
+    }
+}
+
+Neo.applyClassConfig(Table);
+export default Table;
+
+</pre>
+
+Why isn't the store there? Because typically, the code _creating_ the table
+is responsible for providing the store.

package/resources/data/deck/training/p/2023-01-01T18-47-39-766Z.md

@@ -0,0 +1,15 @@
+Let's enhance the app to use a Google Map to show where the earthquakes occurred.
+
+<pre style="font-size:1.6em;">
+import GoogleMapsComponent from '../../../node_modules/neo.mjs/src/component/wrapper/GoogleMaps.mjs';
+...
+{
+    module: GoogleMapsComponent,
+    flex: 1,
+    center: {
+        lat: 64.8014187,
+        lng: -18.3096357
+    },
+    zoom: 6,
+}
+</pre>

package/resources/data/deck/training/p/2023-01-01T19-04-22-830Z.md

@@ -0,0 +1,4 @@
+But this design has a problem: even though the table is nicely
+reusable, the stores are duplicated. 
+
+Duplicating the store config is poor reuse and higher maintenance, and fetching the data twice is inefficient.

package/resources/data/deck/training/p/2023-01-01T21-11-58-025Z.md

@@ -0,0 +1,25 @@
+Configs can hold simple instance properties.
+
+<pre class="runnable readonly text">
+class Simple extends Base {
+    static config = {
+        className: 'Demo.view.component.Simple',
+        ntype: 'demo-simple-component',
+
+        foo: 1, // An instance field
+
+    }
+}
+...
+items: [{
+    module: Simple
+
+    tabButtonConfig: {iconCls: 'fa fa-home', text: 'Simple'},
+
+}, {
+    module: Simple
+    foo: 2, // This value is used for the instance
+
+    tabButtonConfig: {iconCls: 'fa fa-home', text: 'Simple'},
+}],
+</pre>

package/resources/data/deck/training/p/2023-01-01T21-12-37-340Z.md

@@ -0,0 +1,23 @@
+You can create get/set properties by using the underscore suffix.
+
+<pre class="runnable readonly text 300">
+class Simple extends Base {
+    static getConfig() {
+        return {
+            className: 'Demo.view.component.Simple',
+            ntype: 'demo-simple-component',
+
+            foo: 1, // An instance field
+
+            bar_: null, // A get/set field with lifecycle hooks
+
+        }
+    }
+}
+</pre>
+
+In the debugger console this shows up as a get/set property.
+
+<pre style="color:gray;">
+    <span style="color:DarkOrchid">bar</span>: (...)
+</pre>

package/resources/data/deck/training/p/2023-01-01T21-13-13-880Z.md

@@ -0,0 +1,8 @@
+When you use the underscore suffix, Neo generates the get/set, and it also generates
+lifecycle methods that let you intervene as the property is accessed or set.
+
+For example, if you define the property `foo_`, Neo will generate these methods.
+
+- `beforeSetFoo(value, oldValue)` — returns the value to be used for the set
+- `afterSetFoo(value, oldValue)`
+- `beforeGetFoo(value)` — returns a value

package/resources/data/deck/training/p/2023-01-01T21-14-45-740Z.md

@@ -0,0 +1,98 @@
+#Introduction
+
+In this lab, you'll generate a starter app.
+
+#Steps
+
+<details>
+<summary>Create the application</summary>
+
+Use a terminal window to navigate to the root of your Neo workspace, 
+and run the following command. **Important:** Rather than taking all defaults, you _must_ choose the GoogleMaps option.
+
+    npm run create-app-training
+
+Name the app `Yelp`.
+
+If you run the app you'll get a runtime error telling you the api key is missing.
+You add the API key in the next step.
+
+    Google Maps JavaScript API warning: NoApiKeys
+
+??Add the Google Maps API key
+
+Edit `apps/yelp/neo-config.json` and add an entry for _googleMapsApiKey_.
+
+<pre style="color:lightgray;">
+{
+    "appPath": "../../apps/yelp/app.mjs",
+    "basePath": "../../",
+    "environment": "development",
+    "mainPath": "../node_modules/neo.mjs/src/Main.mjs",
+    "mainThreadAddons": [
+        "DragDrop",
+        "GoogleMaps",
+        "Stylesheet"
+    ],
+    <span style="font-weight:bold;color:limegreen">"googleMapsApiKey": "AIzaSyCRj-EPE3H7PCzZtYCmDzln6sj7uPCGohA",</span>
+    "workerBasePath": "../../node_modules/neo.mjs/src/worker/"
+}
+</pre>
+
+Refresh your browser window and you should see the starter app without any warnings.
+</details>
+
+<details>
+<summary>Change `MainView` to be a panel</summary>
+
+Replace the entire contents of `MainView` with this code. 
+
+<pre class="runnable readonly text">
+import Base from '../../../node_modules/neo.mjs/src/container/Panel.mjs';
+import Controller from './MainViewController.mjs';
+import ViewModel from './MainViewModel.mjs';
+
+class MainView extends Base {
+    static config = {
+        className: 'Junk.view.MainView',
+
+        controller: {module: Controller},
+        model: {module: ViewModel},
+
+        headers: [{
+            dock: 'top',
+            html: 'banner'
+        }, {
+            dock: 'top',
+            html: 'filter'
+        }, {
+            dock: 'right',
+            html: 'details',
+            width: 300
+        }],
+        items: [{
+            html: 'tab container'
+        }]
+    }
+}
+
+Neo.applyClassConfig(MainView);
+
+export default MainView;
+</pre>
+
+We'll learn about panels later, but in a nutshell, a panel is a container
+that has a special `headers:[]` config that lets you add components to the
+top, right, bottom, or left edges of the container.
+
+What does the code do?
+
+- Changes the view to be a panel
+- Adds three docked headers which are placeholders for classes you'll create
+    - The banner at the top
+    - The filter container at the top
+    - The business details container at the right
+
+Verify that the app runs.
+
+</details>

package/resources/data/deck/training/p/2023-01-01T21-18-23-886Z.md

@@ -0,0 +1,26 @@
+<pre class="runnable readonly text 480">
+{
+    ntype : 'container',
+    style: {
+        marginTop: '30px'
+    },
+
+    layout: {
+        ntype: 'vbox',
+        align: 'start'
+    },
+
+    items: [{
+        module       : Button,
+        iconCls     : 'fa fa-home',
+        iconPosition: 'right',
+        text        : 'Right'
+    }, {
+        ntype       : 'button',
+        flex        : 1,
+        iconCls     : 'fa fa-play-circle',
+        iconPosition: 'bottom',
+        text        : 'Bottom'
+    }, SomeClass]
+}
+</pre>

package/resources/data/deck/training/p/2023-01-01T21-18-31-316Z.md

@@ -0,0 +1,19 @@
+`itemDefaults:{}` specifies an item config used for every item in 
+`items:[]`. Individual items are free to set their own values.
+
+<pre class="runnable readonly text 300">
+itemDefaults: {
+    module: Button,
+    handler: 'onButtonClick',
+    flex: 1
+},
+items: [{
+    style: { backgroundColor: 'red' },
+}, {
+    style: { backgroundColor: 'yellow' },
+}, {
+    style: { backgroundColor: 'lightblue' },
+}, {
+    module: Label // This is used instead of the default
+}]
+</pre>

package/resources/data/deck/training/p/2023-01-01T21-18-42-290Z.md

@@ -0,0 +1,23 @@
+Items are arranged according to a `layout`.
+
+- `layout:'fit'` 
+- `layout: 'card'`
+- `layout: 'vbox'`
+- `layout: 'hbox'`
+- `layout: 'flexbox'`
+
+When you need to provide more config details, use this form:
+
+    layout: {
+        ntype:'vbox',
+        align: 'stretch'
+    }
+
+
+The container base class imports all layouts, which means you
+can use `ntype` (and don't need to explicitly import the layout class).
+
+<span style="color: #bbbbbb;">And actually, in the case of layouts, you
+<i style="color: #bbbbbb;">must</i> use ntype. You do not specify layouts 
+using the <tt>module</tt> config.
+</span>

package/resources/data/deck/training/p/2023-01-01T21-19-57-020Z.md

@@ -0,0 +1,24 @@
+You can procedurally add or remove items.
+
+- `insert(index, item, [silent])`
+- `remove(component, [destroyItem], [silent])`
+- `removeAt(index, [destroyItem], [silent])`
+
+
+
+<pre class="runnable readonly text 100">
+this.add({
+    module: Button,
+    text: 'New Button'
+});
+</pre>
+
+<pre class="runnable readonly text 160">
+this.add([{
+    module: Button,
+    text: 'One'
+}, {
+    module: Button,
+    text: 'Two'
+}]);
+</pre>

package/resources/data/deck/training/p/2023-01-01T21-22-31-184Z.md

@@ -0,0 +1,13 @@
+Components and other classes fire _events_. Those events run a callback
+function called the event _listener_ or _handler_.
+
+For example, buttons fire _click_ events, tables
+fire  _select_ events, and stores fire _load_ events.
+
+The usual way to configure to an event is with the `listeners` config. 
+
+    listeners: {
+        select: 'onTableSelect'
+    },
+
+

package/resources/data/deck/training/p/2023-01-01T21-22-38-317Z.md

@@ -0,0 +1,17 @@
+The _listeners_ object is a name value pair, where the name is the 
+name of the event, and the value is either a function or the string
+name of the function in the view's controller (or controllers up the
+containment hierarchy). 
+
+    listeners: {
+        change: data=>console.log(data),
+        focusChange: data=>console.log(data)
+    },
+
+
+    listeners: {
+        change: 'onChange',
+        focusChange: 'onFocusChange'
+    },
+
+

package/resources/data/deck/training/p/2023-01-01T21-22-47-693Z.md

@@ -0,0 +1,20 @@
+You can also add listeners procedurally.
+
+<pre style="font-size: 14pt">
+this.getReference('mycomp').addListener(string, function);
+</pre>
+
+The string is the name of the event, the function is the callback function.
+
+The callback function could be an in-line function, or a reference to a function.
+
+
+<pre style="font-size: 14pt">
+this.getReference('mycomp').addListener('change', data=>console.log(data));
+</pre>
+
+
+
+<pre style="font-size: 14pt">
+this.getReference('mycomp').addListener('change', this.onChange.bind(this));
+</pre>