QuickDialog >> JSON Builder

QuickDialog also allows you to easily create iOS dialogs using JSON, and to quickly bind data from objects in the dialog.

Quick demo:

Here’s what a simple dialog, with only one label would look like:

{
    "grouped": true,
    "title": "Hello World",
    "controllerName": "MySampleController",
    "sections": [
        { "title":"Question:", "elements": [
                { "type":"QLabelElement", "title":"Hello", "value":"world!"}
            ]
        }
    ]
}

The code above will create this:

QuickDialog sample

How It Works?

At the heart of all this is the QRootBuilder class. This builder allows you to create the entire QRoot element using the notation above. The JSON text can be included as a file within the project, downloaded from internet or even generated on the fly.

When you instantiate a new controller using the [QRootElement initWithJSONFile:@"file"], the builder automatically creates the QRootElement instance, and all the sections and elements defined. You can define multiple sections, multiple elements per sections and many other things.

Once the root is created, you can simply pass it in the constructor of a controller, or call the [QuickDialogController controllerForRoot:root] method and let QuickDialog generate a controller automatically for you.

Every property available in QuickDialog is also available from the JSON builder. So for example, to initialize a new text entry element, you can simply use:

{  "type":"QEntryElement", "title":"returnKeyType", "placeholder":"EmergencyCall",  "returnKeyType":"EmergencyCall" }

In that case, the returnKeyType will automatically convert the EmergencyCall value into the value UIReturnKeyEmergencyCall. Mappings like this exist for all properties available in the framework.

Controller Actions

In order to execute methods in the controller, each element has a "controllerAction" property, which you set with the selector name you want to call. So for example if you want to show a button that executes the method "handleButton", simply define it like this:

{"type":"QButtonElement", "title":"Button", "controllerAction":"handleButton:"}

Then, in your QuickDialog subclass, you can define the handler as follows:

-(void)handleButton:(QButtonElement *)button {}

When you touch the Button element, the ShowLogin action automatically gets called from the framework.

Other elements have different behaviors. For example, the QBooleanElement executes the controllerAction method when the switch is changed, while de QRadioElement executes it when a selection is made.

Data Binding

A powerful feature of the JSON Builder is being able to not only create elements from a JSON file, but also to bind each element to properties of any object that accepts Key-Value coding, like NSObjects, NSDictionary or even JSON parsed files.

Each section or element by default accepts a “bind” property, which takes a few arguments. Lets look at an example:

{ "type":"QLabelElement", "key":"login",  "bind":"value:username", "title":"Login"}

In the example above, if you simply call [QRootElement initWithJSONFile:@"file"] (where file is the name of a file in your project), the root will be created, and the property of the element called value will be empty. But lets say you have another dictionary:

NSMutableDictionary *dataDict = [NSMutableDictionary new];
[dataDict setValue:@"username" forKey:@"ESCOZ"];
self.root = [[QRootElement alloc] initWithJSONFile:@"file" andData:dataDict];

Now, when the controller is presented, you’ll see that the element “value” field will contain “ESCOZ”. You could also first create the root and then call [root bindToObject:dataDict]. The result would be the same.

This simply allows you to abstract all the form definition out of your code and into a JSON file, and have your Obj-C code deal only with behavior.

A few keywords exist to make it easier to bind the forms with specific structures:

  • bind:“iterate:?” / template: when used in a section, this will automatically iterate over an array of objects from the data object and use the template to render one element for each object.
  • bind:“iterate:?” / template: like the iterate functionality, but works for objects, iterating over each key-value pair.

For more binding examples, take a look at: https://github.com/escoz/QuickDialog/blob/master/sample/Resources/jsonadvancedsample.json

Notes

For more examples on how to use the app, read the code available in the Samples app. There’s a lot of really useful information there.

Hope this quick tutorial will be useful to you. This doc is not supposed to explain all the functionality in the framework, just like the framework is not supposed to be the final solution for all development. My suggestion is for you to use this framework as the starting point for your app, and then change things or add more functionality as necessary. Hope you find it useful.