Introducing Transformers

We’re showing you two cases how you can use these

Photo by Arseny Togulev on Unsplash

Transformers are a new addition to SimplyEdit. They allow you to change the contents of a field just before it gets displayed and reverse the change just before it gets saved. This article will show two cases of how you’re able to use this new feature.

However, if you were looking for robots that transform into planes, trains or automobiles… this article might be disappointing.

Displaying dates

In an earlier article, I showed how to make a blog with just SimplyEdit. One of the features was a date and time picker, which automatically created a field with the day, month, monthName and year entries. This works fine when you select the date yourself, but what if the data comes from somewhere else, and it just has the date as a single string, like this:

<pubDate>Wed, 02 Oct 2018 08:00:00 EST</pubDate>

This is an example of the publish date of an item in an RSS feed. You can turn any RSS feed into JSON using this online service: https://rss2json.com/ , and add it to a SimplyEdit site using a Data Source.

You can alter the JSON data, but this means tying the data format to the display format, which will eventually lead to all sorts of problems — reusing the data source for different views with different date formats will become a nightmare. Instead, SimplyEdit’s transformers provides a much cleaner way to achieve the same.

<span data-simply-field="pubDate" data-simply-content="fixed"
    data-simply-transformer="day">08</span>

This code tells SimplyEdit that whenever this field is updated or rendered, a transformer named day should be applied first. So let’s make that transformer:

The pubDate field is now rendered as just the day, but the data isn’t changed, only the view is. render is a function that changes the data on its way to be displayed. extract is a function that does the reverse, changes the field content on its way to being saved back to the data.

How the transformer sits between your view (field) and the data.

The transformer “lives” on the boundary between the data and the field, but it is “owned” by the field. The this variable is a reference to the field, the DOM element on which you’ve added the data-simply-transformer attribute. The render function is called with a single argument, the data to be shown in the field. Similarly, extract is also called with a single argument, the data as it is shown in the field. Both must return data, modified or not. You must take care that render and extract together cancel each other out.

Linking titles in a FAQ

Another way you can use the transformers, is to enrich fields with extra data. For example, you want to build a page template that shows a FAQ (Frequently Asked Questions) style page. This page consists of a long list of questions and answers, and it has a sidebar with an index to all of the questions. SimplyEdit makes it easy to show such a sidebar, but without transformers it is not so easy to keep the links in the sidebar pointing to the right part of the page.

Here is a sample of the html we want to generate:

Using standard SimplyEdit lists and fields, the basic setup becomes this:

But the sidebar doesn’t yet link to the answers. Transformers to the rescue!

And update the HTML like this:

The first transformer is autoID . It doesn’t actually change the data, it just adds an id attribute to the h1field. This field just saves the innerHTML as a string to the data, and it keeps doing so.

The second transformer is autoHREF and it does a bit more. Because the field is an anchor ( a ), SimplyEdit stores not just the innerHTML but also its href, title and a number of other attributes. So SimplyEdit expects to get an object with these properties. But the field name is identical to the h1 field since we want the same html contents. So the render transformer actually takes the content as saved in the h1 field, a string, and creates a new data object for the a field.

To keep the data correct, the extract transformer than reverses this and returns just a string with the html content.

Since both fields work on the same data, the getID function returns the exact same string for both, linking them together.

You can see this example in action in this codepen: https://codepen.io/simplyedit/pen/JzEROW

This blog is written by Auke van Slooten, one of our senior developers.
Connect with us at GitHub, on social media, or leave a comment below.