Placeholders allow the user to add structure to some EQL request. They work as a special
attribute namespace, by default, Pathom recognize any attribute with the namespace
a placeholder attribute.
You can configure the placeholder namespaces by setting the option
in the env, the default value is
In this guide, you will go over a few examples of how to use placeholders.
You can use placeholders to provide in-query data for Pathom processing. To do this, lets get back to our famous full name example, the way to provide data is to send it to a placeholder key as EQL parameters:
When moving to a placeholder context, Pathom inherits the same parent data and merges the params data to it, to illustrate let's make a nested example of it:
Placeholders data parameters is a new feature of Pathom 3, not available in Pathom 2.
Compose different views
For this example, consider a system where you make a UI out of components, and each component has its query to express its data needs. Here are some of these component queries:
One thing these queries have in common, is that they are "about" the same entity, always the same customer, but different data about it. You might be tempted to just concatenate the queries, something like:
Then run this query and send the full result to all the components, and for this specific example that would work, but I need to point some problems with this approach to you:
Let's add a new component to this system that breaks the previous solution, this is the new component:
Note this component uses the same attribute that
latest-orders-eql did, but it uses
EQL parameters to affect the request. Now we have two components that need the same
attribute but with different data. This is not possible and causes an attribute
conflict for the planner.
To have those two points of data in the same response, they need to be at different places.
Another problem with merging the queries is that the code gets data it didn't ask for. To illustrate this, let's imagine the following code to display the data from the address component:
Now we also want to display the user name, so we change it to:
If we use the previous combined query, without changing the
address-eql to also ask for
code "accidentally works", because
header-view-eql was asking for
:acme.customer/full-name. This can turn into
big headaches in the long run because by changing one component, you may affect other components.
Solving with placeholders
The solution to fix the previous issues is to put each component into a different placeholder path, this way each one gets full isolation from each other:
This way, Pathom guarantees isolation for each path, no more shared data, and each component can ask different params, and Pathom knows how to deal with it.