Some things may not work properly without JavaScript. Please turn on JavaScript.

Quick Start Guide

Getting started is always the hardest part. Staring at a flashing cursor stuck at line 1 is enough to have even the most seasoned developer procrastinate. Fortunately, with Cyntaxic you can have the framework tracing out its version number in a matter of ten minutes.

Keeping It Actually Simple

You may have heard of the KISS principal before. It is an acronym that stands for Keep It Actually Simple, Stupid. Cyntaxic takes it one step further with the KIASS principal, which stands for Keep It Actually Simple, Stupid. There are other frameworks out there that claim to be simple. Based on their claims, you download the framework and start looking through the documentation. After spending hours struggling, you start to see that it isn't simple for you. Now you feel terrible because you are trying to wrap your head around some egghead's notion of the word simple. What's simple for them just isn't simple for you.

That brings us to what is your type of simple. First, we should define who you are. You are obviously not an egghead, but you are also not stupid. You most likely have some other skill that is not programming, but still it lead you down the developer's path. Most likely, you are a designer at heart with a need to do some programming. You are past the days of copy and paste coding and you can get in there and write the code yourself. You have done some reading or at least heard of MVC and using the MVC design pattern in application building. The applications that you build may not need to be massive engineering marvels, but they need to be more sophisticated than gotoAndStop. If this sounds familiar, than Cyntaxic is the framework for you. Cyntaxic was designed with the programming middle class in mind.

Getting Started

If you used the boilerplate utility then these steps have already been completed for you automatically. Just build your application! If not, feel free to read on.

Getting started is always the hardest part. Staring at a flashing cursor stuck at line 1 is enough to have even the most seasoned developer procrastinate. Fortunately, with Cyntaxic you can have the framework tracing out its version number in a matter of ten minutes. First, setup your package structure. At bare bones it should consist of packages named model, view and controller. Usually these packages would be contained inside a reverse domain package structure. Once the package structure is set, it is time to start extending the Cyntaxic base classes.

The classes CynModel, CynController, CynComposite and CynComponent are all abstract classes and are not meant to be used directly. As ActionScript has no real abstract classes, Cyntaxic enforces abstract classes with a little trick. Extend CynModel and CynController placing those files in their respective packages. By convention, name these subclasses Model and Controller. Your model and controller should be setup as singleton classes with a static method returning the single instance of the class.

Once the model and controller are setup, it is time to setup the document class. The document class serves as a boot point for the application. Depending on whether your application is pure ActionScript or Flex, the boot process will be slightly different. For pure ActionScript, initialization should happen after loaderInfo has completed to ensure that the FlashVars have loaded. For Flex the boot process is broken into 2 steps. First run Cyntaxic.init passing in only model and the controller on the initialize event. Then, get the rest of the boot process on the applicationComplete event passing in the document class and optionally the properties object.

Once the framework has been initialized, the first view can be created. Creating views is just about the same as setting up the model and the controller. Just extend the CynComposite class if your view will have children that are views or the CynComponent class if your view won't have any child views. Once this is created, add that root view as a child of your document class.

Lastly, and optionally, create a handles class to hold all your function strings. This class would usually sit in the packages on the same level as the model, view and controller packages. This class just holds static constants with the exact string values of functions that will be called by the execute and notify methods in the controller. It is very important that the strings are exactly the same casing as the actual function names in the controller. That is pretty much all for the handles class. Now that you have your model, your controller, a root view and a handles class to hold all your function calls, you are ready to get started.

Working with Flex

Unlike pure ActionScript applications, the Flex framework is, well, a framework. As a framework, Flex has its own concept of how to go about handling application flow. Flex has MXML files for views and skinning views. Flex has data binding to update views when events concerning data occur. For the most part, Flex is a solution in itself except that Flex is not an organized MVC framework. If MVC is your preferred way of working, you might have noticed that there is something missing from the MVC paradigm. Namely, it is missing the C. Without a controller, code for processing is left to be in the view itself. This conflicts with the SoC or Separation of Concerns rationale. Using an MVC framework like Cyntaxic with Flex adds another layer of organization.

A big difference with working with Flex as opposed to pure ActionScript is that you cannot have CynComponent or CynComposite as your base classes for MXML views. The solution has for this is to make a proxy class to handle addition and removal of views. The CynViewProxy class can make any class function as a CynView. The CynViewProxy class has two static methods, CynViewProxy.add and CynViewProxy.remove. These methods also have aliases in the the Cyntaxic class, Cyntaxic.addCynViewProxy and Cyntaxic.removeCynViewProxy. All these methods receive one argument, the class that you wish to add or remove from being a view. If you used the boilerplate utility then an include file using CynViewProxy.add and CynViewProxy.remove has already been created and can be included for any view created. This include file also gives access to debug and describe methods just like an actual extended CynView.

One of the other big differences about using Flex is the boot process. Flex has a number of events that fire when the application is starting. In most of those Flex events, the document class root and stage object among other display objects are not avaliable. For this reason, Cyntaxic allows you to break down the framework initialization into two steps. The first method to call is Cyntaxic.init. This should be called on the Flex initialize event. You only need to pass the model and controller for this method. The next part of the framework dealing with display objects can be called on the Flex applicationComplete event. On this event call the Cyntaxic.initDocument method passing in the document class and optionally the properties object for framework configuration.

The CynModel class works well with Flex. Because CynModel extends the EventDispatcher class it is compatible with Flex's data binding. Flex has some powerful data binding tools for connection to web services for multiple types of servers. If your needs are complex, use this for getting information from external sources. If you want something simple, use the get and post methods in CynModel which handle drop dead simple calls to external data.

Working with CynModel

The CynModel is basicially just a class designated for the storage of application data. The CynModel class has a describe method so all of the application data at any given state of the applcation can be describe as a valid JSON string. CynModel uses the helper classes, DataCall and DataCallEvent for its get and post methods. To start using the CynModel, extend it with your own model class.

Working with CynController

The CynController class is a class designated for the processing and delegation of the application. It is the controller's responsibility to get data from the model, process it and notify the views that need to be updated. The CynController class has two basic methods to achieve that, execute and notify. The execute method is called when some processing by the controller needs to take place. The execute function takes 2 parameters, handle and vo. The handle is the string value of the function to be called in the controller and the vo is the value object that is being passed to that function. The notify method has the exact same parameters except the handle is a string equivalent of the function name to be called on each view that should be notified. To start using the CynController, extend it with your own controller class.

Working with the CynView Subclasses, CynComposite and CynComponent

Both the CynComposite class and the CynComponent class extend the CynView class where they inherit view functions. Use the CynComposite class if your view will have children that are views. The CynComposite class has methods like add, addAt, remove, removeAt, destroy and destroyAt for view display management. Use the CynComponent class if your view won't have any child views. Both classes have reference to the instance of CynModel and CynController in two protected properties, cynModel and cynController. These should be casted to your extended controller and model classes in the constructor for full code completion capabilities.

Both CynComposite and CynComponent can be described. The describe method on views functions as an opt in to describe properties. The CynView class has a property called describeProperties which is an array of properties to be described. You must add or remove strings named the same as the property to get describe output. This is used as these objects extend Sprite and DisplayObject which can have hundreds of properties and can cause major slow down in the application when being described.

The CynView classes have the debug method available to them as a protected function. They both also have a supressDebug property that can be used to suppress debug output per instance, simply set the suppressDebug property to true.

Using Handles

The handles class is completely optional. It is helpful in keeping a single place for all your function strings. This class just holds static constants with the exact string values of methods that will be called by the execute and notify methods in the controller. It is very important that the strings are exactly the same. This includes casing. The handle string and function names in the controller and views has to be identical.

Working with the CyntaxicVO

The CyntaxicVO class is used as an extension point for all value objects in the framework. These value objects are used in every controller and view method as the one and only parameter passed. You can use dynamically append properties to the CyntaxicVO object by passing an object with properties on it to the constructor. In most cases, it is best to create strongly typed value objects with specific properties for code completion. This functionality can be inherited by a subclass by simply making it dynamic and by passing the data parameter to the superclass with super(data). The CyntaxicVO can be described using its describe method.

Using the describe Method

Throughout the framework on views, value objects and the model there is a method called describe. The describe method is used to create a valid JSON string to describe an object. The thinking behind this is that typical trace output for an object is pretty limited, just outputting [object Object] or Flex's mile long NameUtil output. If you couple this describe method with the debug method, it allows for a readable and portable description of the object being described. By default the output is collapsed, but using a JSON validator site like jsonlint.com, you can easily format it to introspect the object without using the debugger. If you pass the value false to the method, the JSON string will output formatted. This JSON output may be even useful for converting a value object into a structured JSON format to send to a server using POST. For unsupported object types that don't translate into JavaScript or JSON such as Function are described as a string literal.

The describe method on views are a little different as it is an opt in to describe properties. The CynView class has a property called describeProperties which is an array of properties to be described. You must add or remove strings named the same as the property to get describe output. This is used as these objects extend Sprite and DisplayObject which can have hundreds of properties and can cause major slow down in the application when being described. To prevent stack overflow there is a cap of 100 levels of description. When this cap is reached an error in JSON format is described. It is recommended when going live with the application to set Cyntaxic.debug to false to cut down on describe overhead.

The Cyntaxic class has a property called advancedDescribe, when set to true globally makes all describe calls output a more descriptive JSON object. Advanced describe wraps the object being described in an object that gives the fully qualified class name and base class name as well as the length if the object being described is an array.

Using the debug Method

The debug method is nothing more than the trace command that outputs the name of the object that is doing the debugging. The debug method is best used along with the describe method. The CynController class and the CynView classes have the debug method available to them as a protected function. They both also have a supressDebug property that can be used to suppress debug output per instance, simply set the suppressDebug property to true.

Cyntaxic Properties Object

On both the Cyntaxic.init and Cyntaxic.initDocument methods the final parameter is a properties object to setup the framework. Some valid properties are advancedDescribe, fullScaleFlash, debug, cmLove and contextMenu. You can check the documentation on the Cyntaxic class to see all available options. The possible options are properties written in lowerCamelCase. Properties written as constants are reserved by the class and will throw a CynError if attempted to be set more than once.

Utility Classes

The utility classes or Cyntils are a collection of static classes for common coding tasks. Each method returns some type of information, usually the information returned is a primitive type such as String, Boolean, int or Number. When the information returned is more complex like with CynValidate with passFail set to false or some CynColor methods, a Result object is returned with the proper information.

Using Graphical Assets and the init Method

Cyntaxic is setup to work nicely with grapical assets in SWF or SWC files. In a situation where you need to instantiate a graphical class, the constructor cannot be used because you didn't write the class; it is a graphic. The workaround is to use a CynView subclass to extend the graphical class and then to use the init method as the constructor. The init method returns the view itself to make it chainable. So, the init method can be chained directly to the constructor function on the same line to concisely do the same thing as a regular constructor.

Working with Pseudo Abstract Classes

The classes CynModel, CynController, CynComposite and CynComponent are all abstract classes and are not meant to be used directly. As ActionScript has no real abstract classes, Cyntaxic enforces abstract classes with a little trick. You as a user of the Cyntaxic framework don't need to know how it works, just what you need to do to satisfy the requirement. It is really easy to do, just add super(this) to the constructor of the class you are extending. If you do not satisfy this requirement a CynError will be thrown. If you see this error just add super(this) to the constructor of the offending class and the error should be gone.