Upgrade Your Drupal Skills

We trained 1,000+ Drupal Developers over the last decade.

See Advanced Courses NAH, I know Enough

Visualising content models in Drupal

Parent Feed: 

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:

http://www.plantuml.com/plantuml/umla/NLB13i8W3BttAtOssGzuC3leLJzXGMYKX34omCI_Tnbx0tlf-bxRrvPkY4ajAK-EI3iLOxSYgnsFwHkOMj2Tk_lZUaCUVzYdabLTaHDuYREdyf4nfpJJPcL4lPXM0nv-ceFL4KXbOzbhZc9mp8nYGDI3Q2Kg9zS77VBJsVXcCngL-EyDolfe1x0t0qGhCA8HoEtRjYWwj5dnJ90aE4VycBllJqrQ9OjgPN9_aOlN2Awu3zbgWe8Yy5eb_W-mvUhbXgqI60WDx4sUt0y0

And the resulting image:

http://www.plantuml.com/plantuml/png/NLB13i8W3BttAtOssGzuC3leLJzXGMYKX34omCI_Tnbx0tlf-bxRrvPkY4ajAK-EI3iLOxSYgnsFwHkOMj2Tk_lZUaCUVzYdabLTaHDuYREdyf4nfpJJPcL4lPXM0nv-ceFL4KXbOzbhZc9mp8nYGDI3Q2Kg9zS77VBJsVXcCngL-EyDolfe1x0t0qGhCA8HoEtRjYWwj5dnJ90aE4VycBllJqrQ9OjgPN9_aOlN2Awu3zbgWe8Yy5eb_W-mvUhbXgqI60WDx4sUt0y0


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.

Conclusion

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?
 

Original Post: 

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web