Fulcro RAD Developer’s Guide

RAD defines a few central component types, with the following generalized meaning:

As you can see there is some overlap in forms and reports. A read-only form is very much like a report, and a report with sufficient "row actions" (i.e. each cell can be clicked to edit) can behave very much like a form.

See the README files on the various libraries and plugins you use for the correct set of dependencies. The current version of the demo project will have an up-to-date list. The most complex dependency is on js-joda for date/time consistency. The latest versions of RAD do not require a js-joda locale, but versions prior to 1.0.28 did.

If you use the isomorphic math support you will also need big.js. If you do not use big decimals, then you can safely ignore that ns and dependency.

Of course if you target the web then you’ll also need things like react, react-dom and any other UI libraries it might use, etc.

Fulcro encourages the use of a graph-based data model that is agnostic to the underlying representation of your data. This turns out to be a quite powerful abstraction, as it frees you from the general limitations and restrictions of a rigid class/table-based schema while still giving you adequate structure for your data model.

The central artifact that you write when building with RAD is an attribute, which is an RDF-style concept where you define everything of interest about a particular fact in the world in a simple map. The only two required things that you must say about an attribute are its distinct name and type. The name must be a fully-qualified keyword.

The namespace should be distinct enough to co-exist in the data realm of your application (i.e. if you are working on the internet level you should consider using domain-style naming). The type is meant to be an open concept, but usually you will want to make sure that it is supported by your database back-end and possibly your rendering plugin. The type system of RAD is extensible, and you must refer to the documentation of your selected database adapter and rendering layer to find out if the data type is already supported. It is generally easy to extend the data type support of RAD at extension points in these plugins.

A minimal attribute will look something like this:

The defattr macro really just assigns a plain map to the provided symbol (id in this case), but it also ensures that you’ve provided a name for the attribute (:item/id in this case), and a type. It is exactly equivalent to:

The various plugins and facilities of RAD define keys that allow you to describe how your new data attribute should behave in the system. In the example above the identity? marker indicates that the attribute identifies groups of other facts (is a primary key for data), and the datomic-namespaced schema is used by the Datomic database plugin to indicate the schema that the attribute should be associated with.

The attribute definitions are intended to be usable by server storage layers to auto-generate artifacts like schema, network APIs, documentation, etc. Of course these things are all optional, but can serve as a great time-saver when standing up new applications.

Many features of web applications can be classified as some kind of form. For our purposes a form is any screen where a tree of data is loaded and saved "together", and where validation and free-form inputs are common. A form could be anything from a simple set of input fields to a kanban board (which could also be considered a report with actions). Most applications have the need to generate quite a few simple forms around the base data model in order to do customer support and general data administration. Simple forms are also a common feature in user-facing content.

RAD has a pluggable system for generating simple forms, but it can also let you take complete control of the UI while RAD still manages the reads, writes, and overall security of the data.

Forms in RAD are a mechanism around reading and writing specific sub-graphs of your data model.

A Report is any screen where the data contains a mix of read-only, derived, and aggregate data. This data may be organized in many ways (graphically, in columns, in rows, as a kanban board). Interactions with the data commonly include linking (navigation), filtering, groupings, pagination, and abstract actions that can affect arbitrary things (e.g. delete this item, move that card, zoom that chart).

Reports are about pulling data from your data model so that the user can view or interact with it in some way.

The primary difference between a form and a report is that: on a form, the majority of the data has an existence in a persistent store that is (roughly) a one-to-one correlation with a control on screen and a fact in a database. Reports, on the other hand, may include derived data, aggregations, etc. Interactions with a report that result in changes on the server must be encoded as more abstract operations.

The most common report we think of a simple list or table of values that has:

In RAD reports are generated by adding additional "virtual attributes" to your model that have hand-written Pathom resolvers.

Report plugins should be able to provide just about anything you can imagine in the context of a report, such as:

The RAD system generally makes it easy for you to pull the raw data for a report, and at any moment you can also choose to do the specific rendering for the report when no plugin exists that works for your needs.

Fulcro works quite well on the web, in React Native, and in Electron. Notice that the core of RAD is built around auto-generation of UI, meaning that many features of RAD will work equally well in any of these settings.

It is our hope that the community will build libraries of UI controls for these various platforms so that the same core RAD source could be used to generate applications on any of these targets with no need to manually write UI code. That said, RAD will already work on any of these targets with no modification: you’ll just have to write the UI bodies of the forms/reports yourself. This still gives you a lot of pre-written support for:

In fact, as your application grows it is our expectation and design that you take over much of detailed code in your application. It is not the intention of RAD to do everything in your final production application. The point of RAD is to make it possible to rapidly stand up your application, and then gradually take over the parts that make sense while not having to worry over a bunch of boilerplate.

The first thing you’ll typically create will be namespaces like this:

The namespace makes it easy for you to find the attributes when you want to read all of the details about them, and the final def make it easy to combine the declared attributes into a single collection for use in APIs that need to know them all.

You can also make your own defattr macro that side-effects these into a global registry. We prefer the explicit combination of attributes because it forces you to require the proper namespaces to make the compiler happy, whereas a registry needs you to require the namespaces, but the compiler won’t complain if you clean up requires and accidentally remove a model from your program. It’ll just fail at runtime.

Each type of entity/table/document in your database will need a primary key. Each attribute that you define that acts as a primary key will serve as a way to contextually find attributes that indicate they can be found via that key. This is very similar to what you’re used to in typical databases where a primary key gives you, say, a row. RAD’s data model does not constrain an attribute to live in just one place, as you’ll see in a moment.

The ao/identity? boolean marker on an attribute marks it as a "primary key" (really that it is a key by which a distinct entity/row/document can be found).

The data types in RAD are not constrained by RAD itself, though only a limited number of them are supplied by database adapter and UI libraries. Extending the type system simply requires that you make a name for your type, and then supply logic to handle that type at various layers.

TODO: A chapter on adding a data type.

Many attributes are simple containers for scalar values (strings, numbers, etc.). RAD itself does not constrain where an attribute can live in any way, but specific database adapters will have rules that match the underlying storage technology.

A RAD attribute to store a string might look like this:

but such an attribute will only be usable if you hand-generate resolvers on your server that can obtain the value, and can store it based on the ID you give a form. So, such an attribute isn’t useless, but it is made much more powerful when you add information for other plugins.

RAD recognizes that different storage technologies group facts together in different ways. (in tables/documents/entities). The common theme that RAD tries to unify is the idea that a particular fact is reachable through either itself (i.e. it is itself a primary key of things), or via some identifying information.

Now, since we recognize something like a :password/hashed-value might live on multiple kinds of things in your database, the generalization is to simply tell RAD which identities can be used to reach that kind of fact:

This simple generalization leads to a lot of potential in libraries.

An SQL database could use this to know it should add :password/hash to the ACCOUNT, FILE, and SFTP_ENDPOINT tables, while any database driver can know to generate resolvers that can find :password/hash if supplied with an :account/id, :file/id, or :sftp-endpoint/id; and that :account/email is easily reachable if an :account/id is known.

Remember that our graph resolver (Pathom) is also intelligent about "connecting the dots". Thus, if there is some bit of information known (i.e. an SFTP hostname) that can be used to resolve an :sftp-endpoint/id, then the network API will automatically be able to derive that :sftp-endpoint/hostname can be used to find a :password/hash.

Data models are typically normalized, and normalization requires that you be able to store a distinct thing once and refer to it from other places. RAD’s attribute-centric nature actually gives you quite a bit of ability to "flex" the shape of your data model at runtime through custom resolvers (i.e. you can create virtualized views of your data that have alternate shapes from the way the data is stored). Therefore the reference declarations in RAD can define a concrete (i.e. represented in storage) or virtual link.

When an attribute is declared with type :ref and it represents a concrete link in storage then it will include database adapter-specific entries that define the reification of that linkage (e.g. does it hold an ID of a foreign table/document/entity, does it use a join table, is it a back reference from a foreign table, or is it simply a nested map in a document?).

If an attribute represents a virtual link it will typically include a lambda (resolver) that runs the appropriate logic to "invent" that linkage. For example, your customers might have multiple addresses, and you might want a virtual reference to the address you’ve most often shipped items to. You can easily assign that a name like :customer/most-likely-address, but you’ll most likely need to run a query of order history to actually figure out what that is.

References have a cardinality (one/many), and when they are concrete they also typically have some kind of optional statement about "ownership". In SQL this is typically modelled with CASCADE rules, in document databases it is often implied by co-location in the same document, and in Datomic it is handled with the isComponent flag.

Again, RAD attributes allow the database adapter to define namespaced keys that can be placed on an attribute to indicate how that attribute should behave.

When using references in Forms you’ll typically also have to include a bit of extra information for the form itself to know which kind of behavior should be modelled for the user, since it will not be aware of the ins-and-outs of your low-level database.

For example an invoice’s line item needs to point to something defined in your inventory. An invoice form might show that as a dropdown that lets you autocomplete a selection from the inventory items.

There are a number of predefined attribute types defined by the central RAD system. Add-on libraries can define more. There is nothing in RAD core itself that either implements these types or supports them. They are opaque to core, and we predefine common primitive ones as a starting point. Database adapters can define more, and these custom types will sometimes require that you write an input control or field to support such a type.

The core predefined attribute types include (this list is not complete yet, but most of these are present):

See the various docstrings in the *-options.cljc namespaces for predefined things that can be put into an attribute’s map. Here are some examples for attributes-options:

RAD often needs to know what attributes are in your model. Early versions tried using a registry, but the side-effect nature of such a thing is simply quite annoying (order-dependent, you can forget requires, etc.).

When building a RAD application you should manually build up a list of all of the attributes in your model. The recommended pattern is to include a def of attributes at the bottom of each model namespace, then you can easily define a list of all attributes like this:

The list of all attributes is required in a number of places in RAD: automatic resolver generation, schema support, save-middleware, etc.

It is also quite useful to have a way to quickly look up an attribute by its keyword:

and to have a Form Validator that is based on the attribute definitions that can be used in derived validators and directly on forms:

Fulcro comes with an EDN-based config file system, and it has options that work well for both development and production purposes. Please see the Fulcro Developer’s Guide for complete details.

The component that loads config usually ends up being the first thing started in your program, which makes it an ideal place to put other code that does stateful initialization which has no dependencies other than the config data (such as logging and the RAD attribute registry).

Here is the recommended config component using mount:

The config files themselves, like config/defaults.edn and config/dev.edn, will contain a single map. See the documentation of Fulcro for more information on how these configurations are merged, using values from the environment, etc.

Forms support middleware that allows plugins to hook into the I/O subsystem of forms. This allows RAD form support plugins to be inserted into the chain to do things like save form data to a particular database. They use a pattern similar to Ring middleware.

There are currently two middlewares that must be created: save and delete.

You will normally use Pathom to provide the processing for the network API on your server (Pathom supports CLJ and CLJS, so you can use the JVM or node). RAD has some logic to convert virtual attributes to resolvers, and many more resolvers can be auto-generated by a RAD storage plugins like Fulcro RAD Datomic.

So first, you’ll generate a stateful list of all of the attributes that convert to resolvers (these will include ::path-connect/resolve keys):

then you’ll set up a stateful parser that installs various plugins and resolvers along with a few standard ones and any you’ve created elsewhere. The result will look something like this:

The supplied constructor for pathom parsers is not required, you can use the source to see what it includes by default. The RAD parser construction function takes a Fulcro-style server config map, a vector of plugins, and a vector of resolvers (the resolvers can be nested sequences).

You will always want the form plugin, along with any storage adapter plugin that works with a database on your server.

Once you have a parser you just need to wrap it in a Fulcro API handler. The resulting minimal server will be a Ring-based system with middleware like this:

See the RAD Demo project for the various extra bits you might want to define around your middleware. You will need to add middleware to support things like file upload, CSRF protection, etc.

At this point the server is just a standard Ring server like this (here using Immutant):

The RAD Datomic database adapter has the following features:

See the README of the adapter for information on dependencies and project setup. You will need to add dependencies for the version of Datomic you’re using and any storage drivers (e.g. PostgreSQL JDBC driver) for the back-end you choose.

The EQL network API of RAD is supplied by Pathom Resolvers that can pull the data of interest from your database. Typically you’ll need to have at least one resolver for each top-level entity that can be pulled by ID, and custom resolvers that can satisfy various other queries (e.g. all accounts, current user, etc.). Forms need to be able to at least resolve entities by their ID, and reports need to be able to uniquely identify rows (either through real or generated values).

DB adapters can often automatically generate many of these resolvers, but legacy applications can simply ensure all of the attributes a form might need can be resolved via an ident-based Fulcro query against that form (e.g. [{[:account/id id] [:account/name]}]).

Fulcro and EQL defines the read/write model, and RAD just leverages it. You can use as much or as little RAD automation as you want. It is just doing what you would do for Fulcro applications.

Forms support middleware that allows plugins to hook into the I/O subsystem of forms. This allows RAD plugins to be inserted into the processing chain to do things like save form data to a particular database. They use a pattern similar to Ring middleware.

There are currently two middlewares that must be created: save and delete. The documentation of your plugin will indicate if it supplies such middleware, and how to install it.

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!.

A form is really just a Fulcro component. RAD includes the macro defsc-form that can auto-generate the various component options (query, ident, route target parameters, etc.) from your already-declared attributes. The fo namespace is an alias for the com.fulcrologic.rad.form-options namespace.

A form should have a minimum of 2 attributes:

Most forms that are used directly (and not just as sub-forms) must also include a route prefix to make them capable of direct use:

If you have configured UI generation then that is all you need. Thus a minimal form that is using the maximal amount of RAD plugins and automation is quite small:

There are pre-written functions in the form ns for the common actions:

We are now to the point of seeing what a complete Fulcro RAD client looks like. The bar minimal client will have:

The landing page in this example includes a sample button to create a new account, but of course you’ll also need to add some seed data to your database, wrap things with some authorization, etc.

The data type and rendering style of an attribute (along with extended parameters possibly defined by input styles in their respective documentation) are the first line of data enforcement: Saying that something is a decimal number with a US currency style will already ensure that the user cannot input "abc" into the field.

Further constraining the value might be something you can say at the general attribute level (age must be between 0 and 130), or may be contextual within a specific form (from-date must be before to-date).

Validators are functions as described in Fulcro’s Form State support: They are functions that return :valid, :invalid, or :unknown (the field isn’t ready to be checked yet). They are easily constructed using the form-state/make-validator helper, which takes into account the current completion marker on the field itself (which prevents validation messages from showing too early).

Attribute-level validation checks can be specified with a predicate:

Custom validations are defined at the form level with the ::form/validator key. If there are validators at both layers then the form one completely overrides all attribute validators. If you want to compose validators from the attributes then use attr/make-attribute-validator on your complete model, and use the result in the form validator:

The message shown to the user for an invalid field is also configurable at the form or attribute level. The existence of a message on the form overrides the message declared on the attribute.

The form-based overrides are useful when you have dependencies between fields, since they can consider all of the data in the form at once and incorporate it into the check and validation message. For example you might want to require a new email user use their lower-case first name as a prefix for an email address you’re going to generate in your system. You might use something like this:

It is quite common for a form to cover more than one entity (row or document) in a database. An account might have one or more addresses. An invoice has a customer, line items, and references to inventory. In RAD, combining related data requires a form definition for each uniquely identifiable entity/row/document. These can have to-one or to-many relationships.

A given entity and its related data can be joined together into a single form interaction by making one of the forms the master. This must be a form that resolves to a single entity, and whose subforms are reachable by resolvers through the attributes of that master (or descendants).

Any form can automatically serve as a master. The master is simply selected by routing to it, since that will start that form’s state machine which in turn will end up controlling the entire interaction. The subforms themselves can act as standalone forms, but will not be running their own state machine unless you route directly to them. Interestingly this means that forms can have both a sibling and parent-child relationship in your application’s UI graph.

All forms are typically added to a top-level router so that each kind of entity can be worked with in isolation. However, some forms may also make sense to use as subforms within the context of others. An example might be an AddressForm. While it might make sense to allow someone to edit an address in isolation, the address itself probably belongs to some other entity that may wish to allow editing of that sub-entity in its context.

A simple example of this would look as follows:

In the above example the AddressForm is completely usable to edit an address (if you have an ID) or create one (if it makes sense to your application to create one in isolation). But it is also used as a subform through the :account/addresses attribute where the ::form/subforms map is used to configure which form should be used for the items of the to-many relationship. Additional keys in the subforms map entries allow for specific behavioral support.

This section assumes you know a bit about Fulcro’s Form State support. The validation system used in RAD is just that, with some automation stacked on top. It is important to understand that validation does not start taking effect on a field until it is "marked complete", and a form is never considered "valid" until everything it is considered "complete". RAD will automatically mark things complete as users interact with form fields (often on blur), but creation needs you to indicate what (pre-filled) fields should be considered "already complete".

The rules the built-in RAD form state machine uses:

The attributes options for setting defaults when things are created are:

There are currently 3 kinds of dynamism supported by RAD:

Fulcro uses EDN for its data representation, and supports all of the data types that transit supports out of the box, at least at the storage/transmission layer. Some of these type, however, have further complications. The two most pressing are time and precise representation of numbers, but others certainly exist.

RAD includes support for helping deal with these problems.

RAD Forms can support file uploads, along with download/preview of previously-uploaded files.

File transfer support leverages Fulcro’s normal file upload mechanisms for upload and the normal HTTP GET mechanisms for download. The file is sent as a separate upload mutation during form interaction, and upload progress blocks exiting the form until the upload is complete (the form field itself for the upload relies on correctly-installed validation for this to function).

The file itself is stored on the server as a temporary file until such time as you save the form itself (though you can also configure the form to auto-save when upload is complete). When you save the form you must use the save middleware to move the temporary file to a permanent store of your choice and then augment the incoming form data to include the details about the file that will allow your file detail resolver to emit a proper URL for getting the file.

The UI plugin is probably the first and most obvious element that you’ll want control over. RAD is built to give you escape hatches for every element of rendering.

The first thing to realize is that a defsc-form is just a Fulcro component that has a bunch of data in the component options that the various plugins use to do their work. However, forms can be nested, and that creates a bit of additional complexity.

The overall architecture of a RAD form is roughly like this:

The server is the easy part. A single form/save-form mutation is the source of all writes (except delete) and resolvers are the source of form data for reads. The form data is sent via Fulcro’s form-state minimal diff, which makes implementing generic save logic very easy (the Datomic one is just a couple hundred lines of code). Security and such can be added to the form and Pathom middleware.

The UI is a bit more complex in structure.

There is a single UISM that is started with the top-level form. Subforms are controlled by this same top-level machine. The real communication layer is the standard Fulcro state database (query) and mutations (UISM trigger), but for simplicity we show the communcation going through the UISM.

Each form has a query and ident that follows the exact rules of Fulcro, and the props in any form are exactly the content of that component’s query; however, every nested form (no matter the depth) must know its immediate parent, and also the master form (because the UISM is identified by that top-level form’s ident).

A report query is nothing more than your normal EQL query, so it can be resolved by a Pathom client or server parser. The query parameters that come from the report will only normally appear in the AST at the top-level resolver (for the source-attribute).

There is a com.fulcrologic.rad.pathom/query-params-to-env-plugin that can be added to a pathom parser which moves the top-level params into the general parsing env at key :query-params. This is where the report parameters will show up.

So, your parser will look something like this:

and from there it’s simply a matter of writing resolvers. Assuming you have a function that can get all employees:

Remember that Pathom resolvers auto-connect based on inputs and outputs, so any given report attribute can be connected from there. For example, perhaps your report generates the number of hours an employee has worked this pay period, you’d simple add that attribute to the report and a resolver like this:

You will have to install UI renderers for reports to render at all. Your rendering plugin will come with a default layout and perhaps others. You can define your own and the component options can easily be used to get what you need to render the data.

Setting up your layout is just done on app config:

and then set the ::report/layout-style :custom-layout option on the report.

Just some notes…​

Normalization can be expensive for large reports. Denormalize reports that don’t share info with forms. This can save many seconds of processing if you have thousands of data points, will also affect rendering speed if you are doing something like a chart.

Reports filter, sort, and paginate in phases. For large reports, disabling the filter or sort stages can be quite helpful when they are not needed. Use ro/skip-filtering? to programatically force the report to skip the processing of filters (normally if you provide a row-visible? it is called once per row no matter what). Sorting can be disabled by calling report/clear-sort!, which does not re-render or re-sort the table. It just sets a flag so that future operations won’t call the sort stage. This dissoc’s the :sort-by sort paramter, so NOT including a :sort-by in your ro/initial-sort-params is how to disable sorting on initial load. Pagination is cheap, so it should never be the source of problems.

Note also that filtering happens first, then sorting, then pagination. If you re-sort, then filtering will never be re-applied, but if you change the filters sorting will also happen (unless disabled).