neo.mjs 6.10.9 → 6.10.11

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

@@ -0,0 +1,214 @@
+##Introduction 
+
+In this topic you'll create an application that fetches data on earthquakes in Iceland,
+and show the information in two views: a table, and a map.
+
+You'll do this in a series of labs:
+
+1. Generate a workspace
+1. Generate a starter app
+1. Learn some debugging tricks
+1. Generate the earthquakes starter app
+1. Refactor a config into its own class
+1. Add a map
+1. Listen to events
+1. Make the app multi-window
+
+##Advice
+
+A word of advice: Keep a high-level perspective, especially early on. Throughout this
+tutorial, and others, We'll have plenty of time to get into the code, and we'll do 
+most things multiple times. 
+
+##Lab. Generate a workspace
+
+In this lab, you'll generate a Neo.mjs workspace and run the starter app.
+
+<!-- lab -->
+<details>
+<summary>Use the command-line to generate the workspace</summary>
+
+Use a terminal window to navigate to some parent folder, 
+then run 
+
+    npx neo-app@latest
+
+You'll be propted for a workspace name, starter app name, etc &mdash; accept the default for everything.
+As the command finishes it starts a server and opens a browser window.
+</details>
+
+<details>
+<summary>Inspect the workspace</summary>
+
+The workspace contains a local copy of the API docs, an `apps` directory (where your apps are found), 
+and some other directories.
+</details>
+
+<details>
+<summary>Start the server</summary>
+From the root of the `workspace` start the server via `npm run server-start`. That starts a server
+at port 8080 and opens a new browser window.
+
+<img src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/StartServer.png" style="width:80%"/>
+
+</details>
+
+
+<details>
+<summary>Run the starter app</summary>
+
+By default, an app named `myapp` was created. You can run it by entering the `apps` directory and 
+clicking `myapp`. It's a folder containing an `index.html` along with the source code for the app.
+
+<img src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/RunTheStarterApp.png" style="width:80%"/>
+
+</details>
+
+<!-- /lab -->
+
+
+##Anatomy
+
+The purpose of the lab was to generate a workspace, but as long as we're here let's take a look
+at the `workspace/apps/myapp` directory.
+
+- `view/MainContainer.mjs`
+- `app.mjs`
+- `index.html`
+- `neo-config.json`
+
+Application source is in `.mjs` files. These are standard _modular JavaScript_ files
+with `import` and `export` statements, and class definitions. Neo.mjs apps have one class 
+definition per `.mjs` source file. 
+
+The index file contains a script tag that runs `MicroLoader.mjs`, which is a simple 
+file that launches the app based on information found in `neo-config.json`.
+
+Don't worry about the file contents for now: we'll do that in the next lab.
+
+##Flow of Execution
+
+<img src="https://s3.amazonaws.com/mjs.neo.learning.images/FlowOfExecution.jpg" style="width:50%"/>
+
+As you can see, `MicroLoader.mjs` runs `Main.mjs`, which in turn spawns the three web-wokers used by Neo.mjs:
+
+- `neomjs-data-worker` handles Ajax calls and sockets
+- `neomjs-vdom-worker` keeps track of the view (and applies delta updates to the main thread)
+- `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 &mdash; along wih the efficient way the `neomjs-vdom-worker` applies delta updates &mdash; is why Neo.mjs applications run so fast. 
+
+##Commonly-used Scripts
+
+If you look in the `package.json` script block you'll see several scripts used for generating applications and classes, 
+doing builds, and starting a server. We'll use several of them throughout the tutorials.
+
+- create-app &mdash; creates a simple demo app
+- create-app-minimal &mdash; creates a application shell with no content
+- server-start &mdash; starts a server with webroot set to the workspace
+- build-all &mdash; builds minimized versions of your apps
+- build-themes &mdash; creates app .css from .scss files found in `resources/scss`
+- watch-themes &mdash; creates app .css as you save changes to any app
+
+
+##Lab. Create the earthquakes starter app
+
+<!-- lab -->
+
+In this lab you'll create a starter app and add a single component.
+
+<details>
+
+<summary>Use the command-line to create a starter app</summary>
+
+Use a terminal window to navigate to the workspace and run the following script. Use "Earthquakes"
+as the app name, and <b>when prompted for "Main thread add-ons" choose GoogleMaps</b> (using arrow
+keys and the space bar to toggle add-on options). Use defaults for everything else.
+
+    npm run generate-app-minimal
+
+After the script runs yous should see these files in the `app/earthquakes` directory.
+
+`view/MainContainer.mjs`
+- `app.mjs`
+- `index.html`
+- `neo-config.json`
+
+If you look in `neo-config.json` you should see this content. Note the `mainThreadAddons` block 
+&mdash; it specifies the default add-ons, as well as the GoogleMaps add-on you specified.
+<pre>
+{
+    "appPath": "../../apps/myapp/app.mjs",
+    "basePath": "../../",
+    "environment": "development",
+    "mainPath": "../node_modules/neo.mjs/src/Main.mjs",
+    "workerBasePath": "../../node_modules/neo.mjs/src/worker/",
+    "themes": [
+        "neo-theme-neo-light"
+    ]
+}
+</pre>
+
+When the script finishes you should see 
+
+You'll be propted for a workspace name, starter app name, etc &mdash; accept the default for everything.
+As the command finishes it starts a server and opens a browser window.
+</details>
+
+<details>
+<summary>Look at the main view source</summary>
+
+</details>
+
+<details>
+<summary>Add a component</summary>
+
+</details>
+
+
+<details>
+<summary>Start the server</summary>
+
+</details>
+
+<!-- /lab -->
+
+##Introduction to Debugging
+
+##Lab. Debugging
+
+In this lab you'll get a little debugging practice by getting component references, changing properties, 
+and runing methods.
+
+<!-- lab -->
+
+<details>
+<summary>Inspect the workspace</summary>
+
+The workspace contains a local copy of the API docs, an `apps` directory (where your apps are found), 
+and some other directories.
+</details>
+
+<details>
+<summary>Start the server</summary>
+From the root of the `workspace` start the server via `npm run server-start`. That starts a server
+at port 8080 and opens a new browser window.
+
+<img src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/StartServer.png" style="width:80%"/>
+
+</details>
+
+
+<details>
+<summary>Run the starter app</summary>
+
+By default, an app named `myapp` was created. You can run it by entering the `apps` directory and 
+clicking `myapp`. It's a folder containing an `index.html` along with the source code for the app.
+
+<img src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/RunTheStarterApp.png" style="width:80%"/>
+
+
+</details>
+
+<!-- /lab -->

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

@@ -1 +1,142 @@
-### todo: Events
+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.
+
+Some terminology related to events is that events are _fired_, and as a result, some 
+event _handler_ — or _listener_ — is run.
+
+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.)
+
+<pre data-neo>
+import Base from '../../../../src/container/Base.mjs';
+import TextField from '../../../../src/form/field/Text.mjs';
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        layout: {ntype:'vbox', align:'start'},
+        items : [{
+            module: TextField,
+            labelText  : 'First name',
+            listeners: {
+                change: data=>console.log(data.value), // There are other properties, like oldValue
+                focusEnter: data=>console.log(`Entering ${data.component.labelText}`) 
+            }
+        },
+        {
+            module: TextField,
+            labelText  : 'Last name',
+            listeners: {
+                change: data=>console.log(data.value), // There are other properties, like oldValue
+                focusEnter: data=>console.log(`Entering ${data.component.labelText}`) 
+            }
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+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.
+
+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. 
+
+<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';
+
+class MainViewController extends Controller {
+    static config = {
+        className: 'Example.view.MainViewController'
+    }
+    onChange(data){
+        console.log(data.value);
+    }
+}
+Neo.applyClassConfig(MainViewController);
+
+
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        controller: MainViewController,
+        layout: {ntype:'vbox', align:'start'},
+        items : [{
+            module: TextField,
+            labelText  : 'Name',
+            listeners: {
+                change: 'onChange'
+            }
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+(It's important to keep in mind that in Neo.mjs, all class definitions are coded in their own
+source file: one class per file. In the examples we're putting all the relevant classes together
+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.)
+
+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.
+
+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`. 
+
+The code uses a special Neo.mjs feature you haven't seen yet &mdash; the use of an underscore property. 
+We'll discuss that at length later, but in a nutshell, config properties ending in an underscore 
+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';
+
+class ToggleButton extends Button {
+    static config = {
+        className: 'Example.view.ToggleButton',
+        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
+    }
+    onClick(data){
+        super.onClick(data); 
+        this.checked = !this.checked;      
+    }
+}
+Neo.applyClassConfig(ToggleButton);
+
+
+class MainView extends Base {
+    static config = {
+        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
+            }
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>

package/resources/data/deck/learnneo/p/Extending.md

@@ -1 +1,116 @@
-### todo: Extending Components
+In theory, a Neo.mjs app could be defined in a single `.mjs` source file. But that would be very hard to 
+maintain, and any reusable configs would have to be duplicated. Instead, each of your views and reusable 
+widgets will be defined as its own class. The result is simpler views which are inherently reusable and easier 
+to test.
+
+Consider this code. It's a panel with a header and a table. The table has a store. 
+
+<pre data-neo>
+import Base        from  '../../../../src/container/Panel.mjs';
+import Button      from  '../../../../src/button/Base.mjs';
+import Table       from  '../../../../src/table/Container.mjs';
+
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        headers: [{
+            dock: 'top',
+            items: [{
+                module: Button,
+                text: 'She loves me...',
+                handler: () => Neo.Main.alert({message: 'Yeah, yeah yeah!'})
+            }]
+        }],
+        items : [{
+            module: Table,
+            store: {
+                autoLoad: true,
+                url: '../../resources/data/deck/learnneo/data/theBeatles.json',
+                model: {
+                    fields: [{name: 'first'}, {name: 'last'}, {name: 'dob', type: 'date'}]
+                }
+            },
+            columns: [{
+                text: 'First',
+                dataField: 'first',
+            }, {
+                text: 'Last',
+                dataField: 'last',
+            }]
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+If you wanted, any of the configs can be refactored into their own class. Here, the button, store, and table
+have been refactored into their own classes, and the main view is using them. The main view is simpler and
+more abstract, and each class can be reused, tested, and maintained independently. 
+
+<pre data-neo>
+import Base        from  '../../../../src/container/Panel.mjs';
+import Button      from  '../../../../src/button/Base.mjs';
+import Table       from  '../../../../src/table/Container.mjs';
+import Store       from  '../../../../src/data/Store.mjs';
+
+class BeatlesButton extends Button {
+    static config = {
+        className: 'Example.view.BeatlesButton',
+        text: 'She loves me...',
+        handler: () => Neo.Main.alert({message: 'Yeah, yeah yeah!'})
+    }
+}
+Neo.applyClassConfig(BeatlesButton);
+
+class BeatlesStore extends Store {
+    static config = {
+        className: 'Example.view.BeatlesStore',
+        autoLoad: true,
+        url: '../../resources/data/deck/learnneo/data/theBeatles.json',
+        model: {
+            fields: [{name: 'first'}, {name: 'last'}, {name: 'dob', type: 'date'}]
+        }
+    }
+}
+Neo.applyClassConfig(BeatlesStore);
+
+class BeatlesTable extends Table {
+    static config = {
+        className: 'Example.view.BeatlesTable',
+        columns: [{
+            text: 'First',
+            dataField: 'first',
+        }, {
+            text: 'Last',
+            dataField: 'last',
+        }]
+   }
+}
+Neo.applyClassConfig(BeatlesTable);
+
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        headers: [{
+            dock: 'top',
+            items: [{
+                module: BeatlesButton,
+            }]
+        }],
+        items : [{
+            module: BeatlesTable,
+            store: {
+                module: BeatlesStore
+            },
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+There are several use-cases for creating your own classes:
+
+- For reuse
+- To isolate complexity
+- To add events or methods to the new class
+- To test the component independently

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

@@ -0,0 +1,126 @@
+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:
+
+- Using the component references passed to the event handler
+- Tagging a component with a `reference` and using `this.getReference()` in the controller
+
+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 Base        from  '../../../../src/container/Base.mjs';
+import Controller  from  '../../../../src/controller/Component.mjs';
+import Button      from   '../../../../src/Button/Base.mjs';
+
+class MainViewController extends Controller {
+    static config = {
+        className: 'Example.view.MainViewController'
+    }
+    onDisableButtonClick(data){
+        data.component.disabled = true;
+    }
+}
+Neo.applyClassConfig(MainViewController);
+
+
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        controller: MainViewController,
+        layout: {ntype:'vbox', align:'start'},
+        items : [{
+            module: Button,
+            text: 'Disable this button',
+            handler: 'onDisableButtonClick'
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+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 Base        from  '../../../../src/container/Base.mjs';
+import Controller  from  '../../../../src/controller/Component.mjs';
+import Button      from   '../../../../src/Button/Base.mjs';
+
+class MainViewController extends Controller {
+    static config = {
+        className: 'Example.view.MainViewController'
+    }
+    onDisableButtonClick(data){
+        data.component.disabled = true;
+    }
+    onEnableButtonClick(data){
+        this.getReference('myButton').disabled = false;
+    }
+}
+Neo.applyClassConfig(MainViewController);
+
+
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        controller: MainViewController,
+        layout: {ntype:'vbox', align:'start'},
+        items : [{
+            module: Button,
+            reference: 'myButton',
+            text: 'Disable this button',
+            handler: 'onDisableButtonClick'
+        }, {
+            module: Button,
+            text: 'Enable the other button',
+            handler: 'onEnableButtonClick'
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+
+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 
+up or down the containment hierarchy to find the specified component. Using these methods is poor technique
+becuse it violates principles of encapsulation and limiting scope.
+
+There are also debugging methods, such as `Neo.findFirst()` which will find any component matching
+the search param. 
+
+When you're debugging it's pretty handy to be able to inspect or interact with any component in the app. 
+But app logic should never use `Neo.findFirst()` and very rarely use `up()` or `down()`.
+
+The following example gets a reference to the _Learn_ button at the top of this site, and changes its `text`.
+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 Base        from  '../../../../src/container/Base.mjs';
+import Button      from   '../../../../src/Button/Base.mjs';
+
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        layout: {ntype:'vbox', align:'start'},
+        items : [{
+            module: Button,
+            text: 'Change Learn caption',
+            handler: data=>{
+                const component = Neo.findFirst({text:'Learn'});
+                if (component) component.text = 'Yikes!';
+            }
+        }, {
+            module: Button,
+            text: 'Restore Learn caption',
+            handler: data=>{
+                const component = Neo.findFirst({text:'Yikes!'});
+                if (component) component.text = 'Learn';
+            }
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>

package/resources/data/deck/learnneo/p/TestLivePreview.md

@@ -1,10 +1,32 @@
+To code a live preview, enclose the code in a `pre` tag with the `data-neo` attribute.
 
-sdfiousodfi
-
-<pre data-neo>
-let a = 1;
-</pre>
+<pre>&lt;pre data-neo> 
+&lt;/pre> 
 
+Imports are relative to the portal app running within the framework. That means
+Neo.mjs imports should be coded to go up four levels, then look into the `src`
+directory. For example, to import _container_, use `import Base from '../../../../src/container/Base.mjs`
 
+You can define as many classes you need, such as component models and controllers, but the the _last_
+class being defined is assumed to be the view being rendered. In other words, if the final class definition is a component, it's rendered.
 
-slfiksdf
+<pre data-neo>
+import Base from '../../../../src/container/Base.mjs';
+import Button from '../../../../src/button/Base.mjs';
+import Split from '../../../../src/button/Split.mjs';
+class Bar extends Base {
+    static config = {
+        ntype: 'demoFoo',
+        className: 'Foo.Bar',
+        layout: {ntype: 'hbox'},
+        items: [{
+            module: Button,
+            text: 'Button One'
+        },{
+            module: Button,
+            text: 'Button Two'
+        }]
+    }
+}
+Neo.applyClassConfig(Bar);
+</pre>

package/resources/data/deck/learnneo/t.json

@@ -5,14 +5,13 @@
         {"name": "Workspaces and Applications",             "parentId": "GettingStarted",    "isLeaf": true,  "id": "2023-10-14T19-25-08-153Z"},
         {"name": "Describing a View",                       "parentId": "GettingStarted",    "isLeaf": true,  "id": "DescribingTheUI"},
         {"name": "Events",                                  "parentId": "GettingStarted",    "isLeaf": true,  "id": "Events"},
-        {"name": "Updating View State",                     "parentId": "GettingStarted",    "isLeaf": true,  "id": "ComponentState"},
-        {"name": "Extending Components",                    "parentId": "GettingStarted",    "isLeaf": true,  "id": "Extending"},
-        {"name": "Adding Properties",                       "parentId": "GettingStarted",    "isLeaf": true,  "id": "AddingProperties"},
-        {"name": "Component Models and Binding",            "parentId": "GettingStarted",    "isLeaf": true,  "id": "ComponentModels"},
-        {"name": "What about HTML tags?",                   "parentId": "GettingStarted",    "isLeaf": true,  "id": "WhatAboutHTML"},
+        {"name": "Component References",                    "parentId": "GettingStarted",    "isLeaf": true,  "id": "References"},
+        {"name": "Extending Classes",                       "parentId": "GettingStarted",    "isLeaf": true,  "id": "Extending"},
+        {"name": "Config",                                  "parentId": "GettingStarted",    "isLeaf": true,  "id": "Config"},
+        {"name": "Shared Bindable Data",                    "parentId": "GettingStarted",    "isLeaf": true,  "id": "ComponentModels"},
     {"name": "Tutorials",                                   "parentId": null,                "isLeaf": false, "expanded": false, "id": "Tutorials"},
         {"name": "Rock Scissors Paper",                     "parentId": "Tutorials",         "isLeaf": true,  "expanded": false, "id": "RSP"},
-        {"name": "Earthquakes",                             "parentId": "Tutorials",         "isLeaf": false, "expanded": false, "id": "Earthquakes"},
+        {"name": "Earthquakes",                             "parentId": "Tutorials",         "isLeaf": true,  "expanded": false, "id": "Earthquakes"},
     {"name": "Cookbook",                                    "parentId": null,                "isLeaf": false, "expanded": false, "id": "InDepth"},
         {"name": "Config",                                  "parentId": "InDepth",           "isLeaf": false, "id": "Config"},
         {"name": "Instance Lifecycle",                      "parentId": "InDepth",           "isLeaf": false, "id": "InstanceLifecycle"},

package/resources/data/deck/training/p/2022-12-27T21-55-30-948Z.md

@@ -1 +1 @@
-<img height="540" src="resources/images/FlowOfExecution.jpg"></img>
+<img height="540" src="https://s3.amazonaws.com/mjs.neo.learning.images/FlowOfExecution.jpg"></img>

package/resources/data/deck/training/p/2022-12-27T22-23-55-083Z.md

@@ -1 +1 @@
-<img height="580" src="resources/images/intro/InitialTable.png"/>
+<img height="580" src="https://s3.amazonaws.com/mjs.neo.learning.images/intro/InitialTable.png"/>

package/resources/data/deck/training/p/2022-12-29T16-00-13-223Z.md

@@ -4,4 +4,4 @@ Let's do a little code inspection using
 
 Look in the API docs to find the `ntype`.
 
-<img height="300" src="resources/images/intro/FindingNtype.png"/>
+<img height="300" src="https://s3.amazonaws.com/mjs.neo.learning.images/intro/FindingNtype.png"/>