Untangled Developer’s Reference

The mechanism for creating components is the defui macro:

This macro generates a React class as a plain JavaScript class, so it is completely compatible with the React ecosystem.

Notice the use of Object. It indicates that the following method bodies (like in protocols) are being added to the generated class. From an OO perspective, this is like saying \"my widget extends Object\". The render method is the only method you need, but you can also add in your own methods or React lifecycle methods.

If you wish to provide lifecycle methods, you can define them under the Object section of the UI:

Here are some common things you’ll want to know how to do that are different when rendering with Om/ClojureScript:

In order to render components on the screen you need an element factory. You generate a factory with om/factory, which will then act like a new 'tag' for your DOM. We commonly prefix these factories with ui- so we don’t confuse them with query attribute names and other local bindings. If the component is ever to be rendered in a list of adjacent elements then the factory should be given a key function for generating unique React keys on the component.

You can now render a widget inside of any other component using (ui-widget { :prop 1 }).

You access properties in a component using om/props:"

In plain React you store component local state and pass data from the parent to the child through props. You also pass your callbacks through props. In Untangled, we need a slight variation of this because a component can have a query that asks the underlying system for data.

If you complect callbacks and such with this queried data then you run into trouble because the rendering system can re-render a component without going through the parent, meaning that callbacks could be lost.

So, in general props are for passing data that the component requested from a query.

As such, Om has an additional mechanism for passing things that were not specifically asked for in a query: Computed properties.

For your Om UI to function properly you must attach computed properties to props via the helper function om/computed. The child can look for these computed properties using om/get-computed.

Earlier we stress that your components should be stateless whenever possible. There are a few notable exceptions that we have found useful (or even necessary):

All of the standard HTML tags have pre-built React components, accessible from the om.dom namespace.

Specific items in the database are stored in tables. Each table is indexed by a top-level key in the database. Items in the database can refer to other items via a foreign reference, which is formatted as an Ident. It is also legal to have top-level data that is not a table.

The only way to tell a table from a value is by convention. Tables will usually be named in a way that indicates what the primary key of the table is (e.g. by-id), and will be maps of maps. Regular values can be anything, including an Ident.

An Ident is nothing more than a two element vector, where the first entry is a keyword (the "name" of a database table) and the second entry is the ID of the object in that table: [:table-name id]

In the database above you would describe the object in the table as [:table/by-id 1].

Combining regular values, tables, and idents gives you the overall database format which can support any arbitrary graph. The database below has a list of two people (via idents pointing to the people in the table), and each person has a pointer to the person that is their mate. This creates a graph with a loop (when following mate).

The query [:a :b :c] means read the attributes :a :b, and :c from the current object. For example, if this query was against the root of the graph, it would mean the top-level database itself should contain the keys :a, :b, and :c. In the context of a join (or sequence of joins) it indicates attribute reads in that context.

One may query any attribute that makes sense, including an entire table. For example, the query [:people/by-id] against the database above will return:

Joins can be done against reference typed attributes (which essentially means an attribute holding an ident).

Joins are written as a map, where the key is the join point, and the value is a sub-query: [{:my-list [:person/name]}]. If the join point is a vector of idents, then it is a to-many join and the query will result in multiple values. If the join point is a single ident, then it is a to-one join, and the query will result in a single value. In the context of our database above this query should return the names of the people in my list.

The join shown in the prior paragraph against our database above would result in:

Queries can be recursive. In the case where the graph has a normal termination point (such as bullet lists) you can use …​ to indicate a recursive join: [{:list [:item/name {:sublist …​}]}]

This would return a nested map that would follow the graph database links and possibly return something like this:

In our database from earlier, we have a loop. The query engine will automatically detect loops and stop, but you can manually limit the recusion depth using a number instead of …​: [{:my-list [:person/name {:person/mate 1}]}] which would result in:

Union queries are used strictly as the subquery on joins, and are represented by a map. The keys of the map represent the possible choices of subquery to run, and the value represents the subquery.

In the case of a union query one must realize that it is impossible to say what the query means until you look at the actual database. Here is how they work:

The query language includes support for adding a parameter map to every kind of query element. Untangled does not support such parameters on the UI; however, since the same query language is used with respect to the server, it is useful to know how to represent them.

Basically, you surround the query element with parens, and add a map as the second entry.

A property with a parameter: [(:prop { :param 1})] A join with a parameter: [({:prop [:a :b]} { :param 1})]

Again, the the UI cannot make sense of these, but you can write such queries to the server and interpret them there.

This is probably the easiest method to code, and the easiest to keep straight during development because the data is co-located with the queries and UI bits. The only disadvantage is that you cannot easily initialize parts of the graph that do not have a UI representation (which is probably rare).

Implement the InitialAppState protocol on your ui components, and compose the initial state together just like you do with queries:

Compose these all the way to your root component. Untangled will detect state on your root component, and use that to construct the initial application database.

Simply create your database in a map, then wrap it in an atom and pass that via the :initial-state parameter of new-untangled-client. This method is a bit of a hassle to maintain, but allows you to place things in the database that are not (yet) in your UI.

Create a tree of data in a map. Pass it (not wrapped in an atom) to :initial-state. This technique is probably the least useful. It is no more functional than the InitialAppState method, but is harder to maintain.

The following functions are built in (in untangled.client.mutations), and should generally only be used in the context of UI state changes (e.g. folding, checkbox toggle, etc.). They invoke an internal transaction.

The first two take a value or event via a named parameter. For example (m/set-string! this :name :event evt) where evt is a javascript input field event will extra the input’s value and store it in the app db on the correct table entry. These functions are really meant for working with form field state stored in the app database (as opposed to component local state in uncontrolled form inputs).

Untangled provides a multimethod that you can hook your own mutations into.

The three parameters are:

The om/transact! function is used to run a top-level transaction, and can invoke any number of mutations (in order). It must be given a component reference or reconciler (typically the former) and a transaction to run. This looks just like the query notation, but looks to include method calls (which will invoke the multimetod by symbol):

The mutations in a transaction will run in order. Any of them that indicate a remote nature will be sent across the wire to the server.

The is a multimethod for adding in post-mutation handlers that will run after the main mutation. These can be useful when there is a common behavior that should happen after some set of mutations.

Untangled uses Om to manage the UI, and as such the UI refresh story is Om’s story. The basic rule is that when you transact!, the component (subtree) used for the transaction will be refreshed in the UI. This allows you to automatically handle a lot of UI updates without having to think much; however, there are a couple of general rules and tools you can use when this alone is insufficient.

There are a number of convenient things that the network stack does automatically, as shown in the diagram below:

The server-side queries come in a the full EDN send from the client. The Untangled Server code automatically decodes this query and passes it to an Om parser that you define. The basics of processing these queries are covered in the tutorial.

The primary thing to remember is that server query processing functions (which run inside of a parser) should return a map whose only key is :value and whose value is the value for that query attribute/fragment.

Initial data loading can be done in the client by adding a started-callback parameter to the construction of the client. One or more calls to load-data can be used to queue up initial reads from your server, and each of those loads can specify :parallel true to indicate that the loads are not order dependent (if that is indeed true).

Any event (timeout, user interaction, etc) can be used to trigger additional loads. The typical calls used for this are load-data and load-field. The former is completely general and allows for an arbitrary query. The latter is component-centric, and can be used to auto-construct a server query based on the component’s ident, fields, and subqueries.

There are a number of examples in the Untangled Cookbook.

Server mutations are coded exactly like client mutations, but their body does whatever server-side operations you care to do (instead of mutating a client-focused UI database).

There are a few things to understand when implementing a mutation:

You may add a server read to a transaction that also contains a mutation. In this case the mutations and reads will be split, the mutations will run, then the reads will run (ordered using the network queue). Server reads take the form of an untangled/load built-in client mutation. See the getting started video about server basics at roughly 25:20

When using things like websocket server push, timeouts, and manual XHR requests you may have data that you’d like to place in your application’s state that does not arrive through the normal Untangled processing pipeline. In these cases you may use Om’s merge! function or Untangled’s merge-state!. The latter does a bit of common work for you if you can structure the data in a way that looks like the response to an existing query of a UI component with an ident.

Basically, you structure the data to be a tree of maps that could exist in the database for a given component (and children). The merge-state! function will extract the ident from that data, normalize the tree into objects, and merge everything into tables.

Any number of named parameters can be given at the same time to add that object’s ident to other locations in the database.

See the docstring of merge-state! and integrate-ident! in the untangled.client.core namespace.

There are several different kinds of errors that can happen when working with a full-stack application:

Untangled gives you a few mechanisms for dealing with full-stack errors:

Mention gotchas:

The schema support in Untangled Datomic is a fork of Yuppiechef’s Datomic Schema with additions for experimental additional schema enforcements.

The library comes with a function called vtransact. It works just like Datomic’s transact, but enforces the additional schema constraints. This function should be considered experimental. We’d be interested in feedback.