Fulcro Explained: When UI Components and Data Entities Diverge

Most of the time a Fulcro’s defsc both defines a data entity such as "Person" and the UI to display it. It has either a static ident(ifier) such as :ident (fn [] [:component/id ::AllPeopleList]) (using the lambda form) if the data entity is a singleton or a "dynamic" (props-dependent) ident such as :ident (fn [] [:person/id (:person/id props)]) (or just :person/id in the keyword form).

You might want to wrap a piece of UI into a component of its own either to reuse it elsewhere or to simplify the parent component (following the best programming practice of well-named, single-purpose chunks of code). You could achieve the same with just moving it into a separate function but sometimes you actually want a component, e.g. so that it is visible as a separate, named thing in the React world (error logs, React Dev Tools' Components view) or so that it can leverage React’s shouldComponentUpdate to avoid unnecessary re-rendering (as described in the section 5.7. Using defsc for Rendering Optimization of the Fulcro Dev Guide).

If the UI-only component has no stateful descendant than it is trivial. Simple make your defsc with no :ident, :query, :initial-state and otherwise use it as any other Fulcro component. (Obviously you don’t need to include its comp/get-query or initial-state in the parent.)

However if the component has a stateful descendant then you need to make sure that its query and, if required for the initial app state, its initial state is correctly composed (directly or indirectly) into the root component. (Components whose data is dynamically loaded typically do not have initial state.)

Perhaps the cleanest solution is to let the stateful parent of the UI-only component instantiate and control the stateful descendant, composing its query and initial state into its own and passing it as a child to the UI-only child. Thus the data tree is a subset of the UI tree. An example of a similar case, only with the UI-only defsc replaced with a pure React higher-order-component, is in 5.15.1. Fulcro and React HOC where the Root composes CCForm's query and state into its own and instantiates ui-cc-form and passes it to the wrapping ui-stripe-provider and ui-elements.

An example of a stateless Heading with a stateful HeadingUser child, provided by Heading’s parent:

It is canonical to create defsc that are only meant to define a Data Entity and not to produce any actual UI, ones that are never rendered as a child.

You would use them to df/load! a particular set of data that does not have an exact match in a UI component - .e.g because it is never used in the UI but you still need it - or to describe the data returned from a mutation (for use with m/returning).

Imagine you have a login mutation that needs to return information about the user’s session:

(This example is taken from RAD Demo.)

Another example (TODO: Find a better, more realistic example.) - for some weird reasons / optimizations, you want to know the size of each people list, enemies and friends alike, as soon as possible in your application:

The mapping between defsc and Data Entities does not need to be 1:1, you might have multiple components displaying different views/parts of the same data entity at different parts of the UI tree. For instance you might want to display a short PersonView in a people list and a full PersonDetails when the person in question is selected. The solution is to define the two components with the same :ident. They both will query the ID property and will typically request some different and some shared properties. The data of both will be stored at the same place in the DB. (See 9.1.5. Server Result Query Merging for details about how the data is merged.)

Example:

You might want to split a single, large Data Entity over multiple UI components, each displaying a distinct part of the entity, instead of creating a single, huge component. This is similar to the Multiple UI views above but in this case you want to display all the sub-components at the same place in the UI tree.

For example you might want to split Person into PersonIdentification, displaying the name and email, PersonDemographics, displaying the age, location, and salary category, etc.

All these properties are directly a part of the same data entity, contrary to standard joins such as :person/children. So how to do this? Pathom placeholders to the rescue! As described there, we use the "magic" :> namespace for our "flat joins", i.e. to introduce an artificial level of structure to our flat data (notice that this is a Pathom invention, for Fulcro it is a join as any other):

As regarding data fetched, the Person query will be equivalent to :person/id :person/age :person/location :person/salary-cat :person/name :person/email though the data returned will be in the requested structure, i.e. {:person/id "…​", :>/demographics #:person{:id "…​", :age 42, :location "…​" :salary-cat :10k}, :>/identification #:person{:id "…​" :name "…​" :email "…​"}}.

Normally only the Root component can see "global" data, i.e. data that does not belong to a Data Entity. For example, Friend is a data entity with props and an id but the set of all friends is not a data entity. You would typically do something like (df/load! app :all-friends Friend) to get the data into the client and could then query for it via {:all-friends (comp/get-query Friend)} in the Root. But you might be imagining a structure like this:

i.e. you want to pack all your friends into the MyFriends component and you want to make it responsible for laying out the display of them. Thus the UI-only component pattern is not applicable because you want MyFriends to control the "instantiation" of its Friends children. So MyFriends is the root of its own, separate data tree that we want to place somewhere in the total UI tree. There are multiple ways to do that.

Note: We cannot use the Pathom placeholder :>/ approach as we did above because it only works for data entities, on the side of Pathom, where it is used to introduce an extra level of nesting to a data entity. But here we are working with a non-entity.

If you have a piece of data that multiple components, at different parts of the UI tree, need to access then the simplest solution is to put the data or a reference to the data into the root of the client DB and to use Link Query (as described above) to access it from those components. A typical candidate is the current user session or some user’s selection that multiple components need to see, for example "current student" in a student management webapp.

Use df/load!'s :target to relocate the data or add an extra link to it (e.g. :target [:selected-student]) (read load!'s docstring to learn about details).

Then, any component’s query can be :query [... [:selected-student '_]] (and you can of course also make it a join, to select the attributes of the student you want: {[:selected-student '_] [:student/email]}).

What if you want more structure in the UI then is present in the data? For instance if you insert a Fulcro’s Dynamic Router between two components or if you want to have a separate component to render a list of children. Sometimes you can solve it with Pathom placeholder (see above), which is simplest, but sometimes you need a different way. Let’s explore that.

Imagine you have a Team that has a number of Players and, instead of showing all the players, you want to show them as a "slide show", i.e. just one at a time (likely with buttons to navigate to the next/previous). So while before you had this UI tree:

now you have:

How can this work? In the data, a team has a list of players but a team has no "router" (problem 1️⃣) and how would the router know what players the parent team has (problem 2️⃣)? The Team can query for [:team/id {:team/players (get-query Player)}] but if we change it to [:team/id {:ui/router (get-query Router)}] (where the Router query itself is something like [::dr/id {::dr/current-route (get-query Player)} …​]), where did the players go and how can the Player inside the Router access the player entity? A router is just a router and has no players?!

The key to understanding is that the normalized data Fulcro stores in fact represent a graph and we can easily add extra "edges" to it. In this case we add an edge from the Team to the Router under :ui/router(achieved by including the router’s initial data in the Team or via pre-merge) - answering 1️⃣ - and another one from the router to the Player it should display under ::dr/current-route (set by (dr/change-route …​), in this case together with Player’s :will-enter and its (dr/route-immediate <ident>)) - answering 2️⃣. The following figure illustrates it:

And this is how it looks in the client DB:

and thus the query [:team/id {:ui/router […​ {::dr/current-route [:player/id …​]}]}] can be resolved into {:team/id 1, :ui/router {::dr/current-route {:player/id 4, …​}}}.