interim commit working with new application object and other fixes/updates

Cole Davis · Cole Davis · commit 86badb506a9d · 2012-12-20T11:34:50.000-08:00
Enyo-DCO-1.1-Signed-off-by: Cole Davis &lt;cole.davis@palm.com&gt;
diff --git a/debug.html b/debug.html
@@ -16,8 +16,5 @@
 		<script src="source/package.js" type="text/javascript"></script>
 	</head>
 	<body class="enyo-unselectable">
-		<script>
-      enyo.start();
-		</script>
 	</body>
 </html>
diff --git a/gendocs.sh b/gendocs.sh
@@ -2,7 +2,7 @@
 
 docco -t assets/docco/pagelet.jst -c assets/docco/docco.less \
     -o assets/docco/generated \
-    source/Core.js \
+    source/start.js \
     source/controllers/PanelsController.js \
     source/controllers/DocumentsController.js \
     source/controllers/EditorController.js \
@@ -11,11 +11,12 @@ docco -t assets/docco/pagelet.jst -c assets/docco/docco.less \
     source/models/Collections/RollerCollection.js \
     source/models/Models/RollerModel.js \
     source/models/Scaffold.js \
-    source/views/App.js \
+    source/views/RootView.js \
     source/views/Editor.js \
     source/views/Toolbar.js \
     source/views/Main/Divider.js \
     source/views/Main/Main.js \
     source/views/Main/Documents/Documents.js \
     source/views/Main/Roller/Roller.js \
-    source/views/Main/Roller/RollerPanel.js
+    source/views/Main/Roller/RollerPanel.js \
+    source/apps/Sample.js
diff --git a/index.html b/index.html
@@ -16,12 +16,6 @@
 		<script src="build/app.js"></script>
 	</head>
 	<body class="enyo-unselectable">
-		<script>
-			if (!window.enyo) {
-				alert('No application build found, redirecting to debug.html.');
-				location = 'debug.html';
-			}
-			enyo.start();
-		</script>
+	    <script type="text/javascript">if (undefined === window.enyo) location = "debug.html";</script>
 	</body>
 </html>
diff --git a/source/apps/Sample.js b/source/apps/Sample.js
@@ -1,12 +1,42 @@
 
+// The `Sample.Application` kind
+// -----------------------------
+// There can be multiple `enyo.Application`s running simultaneously
+// if you needed. In our case, we only need one. That being said the
+// concept of an `enyo.Application` is simple: coordinate startup and
+// initialization of a group of objects, if there is a view, render that
+// when appropriate.
 enyo.kind({
+    // While the namespace of the application is `Sample` the namespace
+    // of the instanced application is up to the developers discretion.
+    // Go look at our `start.js` file if you haven't to see how this was
+    // done.
     name: "Sample.Application",
     kind: "enyo.Application",
-    autoStart: false,
-    renderOnStart: true,
+    // The `autoStart` flag is `true` by default but its explicitly
+    // designated here for clarity. Since it is true, the `enyo.Application`
+    // `start` method will be executed as soon as the constructor is called
+    // on our application.
+    autoStart: true,
+    // Every application can potentially _own a single view_. This means that
+    // it can programatically determine when to render its _view_ into the
+    // DOM and where to render it when it does.
     view: "Sample.RootView",
+    // The `enyo.Application` also lets us declare what controllers we want
+    // to initialize for this application at the _application scope_. This is
+    // a _very important concept_. Notice the name properties of these
+    // declarations and also note the namespace of this _kind_. Its `Sample`.
+    // By default, the `enyo.Application` will attempt to create instances of
+    // these controllers in the namespace of _the application kind that owns them_.
+    // In our case, this means that when the application is created there should
+    // immediately be available 2 controllers on the `Sample` object: `Sample.panels`
+    // and `Sample.documents`. This allows any other objects in the application to
+    // reference these controllers at those paths. It is possible to instantiate
+    // them in a different namespace (or none at all) by setting a flag on these
+    // declarations `global: true`. The application will not attempt to prefix the
+    // `name` with the namespace of the given _kind_.
     controllers: [
         {name: "panels", kind: "Sample.PanelsController"},
         {name: "documents", kind: "Sample.DocumentsController"}
     ]
-});
+});
diff --git a/source/apps/package.js b/source/apps/package.js
@@ -1,3 +1,3 @@
 enyo.depends(
     "Sample.js"
-);
+);
diff --git a/source/controllers/DocumentsController.js b/source/controllers/DocumentsController.js
@@ -2,7 +2,7 @@
 
     // Locally-scoped variable that contains the fixed names of each of
     // the documentation files we're going to load via `enyo.Ajax` calls.
-    var documents = [ "App", "PanelsController", "Core", "Divider",
+    var documents = [ "RootView", "PanelsController", "start", "Divider",
         "Documents", "DocumentsController", "Editor", "EditorController",
         "FitToTargetBoundsLayout", "Main", "Roller", "RollerCollection",
         "RollerLayout", "RollerModel", "RollerPanel", "Scaffold",
@@ -31,9 +31,9 @@
         xhr.response(loaded).go();
     };
     
-    // The `App.DocumentsController` kind
-    // ----------------------------------
-    // `App.DocumentsController` is derived from `enyo.ArrayController`,
+    // The `Sample.DocumentsController` kind
+    // -------------------------------------
+    // `Sample.DocumentsController` is derived from `enyo.ArrayController`,
     // a kind designed to act like an array, but with support for bindings
     // and observers. Because it inherits from `enyo.Controller`, it can
     // have multiple event targets, which makes it a perfect fit for our
@@ -45,7 +45,7 @@
     // events to this controller, and when the `selected` property changes,
     // the `Documents.js` view responds.
     enyo.kind({
-        name: "App.DocumentsController",
+        name: "Sample.DocumentsController",
         kind: "enyo.ArrayController",
         handlers: {
             onSelect: "selectSource",
diff --git a/source/controllers/EditorController.js b/source/controllers/EditorController.js
@@ -1,15 +1,15 @@
 
-// The `App.EditorController` kind
+// The `Sample.EditorController` kind
 // -------------------------------
 // The editor controller is responsible for setting up the content in
-// the `App.Editor` view. It extends `enyo.ModelController` and proxies
+// the `Sample.Editor` view. It extends `enyo.ModelController` and proxies
 // the selected record.
 enyo.kind({
     // There is convention (not a requirement) to keep the names of
     // presentation objects closely linked with those of their
     // associated controllers. The controller name is typically formed
     // by appending `"Controller"` to the name of the view.
-    name: "App.EditorController",
+    name: "Sample.EditorController",
     // Be sure to read the documentation for `enyo.ModelController`.
     kind: "enyo.ModelController",
     // Even though the textarea is in the view, we are owned by the
@@ -21,18 +21,18 @@ enyo.kind({
     },
     constructor: function () {
        this.inherited(arguments);
-       App.panels.addDispatchTarget(this);
+       Sample.panels.addDispatchTarget(this);
     },
     // We map the selected index from the panels controller to our own
     // `index` property.
     bindings: [
-        {from: "App.panels.index", to: "index"}
+        {from: "Sample.panels.index", to: "index"}
     ],
     // Note that we can set up a `changed` event listener for a property
     // that only exists locally through bindings.
     indexChanged: function () {
         var idx = this.index;
-        var model = App.panels.at(idx);
+        var model = Sample.panels.at(idx);
         if (model && model !== this.model) this.set("model", model);
     },
     input: function () {
@@ -47,6 +47,6 @@ enyo.kind({
     // (since it exists).
     done: function () {
         // We are all done editing and can reset the state property.
-        App.panels.set("isEditing", false);
+        Sample.panels.set("isEditing", false);
     }
 });
diff --git a/source/controllers/PanelsController.js b/source/controllers/PanelsController.js
@@ -1,12 +1,12 @@
 
-// The `App.PanelsController` kind
+// The `Sample.PanelsController` kind
 // -------------------------------
 // This is the kind definition for the global singleton application
-// panels controller (`App.panels`) instantiated in the `main` function
+// panels controller (`Sample.panels`) instantiated in the `main` function
 // in `Core.js`.
 enyo.kind({
     // We give the kind a name in the application namespace.
-    name: "App.PanelsController",
+    name: "Sample.PanelsController",
     // We base this kind on `enyo.CollectionController` because we know
     // we need the collection controller's built-in methods. Even
     // though this is an `enyo.CollectionController`, we can add
@@ -18,14 +18,14 @@ enyo.kind({
     // global instance of the collection. We will hand this controller
     // a kind reference and it will instantiate the collection kind when
     // it is created.
-    collection: "App.RollerCollection",
+    collection: "Sample.RollerCollection",
     // While in Enyo 2.2+ it is not required to create the `published`
     // hash so that the corresponding getters and setters are created,
     // this is still considered to be a best practice.
     published: {
         // The entire application has state. One possible state is the
         // is the editing state. While the `isEditing` property is
-        // designed to be used directly with the `App.Roller` view kind,
+        // designed to be used directly with the `Sample.Roller` view kind,
         // any other component in the application may respond to it as
         // well (as we will see).
         isEditing: false,
@@ -50,11 +50,6 @@ enyo.kind({
     },
     // The timer reference as returned by `setInterval`
     timer: null,
-    // We listen for the special `ready` event to signal that we're ready
-    // to start inspecting and listening on our property observers.
-    handlers: {
-        onready: "collectionChanged"
-    },
     // The following methods are actually dispatch event targets of an
     // `enyo.View` (the toolbar). These methods are executed in response
     // to events bubbled from the view layer.
diff --git a/source/css/RootView.less b/source/css/RootView.less
diff --git a/source/css/package.js b/source/css/package.js
@@ -1,5 +1,5 @@
 enyo.depends(
-    "App.less",
+    "RootView.less",
     "Roller.less",
     "Main.less",
     "Editor.less",
diff --git a/source/ext/FitToTargetBoundsLayout.js b/source/ext/FitToTargetBoundsLayout.js
@@ -1,5 +1,5 @@
 
-// `App.FitToTargetBoundsLayout`, an interesting layout kind
+// `Sample.FitToTargetBoundsLayout`, an interesting layout kind
 // ---------------------------------------------------------
 // We need to make sure that the editor matches the current
 // dimensions of another view not directly in its own tree.
@@ -10,7 +10,7 @@
 // path (relative to the view) or a full path to an instance
 // or an object reference.
 enyo.kind({
-    name: "App.FitToTargetBoundsLayout",
+    name: "Sample.FitToTargetBoundsLayout",
     kind: "enyo.Layout",
     // Local copy of the property from the container
     targetPath: "",
diff --git a/source/ext/RollerLayout.js b/source/ext/RollerLayout.js
@@ -1,12 +1,12 @@
 
-// The `App.RollerLayout` kind
+// The `Sample.RollerLayout` kind
 // ---------------------------
-// This special layout handler for `App.Roller` is designed to make
+// This special layout handler for `Sample.Roller` is designed to make
 // adjustments in a mobile environment (where space is limited) or
 // when an orientation change reduces the amount of vertical display
 // space available.
 enyo.kind({
-  name: "App.RollerLayout",
+  name: "Sample.RollerLayout",
   kind: "enyo.Layout",
   flow: function () {
     this.reflow();  
diff --git a/source/models/Collections/RollerCollection.js b/source/models/Collections/RollerCollection.js
@@ -1,5 +1,5 @@
 
-// The `App.RollerCollection` kind
+// The `Sample.RollerCollection` kind
 // -------------------------------
 // It is helpful to abstract your application objects--for clarity's
 // sake, if nothing else. In this case, we have no special properties
@@ -17,7 +17,7 @@
 // doesn't know what the underlying `enyo.Model` type is, and it will
 // let you know if it cannot figure out which model kind to use.
 enyo.kind({
-    name: "App.RollerCollection",
+    name: "Sample.RollerCollection",
     kind: "enyo.Collection",
-    model: "App.RollerModel"
+    model: "Sample.RollerModel"
 });
diff --git a/source/models/Models/RollerModel.js b/source/models/Models/RollerModel.js
@@ -1,5 +1,5 @@
 
-// The `App.RollerModel` kind
+// The `Sample.RollerModel` kind
 // --------------------------
 // While this subkind of `enyo.Model` doesn't do a whole lot, it
 // serves to illustrate one very important point: It is highly
@@ -11,7 +11,7 @@
 // pressing the "Add" button), the initial message is the one
 // declared here in the model's `defaults` block.
 enyo.kind({
-    name: "App.RollerModel",
+    name: "Sample.RollerModel",
     kind: "enyo.Model",
     defaults: {
         header: "You just created a new record!",
diff --git a/source/models/Scaffold.js b/source/models/Scaffold.js
@@ -4,7 +4,7 @@
 // We want there to be some messages in the roller when the user first
 // sees it, so we create an array of sample records and add these to the
 // collection during app startup. (You'll see this happen in `Core.js`.)
-App.Scaffold = {
+Sample.Scaffold = {
     "Roller": [
         {header: "Welcome to a new pattern of development in Enyo.js"},
         {header: "Make use of the new bindings, observers and notifications"},
diff --git a/source/start.js b/source/start.js
@@ -1,6 +1,27 @@
 
+// The `enyo.ready` method
+// -----------------------
+// Some things need to occur only after the `document` has fully
+// initialized and is ready - thus ensuring the entirety of source
+// has been loaded. You can call `enyo.ready` and pass it a function
+// (and an optional context) as many times as you need and those method
+// will only execute once the `document` is completely ready.
 enyo.ready(function () {
-   app = new Sample.Application();
-   Sample.panels.add(Sample.Scaffold.Roller);
-   app.start(); 
+    // This is a very imporant declaration. This is where we instance
+    // our application. We arbitrarily assign it to a global variable
+    // `app` for reference if we need it. All other components of this
+    // application are instanced in the `Sample` namespace. See the
+    // `apps/Sample.js` file for more information on namespaces and what
+    // this actually means.
+    app = new Sample.Application();
+    // When our application renders for the first time we want it to have
+    // some data already. Since we're not loading from a remote source we
+    // go ahead and use some scaffolding we setup in `models/Scaffold.js`.
+    Sample.panels.add(Sample.Scaffold.Roller);
+    // Now that data is present for the _view_ layer to make use of, lets
+    // go ahead and render it to the DOM. We could have had the application
+    // automatically render when it was created but in `apps/Sample.js` we
+    // deliberately told it not to so we can prepare our scaffold data before
+    // the _view_ layer was initialized.
+    app.render();
 });
diff --git a/source/views/Editor.js b/source/views/Editor.js
@@ -1,15 +1,15 @@
 
-// The `App.Editor` kind
+// The `Sample.Editor` kind
 // ----------------------
 // The editor is a view that is only visible when the application
-// state property (on `App.panels`) is set to true. This is only
+// state property (on `Sample.panels`) is set to true. This is only
 // the case when the "Edit" button is selected. By applying some CSS
 // (using LESS) we can create the effect of an overlay. With the
 // proper bindings, we can set up a text editor with hooks into the
 // modifiable content of the underlying record; proper bindings to
 // other views can give us real-time UI updates with no additional work.
 enyo.kind({
-    name: "App.Editor",
+    name: "Sample.Editor",
     id: "editor",
     // We use a custom controller kind, which we call a "view controller"
     // because it is owned by this view and has awareness of it. Because
@@ -22,7 +22,7 @@ enyo.kind({
     // expected; if not, the event is routed right back up through the
     // view. This allows us to take non-view-related logic and graft it
     // onto a separate kind that has additional functionality.
-    controller: "App.EditorController",
+    controller: "Sample.EditorController",
     // We are able to create bindings with relative paths for both the
     // `from` and `to` properties. One thing to note is that the
     // controller is subkinded from `enyo.ModelController`--this allows
@@ -39,7 +39,7 @@ enyo.kind({
     ],
     // We use a custom layout kind that can be found in the `ext` directory
     // in the project source.
-    layoutKind: "App.FitToTargetBoundsLayout",
+    layoutKind: "Sample.FitToTargetBoundsLayout",
     // The layout looks for the `fitTarget` property when detecting the
     // view for which we want to match the bounds. This is only necessary
     // due to limitations in the way the CSS is applied--this editor
diff --git a/source/views/Main/Divider.js b/source/views/Main/Divider.js
diff --git a/source/views/Main/Documents/Documents.js b/source/views/Main/Documents/Documents.js
diff --git a/source/views/Main/Main.js b/source/views/Main/Main.js
diff --git a/source/views/Main/Roller/Roller.js b/source/views/Main/Roller/Roller.js
diff --git a/source/views/Main/Roller/RollerPanel.js b/source/views/Main/Roller/RollerPanel.js
diff --git a/source/views/RootView.js b/source/views/RootView.js
diff --git a/source/views/Toolbar.js b/source/views/Toolbar.js

-Original file line number
+Diff line change
@@ @@ -1,3 +1,3 @@ @@
 enyo.depends(
     "Sample.js"
 -);
 +);