¶ Understanding Molecule and mapping
¶ Data-molecule
Starfish allows you to create websites with dynamic content - e.g. content from the PP Dashboard. It allows us to update the site with every change made in the dashboard.
In order to make all this content available, we have a Content Molecule. The Content Molecule is a JSON file that includes all the public data of a practice in a structured single place.
¶ General structure of the molecule
If you’re familiar with JSON or XML files - you’ll find the molecule structure very familiar. It’s a tree based structure with key-value pairs:
Here’s a general diagram of a molecule:
¶ Content injection using {{mustache}}
We’re using a simple templating language called {{mustache}} to mark where a dynamic content should be inserted in a text. Starfish will replace any {{ ... }} with the relevant content from the molecule. Site-Creator will use the string inside the {{}} as a Path to find the relevant part in the molecule.
So let’s say you want to insert the name of practice - Artemis - in a text, and make it dynamic, so if the practice will change its name, it’ll update automatically:
- We’ll find the path to the data we wanna use, in this case: identity.name
- We’ll insert this path in a
{{}}instead of the static content we want to replace, in this case: Artemis. - That’s it! When the site will be previewed or published - the content from the molecule will be used instead of the mustached text.
- Static text:
Hi, we are Artemis.
- Now the templates text:
Hi, we are {{identity.name}}
¶ Mapping a Section
Sometimes, you may want to add “context” to a section. Adding context assigns a specific section to be about a specific molecule. For example, the services section on the homepage may have the section context /services/items. This tells the web editor that all of our molecule mapping for this section will pertain to the service molecule.
Context places you in a specific path in the molecule. If a section has context - any element mapping will be relative to the section content.
¶ Map Items to Nodes
This option allows you to map each section item to a node in the molecule - it’s super useful in galleries and slideshows - as you can tell Site Creator to duplicate the items in a section as many times as the molecule has children.
Let’s say you want to display a gallery of all the providers:
First, you set the Section Context to providers/items. Then, you choose “Map Items to Nodes”.
Site Creator will duplicate the items to match the number of childrens (nodes) in the molecule!
Drawing 8.5a - There are 4 items in the providers/items node, therefore there are now 4 items in the Section.
Now you don’t want the same content in each item right? You want to display the relevant name, picture etc... For this we have an ability to map element’s content to a specific key-value pair. Learn about it in our next explanation - “Mapping Element’s Content to a specific key”:
¶ Mapping Elements content to a specific key.
This allows you to tell Site Creator which Key-Value-Pair to use for each of the elements’ content.
Let’s get back to our providers’ gallery example. We now want each item to show the relevant name as a title.
We’ll find the item’s title mapping, and place the relevant relative path: Title: {{name}}
Why do we place only {{name}} and not {{providers.xxx.first_name}}? Because the item already has a context of each item, because we’ve enabled “map items to nodes”.
¶ Mapping a Page
Sometimes, you may want to attach “context” to a page. Attaching a context assigns a specific page to be about a specific molecule’s items. For example, the provider page, once assigned to /providers/items page context - will be duplicated for each item in the molecule. Each duplication will be connected to a specific item.
