Visualising content models in Drupal
Creating a visual representation of a content model can help clients better understand the internal design of their website and how the pieces fit together.
Drupal has rich content modelling capabilities. Using entities and fields it is possible to build out content models which can develop into being quite extensive. During the definition phase of a project all of the details are typically captured in spreadsheets which are helpful for communicating the model to developers. However, the tabular information can be difficult for clients to follow as the types and relationships are not being presented in a visual way.
UX designers will typically use a variety of tools to communicate design ideas to clients. These include:
- Visual sitemaps demonstrating hierarchy
- Wireframes demonstrating page layout and user flows.
Unfortunately the content model, the structure underpinning these other concepts, is generally overlooked.
UML to the rescue!
One solution is to provide a simplified UML diagram which shows the relationships.
For those familiar with UML it probably conjures up memories of enterprise software development in the 2000s. It does for me anyway. UML provides a number of data modelling concepts typically used for capturing class and interface information for software development. It is fairly obtuse and can be intimidating to author and to understand. That probably explains why my UML in a Nutshell book went largely unread. I was hoping to learn it via osmosis but unfortunately that never quite happened.
Fastforwarding back to 2021 I have turned my attention back to UML. In the search for a rapid way to visualise Drupal content models I went on the search for a quick and accessible way to author and visualise relationships. I stumbled across PlantUML which is an online tool which will allow you to quickly author a variety of diagrams, including class diagrams. It uses an intuitive text based format for authoring, allowing diagrams to be nicked out in 15 minutes or so. This is a very low barrier for something which is so useful.
Plant UML has two killer features which make is enjoyable to work with:
- Diagrams are available via a URL, which include all of the data, making them very easy to share and modify.
- PNG images are available via a URL as well, making them easy to embed into documentation.
Here is a simple example of a simple content model:
And the resulting image:
The document is as follows:
@startuml class article_type article_type : NODE class event_type event_type : NODE class person person : NODE class place place : NODE class page page : NODE page : topics page : audiences class article article : NODE article : topics article : audiences article : article_type article : published_date class event event : NODE event : topics event : audiences event : article_type event : event_date class topic topic : NODE class audience audience : NODE article --* audience article --* topic article -u-> article_type article -u-> person event --* audience event --* topic event -u-> event_type event -u-> place page --* audience page --* topic @enduml
You can see that it is pretty easy to get up and starting using a system like this.
I must say that the diagrams I am making are not 100% rigorous and so UML purists should probably not get upset if there are errors in there. The aim is to come up with something which is simple and conveys an idea.
Building an understandable diagram
There are a few key aspects of the diagram which make it easier to understand.
Layered approach: The various Classes can be layered by indicating to PlantUML what the direction of the relationship should be. You will notice “u” characters in the relationships. This standard for “up”. With this little helper we are able to bring some presentation to the diagram.
Characterising the classes: Once we can layer the diagram it can be arranged to group the classes into different conceptual layers. When communicating to clients I tend to speak of classifiers, items and categorizers.
- Top: Classifiers (sub typing entities)
- Middle: Items (editor entities for content)
- Bottom: Categories (buckets for grouping content)
These layers can help clients understand how different content types play a role in underpinning the structure of the site. This is particularly helpful in discussing how facets might work and how content can be surfaced in different areas of the site.
All up we have found PlantUML a very helpful tool with a low barrier to entry. It has helped significantly in helping clients understand what is happening under the hood of their site.
What tools do you use to visualise content models?