Foreword

This book is a gentle introduction to FOAM programming. The book assumes that you have some experience programming in Javascript. Experience with object-oriented languages such as Java or C++ is helpful, but not necessary. Whenever possible, the book teaching FOAM programming through interactive examples. So, let's get to it.

First Steps

Take a look at Your First FOAM Class. Start by just skimming over the whole class. You'll notice that the structure and meaning of the class is quite intuitive. The class has a name; it lives in a package (i.e., a namespace); it has several properties, each with a name and some other information.

From a technical perspective, here the key things to note:

Classes are declared by invoking the CLASS() The global function used for registering a new FOAM class. The function gets passed a class model, i.e., a Javascript object that describes the class. function, and passing it an object that describes the class model.
Every class must have a name, and optionally (though strongly encouraged), a package.
After that, classes have a variety of collections, modelled using Javascript arrays.

Your First FOAM Class

CLASS({
  name: 'Person',
  package: 'foam.sandbox',

  properties: [
    {
      model_: 'StringProperty',
      name: 'firstName',
      label: 'Given Name(s)',
      defaultValue: 'John'
    },
    {
      model_: 'StringProperty',
      name: 'lastName',
      label: 'Surname',
      defaultValue: 'Smith'
    },
    {
      model_: 'DateProperty',
      name: 'dateOfBirth',
      factory: function() {
        return 'January 1, 2000';
      }
    },
    {
      model_: 'IntProperty',
      name: 'age',
      getter: function() {
        // Thanks to André Snede Hansen on Stackoverflow for
        // this procedure. It's not perfect, but close enough.
        var ageDifMs = Date.now() -
            this.dateOfBirth.getTime();
        var ageDate = new Date(ageDifMs);
        return Math.abs(ageDate.getUTCFullYear() -
            1970);
      }
    }
  ]
});

For this simple example, the only collection on the model is properties. It's worth noting that, by convention, this class would live in the file js/foam/sandbox/Person.js; classes modelled in Javascript live in js/, and files are stored according to their package and name.

Let's take a look at the properties. That model_ This is the object key to attach to a model definition to describe the class of FOAM object to build. This can be a string containing a package + model name, or a FOAM Model object. annotation might be the first thing that looks a bit strange. It's kind of like a type annotation, but different. The model_ key denotes the model to use for construcing the current object. In this case, that object is a property, so model_: 'StringProperty' denotes the type of property, not the type of data stored in the property (hence the Property postfix). The rest of the property annotations are as follows:

name The object key for the in-code name of a modelled object. : The name of the property in code; e.g., in a Person method, we may refer to this.firstName.
label The object key for the user-facing name (i.e., text label) of a modelled object. : The text label to use when creating a view of the property in the application's UI.
defaultValue The object key for the default value of a modelled object (usually a property). Note that default values are shared by all instances of an object. As such, most default values that are not of a primitive type should be declared using factory, and not defaultValue. Both defaultValue and defaultValueFn do not emit property change events. : The value to use when no value is provided.
factory The object key for the default factory a modelled object (usually a property). Note that the factory is only invoked if no value is injected at creation time. Factories should return the intended value for the object/property. Also note that factories trigger property change events, whereas defaultValue and defaultValueFn do not. : Like defaultValue, except the provided function is run every time an instance is created with no value provided.
getter The object key for the getter for a modelled object (usually a property). When the object is looked up, the getter will be invoked and its return value will be delivered to the code looking for the object. : A function to run when retrieving the property value; similar to Java convention getSomeProperty(), or the get key used in Javascript's Object.defineProperty().

This example illustrates several powerful features of FOAM. FOAM encourages a declarative style of modelling applications as data. No need for manually coding up getters and setters that procedurally inject defaults, UI labels, or other values for every member variable. You provide a concise description via the class model and the framework wires everything up for you. Notice that the dateOfBirth factory returns a String. However, it's a DateProperty, so is automatically adapted into a Javascript Date object for easy use in our age getter.

Try It Out

Let's try making some changes to Your First FOAM Class.. First we'll add support for middle names. Add a property named middleNames with model_: 'StringArrayProperty'; give it a factory that returns the empty array, a label of 'Middle Name' and annotate it with plural The object key for the plural form of a user-facing name (i.e., text label) of a modelled object. : 'Middle Names'. Don't forget to drop the (s) in the firstName label to keep things consistent.

Now let's make the class behaviour a little more efficient. Right now, the age getter recomputes the age every time. That's silly. The age really only needs to be recomputed when we set the date of birth. This can be achieved using FOAM's support for reactive programming. Cut the age getter to the clipboard. (You may want to paste it somewhere else in case you do more cutting or copying along the way.). Now, on the dateOfBirth property, add postSet The object key for a function to run after the value of a modelled object (usually a property) is set. The function is passed two parameters: the old and new values. : function(old, nu) { this.age = this.computeAge(); }. This callback will fire every time dateOfBirth changes, after the change has taken place. The callback is be passed the old and nu (or "nu") dateOfBirth values.

Before we can declare our efficient age calculating code complete, we need a computeAge method. Beneath the properties array, add a methods array with one element with name: 'computeAge'. Finally, add a code annotation to your one-and-only method and paste the function for the old age getter. That's it! Now, if we ever have code that repeatedly accesses that age property, we won't be slowed down by redundant computations.

Working with the Person Class

Person Class

CLASS({
  name: 'Person',
  package: 'foam.sandbox',

  properties: [
    {
      model_: 'StringProperty',
      name: 'firstName',
      label: 'Given Name',
      defaultValue: 'John'
    },
    {
      model_: 'StringArrayProperty',
      name: 'middleNames',
      singular: 'middleName',
      plural: 'Middle Names'
    },
    {
      model_: 'StringProperty',
      name: 'lastName',
      label: 'Surname',
      defaultValue: 'Smith'
    },
    {
      model_: 'DateProperty',
      name: 'dateOfBirth',
      factory: function() {
        return 'January 1, 2000';
      },
      postSet: function(old, nu) {
        this.age = this.computeAge();
      }
    },
    {
      model_: 'IntProperty',
      name: 'age'
    }
  ],

  methods: [
    {
      name: 'computeAge',
      code: function() {
        // Thanks to André Snede Hansen on Stackoverflow for
        // this procedure. It's not perfect, but close enough.
        var ageDifMs = Date.now() -
            this.dateOfBirth.getTime();
        var ageDate = new Date(ageDifMs);
        return Math.abs(ageDate.getUTCFullYear() -
            1970);
      }
    }
  ]
});

Javascript

console.log.json.put(
  X.foam.sandbox.Person.create()
);

HTML

So we have this Person class. What can we do with it? To start, let's just try instantiating one and printing one to the console. Take a look at Working with the Person Class. Notice that FOAM has decorated console with a JSON-logging object. console.log.json The pretty-printed JSON Sink behaves as a Sink An interface for receiving events related to a DAO. Sinks are notified of new objects coming into the DAO via their put(obj) method; similarly notification of object removal occurs via the remove(obj) method. Sinks are also notified that a sequence of puts is complete via the eof() method, and notified of errors via the error(err) method. Note that Sinks recieve a copy of the object from the DAO; modifying the object passed to the put(obj) or remove(obj) Sink methods will not affect the collection stored in the DAO. . A Sink is anything that receives events from a data storage collection in FOAM. In this case, the collection is messages written to the console. Notice that JSON output to the console is missing several properties (e.g., firstName and lastName). This is because the class stores the default values for these fields, and the current values match the defaults. This optimization is useful to, for example, save bandwidth when sending a large number of FOAM objects over the network; chances are, many of the objects will contain at least some values that match the defaults.

We pass in the return value from X.foam.sandbox.Person.create(). X A FOAM conteXt object. Contexts form a tree of prototypes or sub-contexts. As a result, values from parent contexts appear in the child context, and overwritten values in child contexts do not affect parent contexts. Contexts are intended to avoid polluting the Javascript global namespace and facilitate passing values between related components that do not have immediate references to each other. The unqualified X is the global context, whereas this.X within a FOAM method (or similar) refers to the modelled object's context. FOAM views automatically construct a sub-context for each of their child views. Other sub-contexts must be constructed manually using X.sub(). is the global conteXt object. FOAM context objects are used to encapsulate shared state without polluting the global namespace. In this case, we look up the package-qualified model (foam.sandbox.Person) and invoke the create() The create() method attached to a FOAM class is the class instance constructor function. This method is optionally passed an object containing key/value pairs that describe initial property values for the object. method to instantiate a new Person object. Note that FOAM classes are not constructor functions for use with the new keyword. All FOAM object instances are constructed by invoking create(). The create method can be passed an object containing values for object properties. Try passing an object literal to create() in the Javascript example code; you can set any of the properties listed in the Person Class code snippet.

The HTML portion of this example renders a view of a person. FOAM has a whole suite of views. The default view of a FOAM object is a foam.ui.DetailView, which renders labels and values for each property. FOAM also supports specifying property values as foam-tag attributes, or as tags inside the foam-tag. Try replacing the HTML code with this:

<foam-tag model="foam.sandbox.Person">
  <firstName>James</firstName>
  <lastName>Dean</lastName>
</foam-tag>

Run the code again and you'll see that the view has changed to show you James Dean. FOAM views support two-way data binding, so if you render a view of a FOAM object, the view and the object will stay in sync.

DAOs, Events, and Reactive Programming

Have you worked on a Javascript project where you needed to fetch data over the wire from multiple sources, then wire up a bunch of callbacks to deal with data arriving, network and data extraction errors, and view updates? Then you want to try adding offline support and you have to shim in a mess of IndexedDB callbacks between your network code and your views. What a mess.

FOAM provides several tools for dealing with common application development issues like these. One of the more powerful tools is a unified interface for data collections. We call this interface a DAO Short for Data Access Object. This is FOAM's unified data collection interface. The DAO interface extends the Sink interface. In addition to put(obj), remove(obj), eof(), and error(err), DAOs support find(id) for locating an object by ID, and select(sink, options) for processing queries, and removeAll() for emptying the collection. Of course, in the case of a DAO, put(obj) and remove(obj) are treated as commands to modify the underlying collection, whereas for a Sink, these methods serve as notifications of events occurring on the underlying DAO. Most DAOs also implement convenience functions for attaching query options such as skip(num), limit(num), orderBy(expr), and groupBy(expr). , or Data Access Object. DAOs provide a simple interface for reading from collections (find(id), select(sink, options)) and writing to collections (put(obj), remove(obj), removeAll()). What's more, FOAM provides DAO implementations for a wide variety of data storage modes, including an indexed in-memory store for caching (MDAO), IndexedDB for client-side persistence (foam.dao.IDBDAO), REST for network requests (foam.core.dao.RestDAO), and MongoDB for server code (MongoDAO). Since DAOs are often chained together in common patterns, FOAM also provides a high-level DAO setup interface called EasyDAO.

Your First DAO

Person Class

CLASS({
  name: 'Person',
  package: 'foam.sandbox',


  properties: [
    {
      model_: 'IntProperty',
      name: 'id',
      defaultValue: 0,
      hidden: true
    },
    {
      model_: 'StringProperty',
      name: 'firstName',
      label: 'Given Name',
      defaultValue: 'John'
    },
    {
      model_: 'StringArrayProperty',
      name: 'middleNames',
      plural: 'Middle Names'
    },
    {
      model_: 'StringProperty',
      name: 'lastName',
      label: 'Surname',
      defaultValue: 'Smith'
    },
    {
      model_: 'DateProperty',
      name: 'dateOfBirth',
      factory: function() {
        return 'January 1, 2000';
      },
      postSet: function(old, nu) {
        this.age = this.computeAge();
      }
    },
    {
      model_: 'IntProperty',
      name: 'age'
    }
  ],

  methods: [
    {
      name: 'computeAge',
      code: function() {
        // Thanks to André Snede Hansen on Stackoverflow for
        // this procedure. It's not perfect, but close enough.
        var ageDifMs = Date.now() -
            this.dateOfBirth.getTime();
        var ageDate = new Date(ageDifMs);
        return Math.abs(ageDate.getUTCFullYear() -
            1970);
      }
    }
  ]
});

Person DAO Controller

CLASS({
  name: 'PersonDAOController',
  package: 'foam.sandbox',

  requires: [
    'foam.dao.EasyDAO',
    'foam.dao.IDBDAO',
    'foam.core.types.DAOProperty',
    'foam.ui.DAOListView',
    'foam.sandbox.Person'
  ],

  properties: [
    {
      model_: 'ArrayProperty',
      name: 'people',
      hidden: true,
      factory: function() {
        return [
          this.Person.create({ firstName: 'Margaret', lastName: 'Atwood' }),
          this.Person.create({ firstName: 'Robertson', lastName: 'Davies' }),
          this.Person.create({ firstName: 'Joseph', lastName: 'Boyden' }),
          this.Person.create({ firstName: 'Alice', lastName: 'Munro' })
        ];
      }
    },
    {
      name: 'loadedFromArray',
      defaultValue: false
    },
    {
      model_: 'foam.core.types.DAOProperty',
      name: 'dao',
      factory: function() {
        return this.EasyDAO.create({
          daoType: 'IDB',
          model: this.Person,
          seqNo: true
        });
      },
      view: 'foam.ui.DAOListView'
    }
  ],

  methods: [
    {
      name: 'init',
      code: function() {
        this.SUPER.apply(this, arguments);
        var self = this;
        this.dao.select(COUNT())(function(c) {
          if ( c.count === 0 ) {
            self.people.forEach(function(person) {
              self.dao.put(person);
            });
            self.loadedFromArray = true;
          }
        });
      }
    }
  ]
});

HTML

Take a look at Your First DAO.

Errors, Omissions, and Lies

If you've spent time poking around in the FOAM codebase, you might think that there's more to this FOAM thing than yet-another-Javascript-framework. You'd be right. This section contains some truths about FOAM that are difficult to introduce before you're familiar with the basics of the framework.

What is FOAM, <i>Really</i>?

"FOAM" is, in fact, an acronym. FOAM stands for Feature-Oriented Active Modeller. FOAM is a meta-programming framework for rapid software development. FOAM is implemented in Javascript, but the framework is language agnostic (more on that in the next section). For now, let's spell it out.

F is for feature. In FOAM, a Feature Features are units of data and behaviour, made as small as possible, to facilitate reuse through composition of many features. is a fine-grained unit of encapsulation for data and behaviours. Behaviours are really a special sort of data in FOAM, but let's not get ahead of ourselves. Features should be as small as possible to facilitate flexible composition of features into Models Models are essentially collections of features. FOAM's core model builder supports a variety of standard features, such as properties, methods, actions (user-initiated methods), listeners (pre-bound methods), templates (HTML, CSS, and others), packages (with dependency injection). .

O is for oriented (as in feature-oriented). Not featureful (bloated with features). Not feature-driven (everything's a feature). Feature-oriented. This means that FOAM is strongly encourages encapsulating things into simple features that can be composed to give rise to complex things. Truth be told, FOAM is model-driven, but that's jumping ahead again.

A is for active. To understand what this means, we need to understand FOAM's perspective on data and behaviours. By data we mean represented information (constants, variables, numbers, strings, and the like). By behavoiurs we mean something that's runnable (code, functions, procedures, methods, and so on). FOAM deliberately blurs the line between the two. After all, behaviours need to be represented; so behaviours are simply data represented for a special purpose: computationally manipulating other data. In FOAM, there is virtually no distinction between the two. Code is simply data that can manipulate other data. In this sense, FOAM code changes itself. For example, all FOAM classes -- called Models -- are actually data objects that can be modified and extended at run time.

M is for modeller. As mentioned above, FOAM objects are instances of FOAM Models, which are composed of features. Models are the basic building block for developing FOAM applications, hence the FOAM framework is a toolset for modelling applications. It's worth noting that FOAM makes heavy use of the MVC pattern to structure an environment for modelling applications. We have found this approach to be a flexible and concise means for expressing common patterns that arise in developing applications. If you are unfamiliar with MVC, we encourage you to learn the basics before reading this book. Not only is much of FOAM itself written using MVC, but the toolset encourages developers to adopt this approach when appropriate.

Make sense? Some of these terms are probably unfamiliar, so let's recap. FOAM is a modelling framework for expressing concepts at a high level. These concepts are realized by constructing FOAM Models, which resemble classes in languages like Java and C++. FOAM encourages expressing concepts through small Features that can be combined to give rise to a Model of the concept you have in mind.

When you start building something with FOAM, remember this:

Model the concept. Express it through features.

What FOAM Isn't, <i>Really</i>

FOAM is not a language. Really. FOAM's meta-programming features allow it to interact with various languages and environments, but that still doesn't make FOAM a language unto itself. FOAM code is written in Javascript.

FOAM is not a transpiler. Really. FOAM classes are modelled at a higher level than the language-level. This allows FOAM to generate code in various languages, but that is not what a transpiler does. A transpiler directly and completely simulates all the features of one language in some other language. Many transpilers generate inefficient code not because they are poorly written, but because the source language and target language have radically different opinions on how code should be written. Hence, simulating one language in the other is slow. Modelling classes at a high level, above the language-level, allows FOAM to construct performant code in a variety of environments by being less opinionated about the implementation details than a typical programming language.