Newt’s newt model

The model action does most of the heavy lifting short of actual code generation. If you save the model(s) you will cause the models property to be populated but also related propertes under the routes and templates properties. Like newt config if you do not provide a file name the command will assume you’re working with “app.yaml”.

It is possible to run newt model before running newt config. Whichever order you run them in they both need to be run before you try newt run.

Modeling your data

The newt model lets you add, modify or remove a data model from your Newt YAML file. Like the “config” action it will provide you with the opportunity to review changes and before exiting saving the changes to disk.

The modeling process is more complex than the “config” action. You may have model than one model, you may have many properties per model. As a result the dialog between you and newt model is separated into stages. First you are asked to manage the model(s) by either adding, modifying or removing them. When you add model it creates an empty model. You can then “modify” the model which in turns allows you to add or remove a list of model properties and elements. Each model will have at least one element, the “oid” property. “oid” stands for object indentifier. This is a unique identifier. When the SQL is generated it will be set as a primary key. This is one place where you may want to modify the generated SQL. There are lots of choices for unique identifiers, e.g. auto increment values, UUID and other shorter indentifiers more URL friendly. If you don’t want to use “oid” as your object identifier you can remove it and designate another element as being the primary key. At least one element in your model should be the primary key to avoid problems.

NOTE: You can press “control C” to quit the “config” action without writing the YAML to disk.

Let’s step through how the dialogs and menus are organized.

Top level dialog, “Manage Models”

The top level dialog is the “manage models” (note the plural). It has a menu displayed after any models listed. The dialog’s menu lets you perform one of four different actions. Add a model, modify a model, remove a model and quit. The quit action at the top level will exit the program if you don’t need to save changes. The top level model will list any models hat are defined already. By default it is an empty list.

When you choose “add model” you will then be prompted for a model identifier. This identifier must start with an alphabetical character followed by one or more alphanumeric characters or underscore characters. E.g. “my_bird_list” is an example of a valid model name while “2bots!” is not a valid name. The reason for these restrictions is the model id is used when generating SQL as well as when we generate Mustache Templates. An example is in Postgres the model id will be used as the Postgres table name. Model names must be unique inside your application for the same reason that Postgres tables require uniqueness in a given Postgres database.

The added model will then appear in your model list. An added modify will be empty. You should proceed to “modify” that model after you’ve added.

Models may also be removed. You may have as many models as you want. Each will wind up with their own set of routes and templates that will be used with the generated configuration, SQL and set of Mustache templates.

2nd level dialog, “Manage model”

The second level menu has a title like Manage <MODEL_NAME> model where <MODEL_NAME> is the name of the model you’re modifying. You should update the description with a brief explanation of what the model’s purpose is. This is used in the comments of the generated SQL.

The dialog’s menu choices are description, elements and quit. The elements are the important part of your model. If you think of your model as a table elements would be columns. In object oriented jargon these are usually called attributes or properties. The elements describe a key/value relation between an element’s id and value stored.

The quit menu option exists the manage model dialog and takes you to the top level dialog, “manage models”.

3rd level dialog, “Manage Elements”

If you have selected elements from the 2nd level dialog you will find your self in the “manage element” dialog. This dialog lists any elements that may have been defined. By default their is a “oid” unless you’ve removed it. Like with the top level “manage models”. Managing elements is much like managing models. The menu indicates you can add, modify, remove and quit. Quit, just like the other dialog, lets you leave the current diolog taking you to the second level dialog, “Manage Model”. Add will let you add elements, remove will remove the elements. Modify will let yo modify a specific element.

Like with models you first add an element then you modify it. The defaults are probably not what you want unless your form is very simple.

4th level dialog, “Manage Element”

When you select modify element from the 3rd level dialog “Manage Elements” you can now define the specifics of the element. The menu in this dialog as the following actions type, pattern, attributes, label and primary key.

Conceptually you can think of an element as an HTML5 native input element. There is a loose corrolation in the attribute names.

[t]ype

Sets the element type. The types are the same types supported by HTML5 native elements with the exception of “file”. Additionally there are some library specific elements that leverage the “pattern” attribute such as orcid and issn.

[l]abel

This is holds the value of any associated HTML label element linked to the input element through the set attribute and input’s id attribute.

[p]attern

This is a regular expression used for browser side validation and when generating SQL to validate submitted objects.

[a]ttributes

This holds an HTML5 specific attributes you may wish to include, e.g. name, placeholdertext, title

[o]bject key

This holds true or false that this element is used as the primary key of the modeled object. The dialog shows the current state. Selecting this menu item toggles it.

An elemenet’s properties have a loose corrolation with the native HTML5 input elements attributes. E.g. id, type, pattern are based on the HTML5 input element attributes. Primay key is bool value used when generating SQL to indicate that this element should map to the primary key of the model. You can have one primary key per model.

The types of elements are taken directly from what can be expressed in native HTML5 elements excluding the “file” type. E.g. text, textarea, select, checkbox, radio, button, date, time, datetime, email, phone, and url. Additional are library oriented types like issn and orcid that use the “pattern” attribute for client side validation. The element types infer the SQL columns modeled your Newt application.

The attributes menu option lets you add any additional HTML specific attributes you may need. E.g. required, class, placeholdertext, title.

The select element type triggers an additional dialog since it the HTML of the select element has “option” elements as children.

5th level dialog, “Manage Options”

This menu lets you provide a value, label and default flag for the options in the select element. The dialog’s menu lets you add, modify, remove and quit.

When you add an option you will be prompted for a value, a label and optional default status. The value will get converted to lower case. The label will be left as you typed it.

When you modify or remove an option you do so by provided the number of options listed since options values are not necessarily unique.

Walking through the process

Adding a model

Let’s fireup newt model and add a model called “garden”.

newt model

You should now see the following menu.

Enter menu letter and id


Menu [a]dd, [m]odify, [r]emove, [q]uit (making changes)

Type the letter “a” and press the enter key.

You will see

Enter model id to add:

Enter “garden” without the quotes and then press the enter key.

You should now see

Enter menu letter and id

    1: garden

Menu [a]dd, [m]odify, [r]emove, [q]uit (making changes)

You’ve successfully created an empty model called “garden”.

If you want to see what is in the model or to modify it you would select “m” for modify model.

Modifying our “garden” model

The modify model menu will show you a list of properties associated with the model. When you created our “garden” model it automatically created an “oid”, object identifier, element in the model. We’re going to get rid of this and create a new one.

// FIXME: NEed to finish tutorial …