Fulcro RAD Developer’s Guide

The standard in RAD is for libraries to define an *-options namespace that defines vars for each configurable key that they support. This allows these vars to be used instead of raw keywords, leading to much easier development.

For example, the attributes namespace defines attributes-options. This namespace includes all of the legal keys that RAD itself defines that can be placed in an attribute’s map. The form namespace defines form-options, etc.

This allows you to write an attribute like so:

which helps you ensure that you’re using a key that has not been mis-typed, and also gives you docstring access in your IDE.

Most of the useful documentation in RAD and libraries should generally be concentrated into these options namespace to assist in ease of use.

Attributes are represented as open maps (you can add your own namespaced key/value pairs). There are a core set of keys that the core library defines for generalized use, but most plugins will use keywords namespaced to their library to extend the configuration stored on attributes. These keys can define anything, and form the central feature of RAD’s extensibility.

Attributes are intended to be capable of completely describing the data model. Database plugins will often be capable of using the attributes to generate server schema. Typical plugins will require library-specific keys that will tell you how to get exactly the schema you want. If you’re working with a pre-existing database you will probably not bother with this aspect of RAD.

Resolvers are part of the pathom library. Resolvers figure out how to get from a context to data that is needed by the client. Attributes describe the data model, so storage plugins can usually generate resolvers (if your schema conforms to something it can understand) and provide a base EQL API for your data model. All you have to do is hook it into your server’s middleware.

Statements about security can also be co-located on attributes, which means that RAD can generate protections around your data model. RAD does not pre-supply a security model at this time, since something that is fully generalized would have the scope of something like AWS IAM, and is simply more open source work than we can afford to provide.

That said, most application can implement something quite a bit more narrow in scope: is the user authenticated, and do they "own" the thing they are trying to read/write. Most systems write these rules around the network operations. In RAD the vast majority of your saves will go through the save middleware, meaning you can concentrate your rules and logic there.

For reads: Resolvers are the unit of readable data in RAD, and you can often place security in the Pathom parser as a plugin.

If you want some guidance on implementing security in RAD, please contact Fulcrologic, LLC for paid help crafting a solution that meets you needs.

The save middleware is simply a function that will receive the Pathom mutation env, which is augmented with ::form/params. Usually you will just compose a set of pre-supplied middleware like so:

Very similar to save middleware, but is invoked during a request to delete an entity.

Form save/delete is run in the context of Pathom, meaning that the env that is available to any plugin is whatever is configured for Pathom itself. All middleware should leverage this in order to provide runtime information.

Database plugins should require that you add some kind of plugin to your parser. Mostly what these plugs are doing is adding content to the env under namespaced keys: database connections, URLs, etc. Whatever is necessary to accomplish the real task at runtime will be in env.

The save and delete middlware that you install in the parser is the logic for accomplishing a save or delete.

The env in pathom is the state necessary for it to do so.

The save middleware is simply a function that will receive the Pathom mutation env. The env will include:

Creating a middleware chain is done as in Ring: create a wrap function that optionally receives a handler and returns middleware. The Datomic wrapper looks like this:

This is very similar to save middleware, but is invoked during a request to delete an entity.

Once you’ve selected the UI plugin for generating UI, you still have a lot of control over the site-specific style of a given control or format via "style". This is nothing more than the ability to give a hint as to the kind of information an attribute represents so that the UI plugin (or your own control) can change to suit a particular need.

For example, an :instant in the database might be a epoch-based timestamp, but perhaps you just care to use it with a constant time (say midnight in the user’s time zone). You might then hint that the attribute should have the style of a "date at midnight", which you could just invent a keyword name for: :date-at-midnight.

RAD supports the ability to set and override a control style at many levels. The attribute itself can be given a style:

and forms and reports will allow you to override that style via things like formatters and field style overrides. See the form-options and report-options namespaces for particular details.

RAD places the definition of controls inside of the Fulcro application itself (which has a location for just such extensible data). The map for UI element lookup looks something like this (subject to change and customization in UI plugins):

The idea is that layouts and controls should be pluggable and extensible simply by inventing new ones and adding them to the map installed in your application.

The map also allows you to minimize your CLJS build size by only configuring the controls you use. Thus a library of controls might include a very large number of styles and type support, but because you can centralize the inclusion and requires for those items into one minimized map you can much more easily control the UI generation and overhead from one location. These are the primary reasons we do not use some other mechanism for this like multi-methods, which cannot be dead-code eliminated and are hard to navigate in source.

UI Plugin libraries should come with a function that can install all of their controls at once.

The report namespace allows you to define (or override) field formatters via report/install-formatter!.

One of the core questions in any relation is: does the referring entity/table/document "own" the target? In other words does it create and destroy it? When there is a graph of such relations this question is also recursive (and is handled by things like CASCADE in SQL and isComponent markers in Datomic).

When there is not an ownership relation one still needs to know if the referring entity is allowed to create new ones (destroying them is usually ruled out, since others could be using it).

In the cases where there is not an ownership relation we usually model it as some kind of "picker" in a form, allowing the user to simply select (or search for) "which" of the existing targets are desired. When there is an ownership relation the form will usually model the items as editable sub-forms, with optional controls that allow the addition and removal of the elements in the relation.

The form management system uses the concept of "subforms" to models all of the possible relationships, relies on database adapters to manage things like cascading deletes, and needs some additional configuration (on a per-form basis) from you as to how relations should be rendered and interacted with in the UI.

The following sections cover various relational use-cases that RAD forms support.

In this case the referenced item springs into existence when the parent creates it, and drops from existence when it is no longer referenced. Database adapters model this in various ways, but the concept at the form layer is simple: If you’re creating it then you’ll be creating a new thing, an edit will edit the current thing, and if you drop the reference you’ll depend on the database adapter’s save logic to delete it.

The form rendering system can derive that it is a to-one relation from the cardinality declared on the reference attribute. The ownership nature is more of a rendering concern than anything: If the new thing is exclusively owned then we know we have to generate a subform that can fill out all of the interesting details.

In this case setting up the relation is nothing more that picking some pre-existing thing in the database. There are several sub-aspects to this problem:

At the time of this writing the answers are:

A demonstration of this case is as follows: Assume we want to generate a form for an invoice. The invoice will have line items (to many, owned by the invoice), and each line item will point to an item from our inventory (owned by inventory, not the line item).

We can start from the bottom. The inventory item itself might have this model in a Datomic database:

followed by the line item model:

note the :line-item/item reference. It is a to-one that targets entities that have an :item/id. There is no Datomic marker indicating that it is a component, so we’ve already inferred that the line item doesn’t own it. But it might also be possible that the line item could be allowed to create new ones. We just don’t know for sure unless we provide more context.

In RAD we do that at the form layer:

Here we’ve generated a normal form. We’ve included the line-item/item attribute, and since that is a ref we must normally include subform configuration; however, we do not intend to render a subform. We can use fo/field-styles to indicate to RAD that a reference attribute will be rendered as a field. In this case the :pick-one field type will look in field-options for additional information. This field type, of course, could also just be set as ::form/field-style on the attribute itself.

The fo/field-options map should contain an entry for each :pick-one field style. The options are:

At this point you can use the LineItemForm and it will allow you to pick from the existing items in your database as long as you have a resolver. Something like this on the server (assuming you installed the attribute to resolver generator in your parser) would fit the bill:

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX WARNING: Book is out of date below this line. See the RAD Demo project for working examples. XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The next case we’ll consider is the case where a form has a to-many relationship, and the items referred to are created (and owned) by that parent form. This case uses a normal form for the to-many items, and is pretty simple to configure. Say you have accounts, and each account can have multiple addresses (the addresses are not globally normalized but instead just owned by the account, since they are hard to globally normalize).

The addresses attribute looks like you’d expect:

and the UI for an AddressForm might look like this:

The AccountForm would then simply use that AddressForm in a subform definition like so:

Here the subform information for the :account/addresses field indicates:

So our form shown above does not allow the user to delete the address if it is the only one, and prevents them from adding more than 2.

A purely computational (display-only) attribute is simple enough to declare:

Such a field will show as a read-only field (formatted according to the field style you select). The function is supplied with the form rendering env (which includes the current form props) and the attribute definition of the field that is changing. The return value will be the displayed value, and must match the declared type of the field.

These attributes will never appear in Fulcro state. They are pure UI artifacts, and recompute their value when the form renders.

You actually have access to the entire set of props in the form, but you should note that other computed fields are not in the data model. So if you have data dependencies across computed fields you’ll end up re-computing intermediate results.

Derived fields are attributes that are meant to actually appear in Fulcro state, and can also (optionally) participate in Form I/O (i.e. be saved to your server database). Derived fields are meant to be very easy to reason over in a full-form sense, and are meant to be an easy way to manage interdependencies of calculated data.

Each form can set up a derived field calculation by adding a :derive-fields trigger to the form:

A derive-fields trigger is a referentially-transparent function that will receive the tree of denormalized form props for the form, and must return an optionally-updated version of that same tree. Since it is a tree it is very easy to reason over, even when there is nested data that is to be changed.

If a master form and child form both have derive-fields triggers, then the behavior is well-defined:

Note: Deeply nested forms do not run :derive-fields for forms between the master and the form on which the attribute changed.

Assume you have an invoice that contains line item’s that use the above form. The :invoice/total is clearly a sum of the line item’s subtotals. Therefore the invoice (which in this example is the master form) would look like this:

Now an attribute change of the item on a line item will first trigger the derived field update of subtotal on the LineItemForm, and then the master form’s derived field update will fix the total.

The next dynamic support feature is the :on-change trigger. This trigger happens due to a user-driven change of an attribute on the form. Such triggers do not cascade. This trigger is ultimately driven by the form/input-changed! function (which is used by all pre-built form fields to indicate changes).

The :on-change trigger is implemented as a hook into the Fulcro UI State Machine that is controlling the form, and must be coded using that API. The Fulcro Developer’s Guide covers the full API in detail. The most important aspect of this API is that it is side-effect free. You are passed an immutable UISM environment, and thread any number of uism functions together against that env to evolve it into a new desired env, which you return. This is then processed by the state machine system to cause the desired effects.

Code for UISM handlers generally looks something like this:

In RAD Forms, the on-change handler is passed the UI State machine environment, along with some other convenient values: the ident of the form being modified, the keyword name of the attribute that changed, along with that attribute’s old and new value.

In our Line Item example we allow a user to pick an item from inventory, which has a pre-defined price. Users of the invoice form might need to override this price to give a discount or correct an error in pricing. Therefore, each line item will have a :line-item/quoted-price. Every time the user selects an item to sell on a line item we want push the inventory price of the item into the item’s quoted-price. We cannot do this with the derived-fields trigger because that trigger does not know what changed, and we only want to push the item price into quoted price on item change (not every time the form changes). This is a prime use-case for an :on-change, and can be coded like this:

The :on-change triggers always precede :derive-fields triggers, so that the global derivation can depend upon values pushed from one field to another.

The standard way to represent time is as an offset from the epoch in milliseconds. This is the de-facto representation in the JVM, JS VM, transit, and many storage systems. As such, it is the standard for the instant type in RAD. User interfaces also need to localize the date and time to either the user or context of the form/report in question.

There are standard implementations of localization for js and the JVM, but since we’re using CLJC already it makes the most since to us to just use cljc.java-time, which is a library that unifies the API of the standard JVM Time API. This makes it much simple to write localized support for dates and times in CLJC files. To date we are avoiding the tick library because it is not yet as mature, and is overkill for RAD itself (though you can certainly use it in your applications).

At the time of this writing RAD supports only the storage of instants (Java/js Date objects), and requires that you select a time-zone for the context of your processing. The concept of LocalDate and LocalTime can easily be added, but for now the style of the UI control determines what the user interaction looks like. This means that when you ask the user for a date, it will be stored as a specific time on a specific date in a specific time zone.

For example, an Invoice might require a date (which could be in the context of the receiver or the shipper). The "ideal" solution is to do time zone offset calculations, but a reasonable approximation might be to just store the date relative to noon (or midnight, etc.) in the time zone of the user. This can be supported with a simple UI control style:

Of course you can provide your own style definitions for controls, and you can also choose to store things like "Local Dates" as simple strings (or a LocalDate type if your storage engine has one) in your database if you wish to completely avoid the time zone complication. At that point you could also add Transit support for local dates to your network layer, and keep those items in the correct type in a full-stack manner.

EDN and Transit already support the concept of representing and transmitting arbitrary precision numbers. CLJ uses the built-in BigDecimal and BigInteger JVM support for runtime implementation and seamless math operation. Unfortunately, CLJS accepts the notation for these, but uses only JS numbers as the actual runtime representation. This means that logic written in CLJC cannot be trusted to do math.

In RAD we desire the representation on the client to be closer to what you’d have on the server. Most applications have large amounts of their logic on the client these days, so it makes no sense, in our opinion, to simply pass numbers around as unmarked strings and expect things to work well.

Therefore RAD has full-stack support for BigDecimal (BigInteger may be added, as needed). Not just in type, but in operation. The com.fulcrologic.rad.type-support.decimal namespace includes constructors that work the same in CLJ and CLJS (you would avoid using suffixes like M, since the CLJS code would map that to Number), and many of the common mathematical operations you’d need to implement your calculations in CLJS (PRs encouraged for adding ones you find missing).

Working with these looks like the following:

TODO: Need math/with-precision instead of just an arg to div.

Of course you can use clojure exclusions and refer to get rid of the math prefix, but since it is common to need normal math for other UI operations we do not recommend it.

Fields that are declared to be arbitrary precision numerics will automatically live in your Fulcro database as this math/numeric type (which is CLJ is BigDecimal, and in CLJS is a transit-tagged BigDecimal (a wrapped string)).

The JS implementation is currently provided by big.js (which you must add to your package.json). Most of the functions will auto-coerce values, and you can also ask for a particular calculation to be done with primitive math (which will run much faster but incur inaccuracies).

You can ask for imprecise (but fast) math operation (only really affects CLJS) with:

which will run much faster, but you are responsible for knowing when that is safe. This allows you to compose functions that were written for accuracy into new routines where the accuracy isn’t necessary.

RAD’s built-in support for BLOBs requires that you define a place in one of your database stores to keep a fingerprint for the file. RAD uses SHA256 to generate such a fingerprint for files (much like git). The fingerprint is treated as the key to the binary data in the store where you place the bytes of the file. This allows you to do things like duplicate detection, and can help in situations where many users might upload the same content (your regular database would track who has access to what files, but they’d be deduped).

Forms need to know where to upload the file content. Fulcro requires an HTTP remote for file upload, since it sends the file through a normal HTTP POST. If your primary remote is HTTP, then your client needs nothing more than the standard file upload middleware added to the request middleware on the client, and file upload middleware on the server that can receive the files.

The general operation of file support in RAD is shown in the diagram below. As the user edits a form with a file upload control they can choose local files. RAD generates a SHA for each file, and begins uploading it immediately (tracking progress and disabling save/navigation until the upload is complete). The SHA is stored in the form field (and is what you’ll have in your database as a key to find the binary data later).

The file is saved in a temporary store (usually a temporary disk file).

Once the file(s) is/are uploaded then the form can be saved. When the user does this the SHA comes across in the save delta and middleware on the server detects it. This triggers the content (named as the SHA) to be moved from the temporary store to a permanent store. Of course the SHA is saved in the entity/document/row of your database (along with other facets of the file you’ve set up, such as user-specified filename).

The permanent store is configured to understand how to provide a URL (properly protected) to serve the file content, allowing the form, reports, and other features of your application to provide the file content on demand.

Since RAD controls the rendering of the file in forms it needs to know how to group together attributes of a file so that it knows which is the filename, which is the URL, etc. RAD does this by keyword "narrowing", our term for the process of using the current attribute’s full name as a namespace (by replacing / with .) and adding a new name.

Thus, if you define a blob attribute :file/sha then the filename attribute will be assumed to be :file.sha/filename by the auto-generated UI in RAD. You can use rewrite middleware and custom resolvers if you want to save it under a different name in your real database, but it is easiest in greenfield projects just to adopt the convention.

There is a special macro in the blob namespace defblobattr that should be used to declare a BLOB-tracking attribute in your database. It ensures that you supply sufficient information about the attribute for uploads to work correctly.

A sample file entity (backed by Datomic) might be defined like this:

The defblobattr requires you supply a keyword for the attribute, the name of the permanent store for the content (:files in this example), and the name of the Fulcro client remote (:remote in this example) that can transmit the file bytes.

You must configure an HTTP remote on the client that includes the Fulcro file upload middleware. This is covered in the Fulcro Developer’s guide, but looks like this:

The server setup needs several things.

First, you need to define a temporary and permanent store. RAD requires a store to implement the com.fulcrologic.rad.blob-storage/Storage protocol. The temporary store can just use the pre-supplied transient store, which uses (and tries to garbage collect) temporary disk files on your server’s disk. RAD’s transient store requires connection stickiness so that the eventual form save will go to the save server as the temporary store. If that is not possible in your deployment then you may wish to use your permanent store as the temporary store and just plan on cleaning up stray files at some future time.

Once you’ve defined you two stores you can add the blob support to your Ring middleware and as a plugin to your Pathom parser.

There are two parts to the Ring middleware, and one is optional and is only necessary if you plan to serve the BLOB URLs from your server.

You must also install plugins and resolvers to your parser:

The blob plugin mainly puts the temporary store and permanent store(s) into the parsing env so that they are available when built-in blob-related reads/mutations are called. The BLOB resolvers use the keyword narrowing of your SHA attribute and the env to provide values that can be derived from the SHA and the store (i.e. :file.sha/url).

A file is tracked by a SHA. Therefore you can support a fixed number of files simply be defining more than one SHA-based attribute on an entity/document/row of your database. You can also support general to-many support for files simply by creating a ref attribute that refers to a entity/row/document that has a file SHA on it.

Each set of UI rendering controls will have one or more ways of rendering and dealing with file uploads. See the documentation of the rendering system you’ve chosen to see what comes with it. Of course, you can always render exactly what you want simply by following Fulcro and RAD documentation.

You can use the blob/upload-file! function to submit a file for upload processing. The system will automatically add a status and progress attribute to the in-memory entity in your Fulcro client db.

Assuming this represents the UI instance that has the file upload field, the call to start an upload is:

If your blob-attribute had the keyword :file/sha then you’d see a :file.sha/progress and :file.sha/status appear on that entity and update as the file upload progresses. Saving the form should then automatically move the file content (named by SHA) from temporary to permanent storage.

The Storage protocol defines a blob-url method. This method is under the control of the implementation, of course, and may do nothing more than return the SHA you hand it. You are really responsible for hooking RAD up to a binary store that works for your deployment. The built-in support assumes that you’ll serve the file content through your server for access control. The provided middleware simply asks the Storage protocol for a stream of the file’s bytes, and serves them at a URI on your server.

Thus, you might configure your permanent blob store to return the URL /files/<SHA>, and then configure your Ring middleware to provide the correct file when asked for /files/<SHA>. This is what the middleware configuration shown earlier will do.

When you define a form using defsc-form you end up creating a routing target in Fulcro’s dynamic routing system. The :will-enter handler is automatically supplied for you, and runs the various operations necessary for starting up a state machine on the form and completing the route.

RAD’s form system has an optional routing middleware system that can be configured to do client-side authorization tasks that can prevent (or redirect) routing. This middleware has access to the state map, the target form. and the target route. Individual forms can override this middleware on a per-component basis with the ::form/routing-middleware key.

You can add middleware to the pathom parser in RAD that analyze the overall query or mutation being processed, and modify the outcome in any way. This is a standard Pathom feature.

Auto-generated resolvers and mutations use …​

Of course when you hand-write a resolver or mutation you can leverage attribute definitions, the env, and anything else to determine the validity of the operation in question.

Individual fields are represented by one (or a small group) of attributes. Those attributes are a great location to place things like data specifications, user-facing validation checks, etc.

The form save mechanism in RAD has a standard server-side entry point that splits off an incoming save across any number of low-level database adapters. You can install middleware that sits between these two (the entry point and actual save). Such middleware can redact information, reject invalid requests, verify security, etc.