Skip to content
Browse files

meh, more docs

  • Loading branch information...
1 parent 4a01b36 commit d6dab3b103ec51856fa0c837ec865175bb858b0a @seanhess committed Oct 19, 2009
Showing with 49 additions and 75 deletions.
  1. +9 −22 README.mdown
  2. +11 −16 doc/Glossary.mdown
  3. +6 −26 doc/Questions.mdown
  4. +23 −11 doc/UseCases.mdown
View
31 README.mdown
@@ -3,7 +3,6 @@
[goals]: http://github.com/seanhess/zero/tree/master/doc/Goals.mdown
[questions]: http://github.com/seanhess/zero/tree/master/doc/Questions.mdown
-
# Zero
Zero is a new way to approach Dependency Injection in Actionscript. It is a toolkit that replaces the concept of the Interface with the [DependencyInterface][glossary], which defines an interface using Decorators instead of an ActionScript Interface.
@@ -18,7 +17,6 @@ In this document, `Interface` refers to an actionscript interface, while "interf
[**Questions**][questions]
-
### Getting Started
Visit Downloads and get the latest swc.
@@ -45,7 +43,7 @@ You can specify events by putting an `[Event]` tag on the class
[Event(name="anEvent", type="flash.events.Event")]
-Here is a full example
+Here is a full example. Please see the [Glossary][glossary] for information about the context.
package dependency
{
@@ -69,21 +67,19 @@ You can use `arguments` to simplify passing the arguments along
### Using Dependencies
-You use the `new` operator anywhere as if you were creating the class. Zero takes care of the rest.
+You use the `new` operator anywhere as if you were creating the class. Zero takes care of the rest. You should always pass in the [context][glossary] (a reference to the object creating it) when creating a [DependencyInterface][glossary].
- // "this" is the context
var library:DLibrary = new DLibrary(this);
-Don't worry, you are _not_ creating a dependency on the implementation. Think of the `DependencyInterface` as a normal AS `Interface`. `DependencyInterfaces` are easy to refactor to `Interfaces` and vice versa.
+Don't worry, you are _not_ creating a dependency on the implementation. Think of the [DependencyInterface][glossary] as a normal AS `Interface`. [DependencyInterfaces][glossary] are easy to refactor to `Interfaces` and vice versa.
-You can create them in MXML as well.
+You can create them in MXML as well. The [context][glossary] is set automatically in mxml.
- <!-- Automatically sets the context -->
<dependency:DLibrary id="library"/>
### Implementations
-There are no constraints on implementations at all. You don't event have to implement all the functions.
+There are no constraints on [implementations][glossary] at all. You don't event have to implement all the functions.
package service
{
@@ -106,7 +102,7 @@ There are no constraints on implementations at all. You don't event have to impl
### Connecting Implementations
-You can easily connect an implementation to a DependencyInterface using ActionScript.
+You can easily connect an [implementation][glossary] to a [DependencyInterface][glossary] using ActionScript.
import dependency.DLibrary;
import service.Library;
@@ -122,7 +118,7 @@ You can do it in MXML as well
### Multiple Implementations
-A single class doesn't need to be responsible for the whole interface.
+A single class doesn't need to be responsible for the whole [DependencyInterface][glossary].
package service
{
@@ -143,7 +139,7 @@ A single class doesn't need to be responsible for the whole interface.
}
}
-You can then connect both of them to the interface. Later implementations have priority.
+You can then connect both of them to the [interface][glossary]. Later [implementations][glossary] have priority.
var connect:Connect = new Connect(this);
connect.add(new Implement(DLibrary, Books));
@@ -158,7 +154,7 @@ or in MXML
### Factories
-You can define factories for short-term objects, like value objects or models.
+You can define factories for short-term objects, like value objects or models. Instead of creating a single copy of the implementation, it creates a new one every time it is requested.
// interface
public class DBook extends DependencyInterface
@@ -332,14 +328,5 @@ You can also connect an implementation by package or class as described above. Y
connect.wipe();
// add pristine implementations
-
-## Glossary
-
-### DependencyInterface
-
-A DependencyInterface is a class that wraps, or proxies, another object - also called a Decorator. However, unlike most Decorators, a DependencyInterface does not add any functionality. It only defines the functions that are available to call, in effect, performing the same role as an `Interface`.
-
-### Context
-Objects in Zero need to know their _context_. DependencyInterfaces need to know which object created them, or which object is asking for a particular dependency. Connect has the ability to define different rules
View
27 doc/Glossary.mdown
@@ -1,27 +1,22 @@
-# Use Cases
+## Glossary and Important Concepts
-The following use cases are provided to show how Zero will make life better.
+### interface
-### Logging
+An interface is a way to describe _what_ an object does, without describing _how_ it does it. Object-oriented languages usually have an `interface` keyword that lets you define an interface explicitly. Zero allows you to describe an interface a different way, using another object, called a DependencyInterface.
-Logging is a classic example of Object-Oriented programming falling short. You want to log everything, or lots of stuff, so you can see where a program breaks. However, log statements clutter up your code significantly. Logging is a common example for Aspect-Oriented programming, which is mostly impossible in AS.
+### DependencyInterface
+A DependencyInterface is a class that wraps, or proxies, another object - also called a Decorator. However, unlike most Decorators, a DependencyInterface does not add any functionality. It only defines the functions that are available to call, in effect, performing the same role as the interfaces built in to ActionScript.
+### Context
+In Zero, an object's context is its place in the program. If you have one object, "a", which creates another object "b", b's context is a, because a created it.
+The context of a DependencyInterfaces is the object that created it. This lets the system know which object is requesting access to the dependency.
+By giving a context to Connect, we can give different implementations to different DependencyInterfaces.
-* When testing, pass in mock implementations to a class
-* Switch to a mock server connection at runtime (a checkbox)
-* 4 different views of a list of users. Invisible ones are inactive and don't receive updates
-* When a module is unloaded it is deactivated and GC'd
-* Give a particular view a unique implementation
-* Give a particular class a unique implementation
-* Give a set of views/classes a unique implementation
-* Proxy all service requests, to convert xml data to strongly typed data before returning
-* Log all requests in the system without requiring the implementations to know about it
-
-
-
+### Implementation
+An implementation is a class that specifies functionality for an interface, or in Zero, a class connected to a DependencyInterface.
View
32 doc/Questions.mdown
@@ -1,27 +1,7 @@
-# Use Cases
-
-The following use cases are provided to show how Zero will make life better.
-
-### Logging
-
-Logging is a classic example of Object-Oriented programming falling short. You want to log everything, or lots of stuff, so you can see where a program breaks. However, log statements clutter up your code significantly. Logging is a common example for Aspect-Oriented programming, which is mostly impossible in AS.
-
-
-
-
-
-
-* When testing, pass in mock implementations to a class
-* Switch to a mock server connection at runtime (a checkbox)
-* 4 different views of a list of users. Invisible ones are inactive and don't receive updates
-* When a module is unloaded it is deactivated and GC'd
-* Give a particular view a unique implementation
-* Give a particular class a unique implementation
-* Give a set of views/classes a unique implementation
-* Proxy all service requests, to convert xml data to strongly typed data before returning
-* Log all requests in the system without requiring the implementations to know about it
-
-
-
-
+* Does this approach solve actual problems?
+* Does it provide significant advantages over existing approaches?
+* What terminology makes this the most clear?
+* What would you change about the interface?
+* What functionality does it lack?
+* Is anything unnecessary?
View
34 doc/UseCases.mdown
@@ -1,27 +1,39 @@
# Use Cases
-The following use cases are provided to show how Zero will make life better.
+Here are a few sample use cases.
### Logging
-Logging is a classic example of Object-Oriented programming falling short. You want to log everything, or lots of stuff, so you can see where a program breaks. However, log statements clutter up your code significantly. Logging is a common example for Aspect-Oriented programming, which is mostly impossible in AS.
+Logging is a classic example of Object-Oriented programming falling short. You want to log everything, or lots of stuff, so you can see where a program breaks. However, log statements clutter up your code significantly.
+ class LogAllFunctionCalls extends ObjectProxy
+ {
+ override public function callProperty(name:*, ... rest):*
+ {
+ trace("Called: " + name); // use a more sophisticated logger than this
+ object.callProperty.apply(object, [name].concat(rest));
+ }
+ }
+ ...
+ <zero:Connect>
+ <zero:Proxy dependency="*" factory="{LogAllFunctionCalls}"/>
+ </zero:Connect>
+### Switching Configurations at Runtime
+Imagine that you have an application that needs to send requests to a SharedObject when offline, and to some webservices when online. You can easily change the factory for an implementation at the click of a button.
-* When testing, pass in mock implementations to a class
-* Switch to a mock server connection at runtime (a checkbox)
-* 4 different views of a list of users. Invisible ones are inactive and don't receive updates
-* When a module is unloaded it is deactivated and GC'd
-* Give a particular view a unique implementation
-* Give a particular class a unique implementation
-* Give a set of views/classes a unique implementation
-* Proxy all service requests, to convert xml data to strongly typed data before returning
-* Log all requests in the system without requiring the implementations to know about it
+### Deactiviate hidden views
+Normally, if several different views bind to the same data, they continue to receive updates even when inactive or hidden. For example, one view might show the data in a map, and the other in a list. By overriding `set visible` or by listening to `show` and `hide` events, you can easily make a view ignore updates when invisible. This will turn off sub-views as well.
+ connect.disconnect(); // and .connect();
+
+### Translate XML Data to Objects
+
+If you can't use remoting, translating XML to VOs can be annoying. Assume you have a bunch of web services, and you want to abstract out the translation. Instead of making the services decide, you can use a proxy.

0 comments on commit d6dab3b

Please sign in to comment.
Something went wrong with that request. Please try again.