We will learn how to work with this tool by designing the model for our next app: the category-links application. This app is all about subjects (called categories here) such as HTML5, Dart, Apple, Google, Programming, the economic crisis, and hyperlinks (called links here) to web postings about these subjects. Here are some examples of links for HTML5: www.html5rocks.com, http://diveintohtml5.info/ and http://animateyourhtml5.appspot.com/. Clearly, a category can have multiple links but it may also have none; so, the relationship from category to link is 0..N.

Our app (that will be developed in Chapter 8, Developing Business Applications with Polymer Web Components) will show all categories and the corresponding links for each category. Furthermore, we will be able to edit, remove, and add categories as well as links. But first we will draw a model with two concepts (Category/Link) and one relationship (links). It will look like the following figure:

The graphical model of category-links

The category concept has two attributes: a code (name) such as Dart and a description such as Web programming language, tools, and how to. The code attribute is drawn in italics because it is an identifier and in bold because its value is required. The link concept has the code identifier, the required URL attribute, and an optional description attribute. For example, the URL for Dart could be www.dartlang.org and the description could be Official Google site for Dart. In our model, a link has exactly one category, so a 1..1 relation is applied (this is, a simplification of a more realistic situation where a link could belong to many categories). A relationship between two concepts has two directions (neighbours). The category-link direction, where Link is a neighbor of Category, has a min cardinality of 0 (a category need not have any link) and a max cardinality of N (many). In addition, it has the link's name. The link-category direction has no name. Hence, it will not be represented explicitly in Dart; its min and max cardinalities are in bold and italics. Together with the code, it is the identifier of the link (note that 1..1 is in italics and bold). Within the same category, all links must have a unique code value. Category is the only entry (|| as a door) into the model. This means that the model will have a collection of categories and each category will have a collection of links.

The steps to draw a model are given as follows:

The size of selected boxes may be changed by menu items in the View menu. If you want to create several boxes, double-click on the box tool to stay active. To return to the select mode, double-click on the select tool.

A box item (an attribute of a concept) may be created by entering its name in the attribute field of the toolbar and by using the Enter key.

The first box is a parent and the second box is a child. By default, the parent box has 0..N cardinalities. The min is 0 and the max is N. By default, the child box has 1..1 cardinalities. For more details, see the tiny user guide in the program screen beneath the brown toolbar.

Drawing the model clarifies our thoughts about it, but it won't be of much use if we can't get to code from it. We can export the semantics of a model (only the non-hidden boxes and lines) in the JSON format by clicking on the From model to json button above the JSON panel. After doing this, the JSON text appears in the JSON panel; copy it and save it into a local text file category_links.json. It also works the other way around: the JSON text may be used to recreate the graphical model in magic boxes. Paste the JSON text from a previous model into the JSON panel and click on the From json to model button to visualize the model. For a pretty JSON version of the model, click on the Pretty json button, but only after clicking on the From model to json button. Open the .json file in a text editor and see how the information about our model is contained in it:

{
    "width":990,
    "lines":[
        {
            "box2box1Max":"1",
            "box1Name":"Category",
            "box1box2Min":"0",
            "box2Name":"Link",
            "box1box2Id":false,
            "box2box1Id":false,
            "box2box1Name":"",
            "box1box2Max":"N",
            "box1box2Name":"",
            "box2box1Min":"1",
            "category":"relationship",
            "internal":true
        }
    ],
    "height":580,
    "boxes":[
        {
            "width":120,
            "entry":true,
            "name":"Category",
            "x":125,
            "height":80,
            "y":63,
            "items":[
                {
                    "sequence":10,
                    "name":"code",
                    "category":"identifier",
                    "type":"String",
                    "init":""
                },
                {
                    "sequence":20,
                    "name":"description",
                    "category":"attribute",
                    "type":"String",
                    "init":""
                }
            ]
        },
// omitted analogous entry for link
    ]
}

JSON (JavaScript Object Notation) is a simple text format (easy to be read and written by humans and machines) for representing structured objects and collections, and exchanging data between applications or computers. For example, when a client sends data to or receives data from a server through a web service, this data is often in JSON format. It arose from the open source world, more or less as a competitor to the heavier XML format; but it is used everywhere now. Any production language has special functions (in library dart:convert) to make it easy to use, Dart being no exception. Let us examine a simple JSON example and see how it connects to list and map: look at the BankAccount object from banking_v3.dart (Chapter 2, Getting to Work with Dart):

var ba1 = new BankAccount("John Gates","075-0623456-72", 1000.0); 

It contains three data items: the owner, the number, and the balance of the account. The JSON representation of this data (object) is:

{
    "owner": "John Gates",
    "number": "075-0623456-72",
    "balance": 1000.0
}

In a Dart app, this could be typed as a multiline string (see line (1) in json.dart at codechapter_3). Looking at it from the Dart perspective, this is a map where the names of the object properties are the keys and the values are the map's values; there is a close relationship between objects and JSON (hence the name). This object notation can be nested (for example, the owner could be an object itself with a name, address, and telephone number). To express that there are many of these objects, you can use the [ ] notation, as in the following code snippet:

[
  {
      "owner": "John Gates",
      "number": "075-0623456-72",
      "balance": 1000.0
  },
  {
      "owner": "Bill O'Connor",
      "number": "081-0731645-91",
      "balance": 2500.0
  }
]

This effectively corresponds to a list of maps in Dart.

You can encode a Dart object into a JSON string with the JSON.encode() function from the dart:convert library, for example, the bankAccounts variable in line (2). The resulting JSON can be sent over the network, or it could be the return value of a call to a web service. The Dart object to encode needs to be of the type null, bool, int, double, String, List, or Map; any other object needs to have a toJson() method that is called when encoding. The other way around, decoding a JSON string into a Dart object is done with the JSON.decode method (see line (3) in json.dart):

import 'dart:convert';

var jsonStr1 = '''                                             (1)
{
    "owner": "John Gates",
    "number": "075-0623456-72",
    "balance": 1000.0
}
''';
var jsonStr2 = '''
[
  {
      "owner": "John Gates",
      "number": "075-0623456-72",
      "balance": 1000.0
  },
  {
      "owner": "Bill O'Connor",
      "number": "081-0731645-91",
      "balance": 2500.0
  }
]
''';
var bankAccounts = [{ "owner": "John Gates","number": "075-0623456-       72",
                      "balance": 1000.0 },
                    { "owner": "Bill O'Connor", "number": "081-       0731645-91",
                      "balance": 2500.0 }];
main() {
  // encoding a Dart object (here a List of Maps) to a JSON string:
  var jsonText = JSON.encode(bankAccounts);                    (2)
  print('$jsonText'), // all white space is removed
  // decoding a JSON string into a Dart object:
  var obj = JSON.decode(jsonText);                             (3)
  assert(obj is List);
  assert(obj[0] is Map);
  assert(obj[0]['number']=="075-0623456-72");

  var ba1 = new BankAccount("John Gates","075-0623456-72", 1000.0);   
  var json = JSON.encode(ba1);                                   
}

class BankAccount {
  // other properties and methods ...
  String toJson() {
    return '{"owner":"$owner", "number":"$number", "balance: "$balance"}';
}

In the previous section, data were exported from model concepts in the JSON format and this data can be imported in the domain model framework Dartling (see Chapter 9, Modeling More Complex Applications with Dartling) in order to generate the code for it. We will use JSON again as the format to store data in, or to send data to the server, in some of the forthcoming projects. In the dartlero_tasks project of Chapter 12, Data-driven Web Applications with MySQL and MongoDB, we will read and write the JSON files. For a more in-depth look, refer to http://en.wikipedia.org/wiki/JSON.