Fulcro Developers Guide

Many of the code examples assume you’ve required the proper namespaces in your code. This book adopts the following general set of requires and aliases:

others will be identified as they are used.

Fulcro and our understanding of best practices with it have evolved over time. Unfortunately we don’t have time to update this book every time a new insight or technique proves to be more useful that older ones. Everything in this book functions in the latest versions of Fulcro (to the best of our knowledge); however, this small section of the book is where we’ll try to list notes about current evolutions of the library and which features might be best to focus on.

As of September 2020 you should concentrate your efforts on understanding:

People have a number of initial "comparative" questions when looking at Fulcro when they’ve used other libraries. If you are familiar with other CLJS or JS UI libraries then you may have one of these questions. The most common ones are:

Fulcro makes no assumptions nor does it have any requirements about back-end databases. You don’t even have to have a back-end: You can easily simulate one with the browser (like this book does), wrap browser local storage, or simply not use one at all.

If you are using a server database, then normalization and schema on the server is done according to whatever you’ve designed. Pathom makes it easy to "reshape" any particular schema or storage technology into a graph that fits your external API and UI needs.

This is an important point: it does not matter how your back-end database structures the data, as long as you know how to get the data you need when given a "context" that makes sense.

Fulcro uses EQL (EDN Query Language), a graph query language similar to Datomic’s pull query notation.

A query is a vector (with nesting) that lists the things you want:

The above query (when run against a person) asks for that person’s name, and then indicates a "join" by using a map whose key is the join property on person, and whose value is a subquery of things to pull from there.

Such a query returns a map that mirrors the query structure:

and could potentially return to-many results (if the address field were to-many in the database of the server):

For those coming from SQL this roughly equates to a LEFT JOIN from person to address (where the behind-the-scenes join key might be converted from :person/address to something like address.person_id). You could implement this with something crude like:

and walk the table result with a reduce to convert the rows into the graph, but fortunately, the Pathom library does most of that "lifting" for you and also includes features that can be used to tune for optimal performance (e.g. fixing n+1 query problems, branch caching, parallel operation, etc.).

Fulcro uses a single, central, normalized graph database. Any time data is created or read into a Fulcro application it can be auto-normalized into this database, and queries from the UI components can easily be fulfilled from it.

The format of this database is trivial (and very fast as a result):

We use the term *ident* to mean "A tuple of table and ID that uniquely identify a graph node in the database."

The graph of data like this:

can be turned into this:

This format supports any arbitrary graph, to-many (a vector of idents) and to-one (single ident) relations, any possible property value type (though you should generally make sure they’re serializable for network transfer), and is simple to manipulate (i.e. an assoc-in with a path length of 2 or 3 gets you to anything).

This leads to the following useful results:

You may be asking "by what magic can Fulcro do this?". The answer is simple: by co-locating the node/edge descriptions with the components of your UI!

We also are writing SPAs where what we care about is the UI we end up with. Pathom can shape our server graph to match whatever we need on the client, and this frees us to design our UI as we see fit.

Components can therefore represent the desired UI nodes of a graph, and the EQL joins can represent the edges. Auto-normalization just requires one more detail: a way to manufacture the correct ident for a given node in order to make the edge.

This is functional programming, so of course the answer is a function:

The convention for our table names (for ease of use with Pathom) is to use the name of the ID field of the entity (e.g. :person/id) as the table name for those types of entities.

Thus, the "ident" of this person:

Of course, this function needs to be associated with the Person component for Fulcro to know how to use it. That looks like this:

During operation you will need to make things happen.

The prior sections describe the core points of Fulcro’s architecture. Data flows in and out via graph queries and mutations that can easily manipulate a local normalized graph database in a unified way. Remote interactions are managed by mutation declarations and all side-effecting and asynchrony is isolated from the UI layer by a CQRS-style transactional semantic. Fulcro leverages the idents, immutable data structures, co-located queries, and other tricks to optimize refresh.

Here are some additional interesting things that fall out of this model "for free":

Finally, a more recent addition to the library has proven to be extremely useful: UI State Machines.

Most UIs end up with a mess of logic spread out in ways that are hard to reason about. Look no further than any "login" module of an application. Are you logged in? Are we checking the server to see if our session is valid? Should I show a "wait" indicator?

We’ve known for years that state machines are a great way to manage this kind of complexity, but they are traditionally a bit of work to integrate into any given "UI library".

Fulcro’s central normalized database and mutation model made an internal version of state machines a very good match. Not only is it easy to define them, the model makes them reusable: that is to say you can indicate which UI components serve roles within the machine, leading to things like CRUD state machines can manage the interactions (edit, list, save, reset, cancel, etc.) for most of the entities in a form system.

Many of the most interesting and compelling features of Fulcro are directly or indirectly enabled (or made simpler) by the use of persistent data structures that are a first-class citizen of the language.

In imperative programming languages like Java and Javascript you have no idea what a function or method might do to your program state:

This leads to all sorts of subtle bugs and is arguably the source of many of the hardest problems in keeping software sustainable today. What if Person couldn’t change and you instead had to copy instead if you wanted to modify?

Now you can reason about what will happen. The other thread will see p exactly as it was when you (locally) reasoned about it. Furthermore, q cannot be affected because if p is truly "read-only" then I still know what it is when I use it to derive q (the other thread can’t modify it either).

In order to derive these benefits you need to either write objects that enforce this behavior (which is highly inconvenient and hard to make efficient in imperative languages), or use a programming language that supplies the ability to do so as a first-class feature.

Another benefit is that persistent data structures can do structural sharing. Basically the new version of a map, vector, list, or set can use references to point to any parts of the old version that are still the same in the new version. This means, for example, that adding an element to the head of a list that had 1,000,000 entries (where only one is being changed) is still a constant time operation!

Here are some of the features in Fulcro that trivially result from using persistent data structures:

Fulcro’s default rendering system uses Facebook’s React to accomplish updates to the browser DOM. React, in concept, is really simple:

Render is a function you make that generates a data structure known as the VDOM (a lightweight virtual DOM)

The cool realization the creators of React had was that the DOM operations are slow and heavy, but there are efficient ways to figure out what needs to be changed via the VDOM without you having to write a bunch of controller logic.

Now, because React lives in a mutable space (JavaScript), it allows all sorts of things that can embed "rendering logic" within a component. This sounds like a good idea to our OOP brains, but consider this:

What if you could have a complete snapshot of the state of your application, pass that to a function, and have the screen just "look right". Like writing a 2D game: you just redraw the screen based on the new "state of the world". All of the sudden your mind shifts away from "bit twiddling" to thinking more about the representation of your model with minimal data!

That is what we mean by "pure rendering".

Here’s an example to whet your appetite: Nested check-boxes. In imperative programming each checkbox has its own state, and when we want a "check all" we end up writing nightmares of logic to make sure the thing works right because we’re having to store a mutable value into an object that then does the rendering. Then we play with it and find out we forgot to handle that event where some sub-box gets unchecked to fire an event to ensure to uncheck the "check all"…​oh wait, but when I do that it accidentally fires the event from "check all" which unchecks everything and then goes into an infinite loop!

What a mess! Maybe you eventually figure out something that’s tractable, but that extra bit of state in the "check all" is definitely the source of bugs.

Here’s what you do in pure rendering with immutable data:

Each sub-item checkbox is a simple data structure with a :checked? key that has a boolean value. You use that to directly tell the checkbox what its state should be (and React enforces that…​making it impossible for the UI to draw it any differently)

For a "state of the world", these are read-only. (you have to make a "new state of the world" to change one). When you render, the state of the check-all is just the conjunction of its children’s :checked?:

The check-all button would have no application state at all, and React will force it to the correct state based on the calculated value. When the sub-items change, a new "state of the world" is generated with the altered item:

and the entire UI is re-rendered (React makes this fast using the VDOM diff), the "check all" checkbox will just be right!

If the "check all" button is pressed, then the logic is similarly very simple: change the state for the subitems to checked if any were unchecked, or set them all to unchecked if they were all checked:

and again you get to pretend you’re rendering an entire new frame on the screen!

You’ll be continually surprised at how simple your logic gets in the UI once you adjust to this way of thinking about the problem.

Data-driven concepts were pioneered in web development by Facebook’s GraphQL and Netflix’s Falcor. The idea is quite powerful, and eliminates huge amounts of complexity in your network communication and application development.

The basic idea is this: Your UI, which might have various versions (mobile, web, tablet) all have different, but related, data needs. The prevalent way of talking to our servers is to use REST, but REST itself isn’t a very good query 'or' update language. It creates a lot of complexity that we have to deal with in order to do the simplest things. In the small, it is "easy". In the large, it isn’t the best fit.

Data-driven applications basically use a more detailed protocol that allows the client UIs to specify what they need, and also typically includes a "mutation on the wire" notation that allows the client to abstractly say what it needs the server to do.

So, instead of /person/3 you can instead say "I need person 3, but only their name, age, and billing info. But in the billing info, I only need to know their billing zip code".

Notice that this abstract expression (which of course has a syntax we’re not showing you yet) is "walking a graph". This is why Facebook calls their language "GraphQL".

You can imagine that the person and billing info might be stored in two tables of a database, with a to-one relationship, and our query is basically asking to query this little sub-graph:

Modifications are done in a similar, abstract way. We model them as if they were "function calls on the wire". Like RPC/RMI:

but instead of actually 'calling' the function, we encode this list as a data structure (it is a list containing a symbol and a map: the power of Clojure!) and then process that data locally (in the back-end of the UI) and optionally also transmit it 'as data' over the wire for server processing!

The client-side of Fulcro keeps all relevant data in a simple graph database, which is referenced by a single top-level atom. The database itself is a persistent map.

The database should be thought of as a root-level node (the top-level map itself), and tables that can hold data relevant to any particular component or entity in your program (component or entity nodes).

The tables are also simple maps, with a naming convention and well-defined structure. The name of the table is typically namespaced with the "kind" of thing you’re storing, and has a name that indicates the way it is indexed:

You should use Chrome for development because we have a developer tool called Fulcro Inspect that is available from the Chrome store for free. There are also devtools that are installed via preloads which will autoformat EDN that is sent via console.log. When properly configured, these tools will let you view the internal state of your Fulcro application, the local and remote transaction history, save "snapshots" of state so you can quickly retry a UI flow by hitting a "reset" button, "scroll" over state history and watch the UI change, run queries (with autocomplete if you’re using Pathom) against your EQL server, and even (via binaryage devtools) source-level debug your Fulcro application in CLJS with stack frame analysis and proper clojure names for things! These tools will save you countless hours of frustration.

Fulcro Inspect is a free extension for Chrome, and Binaryage devtools is a library that can be injected via a preload (which shadow-cljs does for you if it is in your dependencies).

All of the examples in the book have a "Focus Inspector" button. If you open Chrome devtools, choose the Fulcro Inspect tab, and then press that button you will focus the inspector on that example so you can see its database. The first example in this book looks like this when you do that:

You should open the Chrome developer tools (e.g. console and such). Edit the developer tool settings and change:

and always keep devtools open when you’re working on your apps. This ensures you’ll not be confused by caching issues and will be able to see clojure data structures as Clojure, and not low-level JS objects.

You’ll normally want to build a real application based on the Fulcro template. It contains a lot of boilerplate on things like server configuration, CSRF, testing, better error message formatting, and so on. This can save you quite a bit of setup and development time.

For this chapter we’re going to start from literally nothing. These instructions should work with any UNIX-like (e.g. OSX or Linux) system. I do not use Windows, so your mileage may vary if you’re on that platform.

The following commands should work from your command line (the $ is the command prompt):

(hit CTRL-D or CTRL-C to exit)

your version may be different. In general you should use the latest version of the JDK that is compatible with Clojure, but later versions should probably work fine as well.

If any of these fail, diagnose your installation of those tools before continuing.

Create a directory and set up a basic node project:

Fulcro supplies a defsc macro to build React components. This macro emits class-based React components (or, with :use-hooks? true, a pure functions with hooks support). These components are augmented with Fulcro’s data management and render refresh.

There are also factory functions for generating all standard HTML5 DOM elements in React in the com.fulcrologic.fulcro.dom namespace.

The basic code to build a simple component has the following form:

This macro emits the equivalent of a React component with a render method.

You can tighten your DOM code up even more if you also :refer the common tags in your namespace declaration:

React lifecycle methods are all supported, but we’ll talk about those later.

Obviously it isn’t going to be desirable to hand-manage this very well for anything but the most trivial application (which is the crux of the problems with most UI libraries).

At best it does give us a persistent data structure that represents the current "view" of the application (which has many benefits), but at worst it requires us to "think globally" about our application. We want local reasoning. We also want to be able to easily re-compose our UI as needed, and a static data graph like this would have to be updated every time we made a change! Almost equally as bad: if two different parts of our UI want to show the same data then we’d have to find and update a bunch of copies spread all over the data tree.

So, how do we solve this?

The queries on components describe what data the component wants from the database; however, you’re not allowed to put code in the database, and sometimes a parent might compute something it needs to pass to a child like a callback function.

It turns out that we can optimize away the refresh of components (if their data has not changed). This means that we can use a component’s query to directly re-supply data for refresh; however, since doing so skips the rendering of the parent. If we are not careful this can lead to "losing" these extra bits of computationally generated data passed from the parent, like callbacks.

Let’s say we want to render a delete button on our individual people in our UI. This button will mean "remove the person from this list"…​but the person itself has no idea which list it is in. Thus, the parent will need to pass in a function that the child can call to affect the delete properly:

Now the real fun begins: Making things dynamic.

Most operations that make changes to the client database should happen through the Fulcro transaction system. It is actually possible to do more advanced low-level things, but that is beyond our current scope.

Fortunately, we have a very good solution to the mutation problem above, and it is one that has been around for decades: database normalization!

Here’s what we’re going to do:

Each UI component represents some conceptual entity with data (assuming it has state and a query). In a fully normalized database, each such concept would have its own table, and related things would refer to it through some kind of foreign key. In SQL land this looks like:

In a graph database (like Datomic) a reference can have a to-many arity, so the direction can be more natural:

Since we’re storing things in a map, we can represent "tables" as an entry in the map where the key is the table name, and the value is a map from ID to entity value. So, the last diagram could be represented as:

This is close, but not quite good enough. The set in :people is a problem. There is no schema so there is no way to know which table to look in for "1" and "2"!

The solution is rather easy: code the foreign reference to include the name of the table: [:Person 1].

To-one relations are represented as a single one of these, and to-many relations as a vector of these (to preserve order).

In Fulcro [TABLE ID] is known as an ident.

So, now that we have the concept and implementation, let’s talk about conventions:

Using these conventions the prior example would have looked like this:

So far we’ve been hacking things in place and using the REPL to watch what we’re doing. There are better ways to work on Fulcro applications, and now that we’ve got one basically working, let’s take a look at them both.

OK, back to the main story!

Believe it or not, there’s not much to add/change on the client to get it talking to a server, and there is also a relatively painless way to get a server up and running.

Before we can obtain data from the server we have to understand a little bit about writing resolvers for Pathom. Pathom is basically a library for building EQL parsers. The two critical things you define are called resolvers and mutations. The latter is pretty much identical to what you’ve already done in Fulcro, and at the moment we’re primarily interested in satisfying some reads. So let’s talk about resolvers.

Resolvers are defined to expect some particular inputs, and declare what they can produce. They are always called with some context (stored in an env parameter) and some optional inputs that match the expected inputs. The context includes the portion of the query that is currently being parsed along with a number of other things. The idea is that "given a context and some input" you should be able to write some code that can resolve the desired outputs.

In this chapter the following requires with aliases are assumed:

Here is a sample resolver:

it declares "Given a :person/id as input, I can produce their name". The inputs are written as a set, and the output is written as an EQL query. The body of the function will find the required input in the input parameter, and must return an EQL response that matches the shape of the declared ::pc/output.

In cases where the resolver is not able to find the data promised in ::pc/output`, simply elide the promised key from the returned map. Loosely following the examples below, such a situation might arise if the person you’re querying for has no enemies while :person/enemies is in the declared ::pc/output. Excluding a key like this from the resolver’s return value will cause Pathom to respond with {:person/enemies ::p/not-found …​}, which gets removed from the final query output as long as your parser config includes one of the elide plugins like p/elide-special-outputs-plugin or (p/post-process-parser-plugin p/elide-not-found). Foregoing this step can cause Fulcro to produce malformed idents like [:thing/id nil] when referring to the thing that could not be found. Lastly, another option is to set :person/enemies to an empty vector in such cases instead of excluding it from the map entirely.

Furthermore, the output of a resolver augments the known context that Pathom is working with, and can be used to chain lookups across resolvers to fulfill a complete query.

For the sake of our examples we’re going to hand-generate a server-side database in simple maps so that you can concentrate on the code of interest instead of boilerplate database initialization and queries.

Add a src/main/app/resolvers.clj file with this content:

and then add these resolvers into the parser.clj file:

These two resolvers already give you a lot of power. We’ve been following a convention for some time of giving idents the "table name" of the ID field. This is because Pathom can treat an ident as "context" for determining which resolver to run.

It turns out that EQL will allow an ident to be used as a join key to establish a particular graph context (i.e. pretend we’re on the node with the given ident): :

If you load the parser namespace you can try these out in a CLJ REPL (e.g. clj -A:dev at the command line):

Pathom’s magic is that it can traverse the graph based on the declared inputs and outputs. The fact that the list resolver says it outputs :person/id means that Pathom can "connect the dots" to fill in details of that person.

Those two resolvers make it possible for us to execute all of the arbitrary queries we’d need to feed data to our application at any level!

It is also possible to define resolvers that don’t require any inputs at all. These "global resolvers" are the same as "root queries" in GraphQL. We could use one of these for our application, so add this to your resolvers.clj file:

and now if you reload the code in your REPL you should be able to run a query like this:

At this point you’ve gotten more detailed view of what a Fulcro application looks like. The remaining chapters of this book go into considerably more detail about each important part of the API.

Denormalization in Fulcro is the process of running an EQL query against a normalized Fulcro client database. The algorithm is pretty trivial in the common case, but since EQL supports recursion, wildcards, and union queries the actual implementation is somewhat difficult to read and understand.

Fortunately, using it is much simpler.

The primary algorithm for denormalization is db→tree, found in the [com.fulcrologic.fulcro.algorithms.denormalize :as fdn] namespace.

The db→tree function is designed to be used in two different contexts:

Notice that since the Fulcro database itself is just a special (the root) node of the database that the two cases are really identical in practice. The first case is just a "well-known" node to start at.

Let’s make it more concrete. Assume you have the following Fulcro database:

I can pull a tree of data using:

I want you to note a few very important things:

For clarity, let’s build this up a step at a time:

Notice that both of the above queries stop where the EQL stops (even if there are unresolved idents). If you say you want :people as a prop, then you get that value as an "opaque" literal. You are free to store whatever you like at a prop in a Fulcro database, and the denormalization will only resolve an ident when it is told to expect a join.

Now, let’s suppose you wanted to query the details of a person, but you didn’t want to follow any joins. Well, in that case you can essentially use db→tree much like clojure.core/select-keys:

In this case I can supply an empty database for the final argument because that database is only used to resolve idents. In fact, if I have a tree of data with no normalization, I can use db→tree to simply "prune it" as if it were a more advanced version of select-keys:

Thus, you see that the final database argument is only about resolving idents when they are crossed by a join in the EQL.

The normalization of data is the reverse process of denormalization. Take an arbitrary tree of data and turn it into Fulcro’s normalized graph database form. Note that, except for the root of the tree, that every element in the tree is relative to another element:

our task in normalization is to recursively replace every relative child with a "lookup ref" (known to Fulcro as an ident), and to place that child at the location indicated by that lookup ref.

How do we do that?

Now that you understand how the normalization and denormalization APIs work, it is much easier to understand the purpose and functionality of component :initial-state. It is common for people to misunderstand initial state to be some kind of OO constructor pattern. It is not. Initial state is bourne out of the following problem:

You start a brand new Fulcro app. It has a query that wants to pull data from a client database. What is in that database?

The answer is, well, nothing!

In the very early days this was a painful problem. If you wanted a real normalized database then you had to build the darn thing by hand! You’d write some UI, then you’d hack away on a data structure to build a normalized database that you’d then initialize the app with. This was very error prone and frustrating. Worse, when you’d go to refactor your application you’d have to refactor your initial database.

After doing that about 3 times it was obvious that this needed a better solution, and it didn’t take much thinking to realize that we already had the answer: The shape of the UI! The shape of the UI already dictates the query, and that same parallel magic that led to the co-location of the ident was now an obvious similar solution for this initial application state problem!

By having you co-locate the component’s query and state, and then compose the query (through joins) and initial state (by component reference) we could have an initial application state that could be automatically extracted, normalized, and would also "follow along" through refactoring!

The defsc macro again has some convenient "magic" that can save you some typing, but the reality is this: initial state is just a function in component options that returns the desired initial data for that component (if it has any). That component, of course, also knows the immediate children and composes their queries and initial state into its own.

That causes the whole shape to naturally form and maintain correctness as a simple part of UI construction.

Try it out in a REPL:

and then build it up a layer at a time:

Fulcro is doing no magic here at all. It is simply returning your own composition of data that just happens to naturally fall into the correct shape due to your composition of the UI (assuming you follow the rule, which is simply: shape of query + initial state == shape of stateful UI).

It is a natural composition technique that self-maintains through any amount of refactoring, is reasoned about locally (yes, root gets the entire application’s tree of data, but it need know nothing about anything but the direct children, which it cannot get out of knowing because it renders them!), and which leads to all of the additional cool stuff you get from Fulcro:

As a quick final example, the initialization of a Fulcro application is something you should now be able to write yourself! You’ve seen all of the elements that are required. It is simply:

Fulcro does a few more things related to unions during this initialization, so this isn’t the entire picture, but it is pretty darn close.

Fulcro has a lot of internal mechanisms dedicated to rendering, but you’ll possibly be surprised to learn that the core rendering logic is about 5 lines long. Most of the additional logic is made up of pluggable algorithms that do various (optional) optimizations.

The primary rendering of Fulcro is just this:

That’s it! The optimizations do things like re-render targeted components (instead of the root), but it is critical that you understand that the rendering is a literal reification of your normalized database as UI.

So, now that you’ve been awakened to how simple Fulcro actually is internally, you can start to shift your mental model to the reality of working with Fulcro. The primary task is this:

Update your state database (and optionally your queries) such that the next reification of that data will be the desired render frame.

That’s the major shift you have to make when thinking about UI in Fulcro. It’s all about the data. Therefore, the operations you’ll be doing throughout your application’s lifetime are:

Trivial operations like "check that box" or "hide that dialog" are done via manual manipulation, and are quite common (and simple) to do in mutations. You can technically swap! against the actual state atom, but Fulcro does not watch the state atom, so rendering refreshes are not automatic, and that form of direct manipulation bypasses a lot of other useful and important features. Advanced users (or library authors) with specific needs might do that to add some advanced feature, but most users will never want to.

Structured manipulation is where Fulcro starts to get really nice. It is very common for a Fulcro application to want to add something to the graph dynamically. It is most easy to do that using a tree of data and the built-in normalization features. You can, of course, do this within a mutation using tree→db, but because there are some common use-cases there are pre-built functions to help you with this task. The primary two are df/load! and merge/merge-component!.

Both of these functions are just fancy versions of tree→db: that is to say take a tree of data and merge it into the database. The load! variant obtains the tree over the network, and the merge-component! one assumes you’ve got a tree of data in hand.

In both cases they leverage the fact that a query has metadata that can be used for normalization. The load! variant, of course, also needs the query so it can ask a remote server for the correct tree.

Again, these APIs work in a CLJ REPL (though to use either you have to have a running Fulcro app). load! also requires a CLJ implementation for a remote, so we’ll just play with merge-component!, which does everything load! does except obtain the tree remotely.

Let’s say you set up a running application. The :headless keyword is just an arbitrary placeholder in CLJ. There is no actual UI mounted, but we have to pass something to match the function’s arity.

Notice that we can start up the Fulcro app just like we could on the client, and that when we ask for the current state it is exactly what we expect (plus an app ID that Inspect adds).

Let’s say we want to add another person to this database. This usually involves 2 operations:

We could use a mutation and do those steps manually, but it gets really tedious if there are complete subgraphs to normalize. Instead, we use merge/merge-component! from [com.fulcrologic.fulcro.algorithms.merge :as merge]:

Notice that this put the new map of data in the correct (normalized) place. If there were sub-children of a person (e.g. :person/address) then this would have normalized (and joined) those parts as well.

For example,

The main problem is that the new person is not yet in the :root/people list! If the UI for Root was rendering all of the people, then this new person isn’t going to show up! Remember that the UI is just a reification of the data graph, and the data graph is missing an edge from :root/people to [:person/id 3].

We could, of course, manually fix that with a mutation, but merge-component! (and load!) understand that this is a very very common need. So, the merge variant allows any number of optional targets (and load! supports a :target parameter).

The name "target" comes from the idea that the thing you’re merging often needs to be added to the graph: a desired target location. It is specified as a vector-path (ala assoc-in), and can also be augmented with metadata to tell it how to behave with respect to to-many edges.

For example, say you wanted to target the new person to be available from the root as a new :root/edge:

or this new person was the spouse of Bob:

or this new person should be shown at the beginning of the :root/people list:`

The same thing applies when you’re writing mutations. The returning helper for mutations is just a way of sending a query on the return value of a mutation that is then merged into your database. It’s all the same stuff!

is a mutation that will (only) do remote operations on person, but will also return the updated person. When it does so the server should use the query (of Person) to return only the items the UI cares about, and Fulcro will merge the resulting data using merge-component! via Person.

Of course, that would only update the person in-place, and would not change any graph edges. Making new edges is also possible on mutation return values. Say you use Person to represent your system users. When you application first loads you might want a mutation to run that looks something like this:

where the server-side implementation of resume-session looks to see if there is a cookie that represents a known user. If so, it returns the identity according to the Person query, and when the application receives the result it joins that person to the graph at the root "edge" :current-user. The UI could then integrate that in for display in the header to indicate who is logged in:

Now that you have the general idea of the core APIs of Fulcro, the remaining chapters should be considerably easier to digest. Every other feature of Fulcro is kind of a "side detail" or "gravy on top".

The React-centric APIs (i.e. DOM factories) have to do with writing web applications. The transaction and mutation system are central to the overall operation of a Fulcro application and provide a number of services that make writing applications more sane. The routing APIs are really just two ways of how you might go about doing UI routing in Fulcro. The state machine API is a kind of "mega mutation" system for writing coordinated bits of logic with your UI.

Ultimately there is a lot of "support" in the Fulcro ecosystem of libraries, but at the core is this simple mechanism: The shape of your UI mirrors the shape of the query which in turn mirrors the resulting shape of the data. That symmetry of shape leads to the ability to easily transform the data between normalized and denormalized forms, which in turn leads to the ability to easily evolve your graph of data, and thus your UI.

Debugging becomes largely a task of "Does my data have the right shape, and if not, why?"

The core HTML5 elements all have simple factory functions that generate the core elements that stand-in for the real DOM. These stand-ins (commonly referred to as the virtual DOM or VDOM) are ultimately what React uses to generate, diff, and update the real DOM.

So, there are functions for every possible HTML5 element. These are in the com.fulcrologic.fulcro.dom namespace.

The notation allowed is as follows:

There is also a :classes property that can be used to add (typically via expressions) additional classes. It drops nil, and allows classname keywords and strings as well:

Assuming hidden and (not tall) would yield classes "a other hidden short" on output. Of course you probably don’t need all of these at once, but supporting them all lets you programmatically combine them when generating props. NOTE: This feature does not work on props sent with #js notation.

Remember that this (nested) call of functions results in a representation (React Elements) of what you’d like to end up on the screen.

The next level of abstraction is simply a function. Combining more complex bits of UI into a function is a great way to group re-usable nested DOM:

but remember that a function has no component hooks, so it cannot do things like short-circuit rendering when props have not changed.

Fulcro’s defsc is the main macro you’ll use to create components. It is sanity-checked for the most common elements: ident (optional), query, props destructuring, and initial state (optional). The sanity checking prevents a lot of the most common errors when writing a component, and the concise syntax reduces boilerplate to the essential novelty. The name means "define stateful component" and is intended to be used with components that have queries (though that is not a requirement).