Merge pull request #4 from Cyber-Duck/master

Taking advantage of the override by ID
jasonkneen · Apr 7, 2017 · d1cdb2d · d1cdb2d
2 parents 0b7a380 + 0391cda
commit d1cdb2d
Show file tree

Hide file tree

Showing 2 changed files with 79 additions and 37 deletions.
diff --git a/alloyXL.js b/alloyXL.js
@@ -17,13 +17,15 @@ Alloy.createController = function(name, args) {
         if (path.length > 0) name = path[path.length - 1];
 
         // Avoid having issues with same controller name within different folders
-        if (Alloy.Controllers[name]) {
-            if (controller.getView().id) {
-                name = controller.getView().id;
-            } else {
-                console.warn("::AlloyXL:: The controller Alloy.Controllers." + name + " (" + controller.__controllerPath + ") exists, and will be overwriten because it's conflicting with another controller already instanciated with the same name. " +
-                "Please add a unique ID on the top parent view within that controller view so you can use this as the controller name within AlloyXL to avoid this.");
-            }
+        if (Alloy.Controllers[name] && ! controller.getView().id) {
+            console.warn("::AlloyXL:: The controller Alloy.Controllers." + name + " (" + controller.__controllerPath + ") exists, and will be overwriten because it's conflicting with another controller already instanciated with the same name. " +
+            "Please add a unique ID on the top parent view within that controller view so you can use this as the controller name within AlloyXL to avoid this.");
+        }
+
+        // No matter what, the ID on the top parent view will always override
+        // the controller name driven from its filename.
+        if (controller.getView().id) {
+            name = controller.getView().id;
         }
 
         // save the controller to Alloy.Controllers for global access

diff --git a/readme.md b/readme.md
@@ -17,9 +17,9 @@ So previously I'd end up writing code to clean up a view / controller within say
 
 ```JS
 function doClose() {
-	$.getView().close();
-	$.destroy();
-	$.off();
+    $.getView().close();
+    $.destroy();
+    $.off();
 }
 ```
 
@@ -38,29 +38,6 @@ The main things I wanted to achieve with AlloyXL were:-
 * Reduce code throughout the app
 * Allow access to controllers globally like Alloy.Collections
 
-## Same name controllers conflicts
-
-The **Alloy.Controllers** object stores the *last* instance to a controller -- so normally, if you're creating controllers with different names it's all fine -- however if you create two instances to a controller at once, only the *last* one is in **Alloy.Controllers**.
-
-If you have two controllers having the same names but located in different folders (`app/controllers/registration/index.js` and `app/controllers/home/index.js` for example), this will cause a conflict within AlloyXL.
-
-However, you can avoid this issue by either using different and unique names for all of your controllers **or** by using a unique ID on the top parent `<NavigationWindow>`, `<Window>` or `<View>` within your controllers and use it as the controller name within AlloyXL:
-
-File: `app/views/registration/index.xml`
-```xml
-<Alloy>
-    <View id="myUniqueID">
-	</View>
-</Alloy>
-```
-
-```javascript
-// Now access the controller using
-Alloy.Controllers.myUniqueID;
-// instead of
-Alloy.Controllers.index;
-```
-
 ## Quick Start
 
 * [Install from NPM the latest version](https://www.npmjs.com/package/alloyxl)
@@ -87,7 +64,7 @@ _(where the view we're in is a Navigation Window or TabGroup and "subview" is a
 
 ```javascript
 $.getView().openWindow(Alloy.createController("subview").on("open", function(){
-        Alloy.Controllers.subview.getView().setBackgroundColor("#F00");
+    Alloy.Controllers.subview.getView().setBackgroundColor("#F00");
 }).getView());
 ```
 In this example, without creating any local pointers to the controller or view, we're responding to the open event on the window, and setting the background color of the view to red.
@@ -96,16 +73,79 @@ You can also combine this with Alloy event chaning:
 
 ```javascript
 $.getView().openWindow(Alloy.createController("subview").on("open", function(){
-        Alloy.Controllers.subview.getView().setBackgroundColor("red");
+    Alloy.Controllers.subview.getView().setBackgroundColor("red");
 }).on("anotherEvent", function(){
-			// handle the anotherEvent here
+    // handle the anotherEvent here
 }).once("oneTime", function(){
-			// this event will only ever fire once
+    // this event will only ever fire once
 }).getView());
 ```
 
 Because AlloyXL is intercepting and overriding the **Alloy.createController** method, it's able to do all this at the source, ensuring that everything is cleaned up afterwards!
 
+## Same name controllers conflicts
+
+The **Alloy.Controllers** object stores the *last* instance to a controller -- so normally, if you're creating controllers with different names it's all fine -- however if you create two instances to a controller at once, only the *last* one is in **Alloy.Controllers**.
+
+If you have two controllers having the same names but located in different folders (`app/controllers/registration/index.js` and `app/controllers/home/index.js` for example), this will cause a conflict within AlloyXL.
+
+However, you can avoid this issue by either using different and unique names for all of your controllers **or** by using a unique ID on the top parent `<NavigationWindow>`, `<Window>` or `<View>` within your controllers and use it as the controller name within AlloyXL:
+
+File: `app/views/registration/index.xml`
+```xml
+<Alloy>
+    <View id="myUniqueID">
+    </View>
+</Alloy>
+```
+
+```javascript
+// Now access the controller using
+Alloy.Controllers.myUniqueID;
+// instead of
+Alloy.Controllers.index;
+```
+
+### Taking the advantage of overriding controllers 
+
+By applying the above, you can easily override a controller already instanciated within `Alloy.Controllers`, no matter what.
+
+This is very useful for `<NavigationWindow>` if you want to re-use the same "ID" or controller name accross your project. Here is a simple example:
+
+File: `app/views/login.xml` Login screen
+```xml
+<Alloy>
+    <NavigationWindow id="navigationWindow">
+    ...
+    </NavigationWindow>
+</Alloy>
+```
+
+File: `app/views/home.xml` Home screen once connected
+```xml
+<Alloy>
+    <NavigationWindow id="navigationWindow">
+    ...
+    </NavigationWindow>
+</Alloy>
+```
+
+File: `app/views/welcome.xml` Welcome window displayed no matter if you're logged in or not
+```xml
+<Alloy>
+    <Window>
+    ...
+    </Window>
+</Alloy>
+```
+
+```javascript
+// This will work no matter if the controller used is login or home.
+Alloy.Controllers.navigationWindow.getView().openWindow(
+    Alloy.createController("welcome").getView()
+);
+```
+
 ## License
 
 <pre>