Why talk again about iconography? What is there left to talk about?
In fact, iconography is a very frequent topic when it comes to developing UI for a project. Either because we need to implement a set of icons or because we need to document them in a way anybody can easily search and use an icon in an interface or both.
This is where things get a little bit messy and confusing due to the fact that, unfortunately, OutSystems doesn’t have either a simple nor direct way to implement a custom iconography (at best we can download a component from Forge to use icons from Font Awesome).
The question is: “how can we implement a set of 200, 300, or more icons, spending only a couple of minutes? Is it even possible?”.
Naturally, the answer is YES, and that’s what I will write about in the following article.
But before you continue reading, let me just state that this article is focused on using SVGs by converting them into a usable font and documenting them. It’s not about how to use an SVG on a screen in OutSystems.
What We Need to Start?
To start doing something in OutSystems, we will basically need 3 things:
- SVG icons;
- A Font Face with the icons;
- Font Face JSON file with information of all icons contained in the font face;
1. SVG Icons
As we all should know, it’s recommended that for every project, or at least is a good practice, to have a Figma (i usually use Figma but can be another design tool) document with the UI that needs to be implemented.
And as part of this Figma UI Style Guide, sometimes there’s a section dedicated to the entire iconography.
When this happens, it usually means that we need to implement all those icons in a font face readable by the browsers, making this set of SVG icons our first requirement.
Since the goal is not on how to create an SVG icon in Figma or any other platform, I am going to skip that ahead, but if you are interested, you have another article and master class video from hiinteractive where we talk more deeply on how to create a font of icons.
2. Font Face with the Icons
Personally, I am a long-time fan of Icomoon when I need to generate a font face for a set of icons. It allows us to make some alignment adjustments, edit icon names, and a lot of other settings that may be useful.
Icomoon is the tool that can help us get our 2nd requirement for our masterclass which is having a font face with all our icons extracted from a Figma document.
To cut short, here is a typical settings configuration that I usually use when generating a font to be used in OutSystems.
3. Font Face JSON file
Luckily, when we create/generate a font using Icomoon, one of the files included in the ZIP we download is a JSON file (named “selection.json”) containing the entire set of icons.
By looking at the above example, we see that we have an icon with a specific path, which is not much relevant to us but, more relevant is the attribute “name” that represents the CSS class that we will use in our CSS theme to show the icon on the screen. Within this JSON file lies the secret to documenting an entire set of icons in OutSystems in just a couple of minutes.
Document the Icons Font Face on a Screen
To document a font face of icons in OutSystems Service Studio, we need to perform just a couple of steps.
The goal is to create a simple screen showing all icon classes, a search engine, and a copy to clipboard mechanism.
1. Add the icons font face file in a theme module
To start we need to add the font face file to the theme module we will use in our project.
Typically I just upload the “.woff” file contained inside the Zip file downloaded from Icomoon.
The main reason is because it’s a compressed version of an OTF or TTF file which makes it faster to load and also is supported by all browsers.
2. Add the CSS generated by Icomoon into a CSS theme
The second logic step is to add the font CSS in our theme, allowing us to use classes to display a specific icon on a screen.
All the CSS we may need is also included in a “.css” file in the downloaded zip from Icomoon.
Just copy the content into your theme in OutSystems Service Studio, update the URL pointing to the correct path and font that you uploaded in the previous step.
This CSS will allow us to add a class “icon-client” that combined with an icon class, in this example “Status-away-outline”, we can display the correct icon on our screen.
3. Add the JSON to Resources
Next, we need to add the JSON file as a resource in Service Studio.
With the JSON file as a resource, we can access it and by reading its content, display all the icon classes that we may use on a screen.
What we also need to do (because we will need it later) is to create a structure based in the JSON file and to do that in OutSystems Service Studio is quite simple:
1. In the Data tab, right click in the “Structures” and select “v”
2. This will open a modal were you need to past your JSON file content (depending on the size, this may take a few seconds to past the entire content);
3. When done, click on “Add structure button” to generate all the needed structures based on the JSON.
The reason we need this structure is for later on, we are able to create a list based on the JSON that we can read on a screen.
4. Prepare JSON file to be displayed on a screen
Finally, to show the list of icons on a screen, the idea is to read the JSON file, convert it into a list, and display it in the form of a gallery.
This is the flow that I use to display the JSON content in a form of a gallery of icons:
1.Binary Data To Text: since we have our JSON as a resource, we first need to read it using this action from “System” that is going to convert a binary file into text to read it after in the JSON action;
2.JSON Deserialize Icons List: in this step, we are going to convert text into a list and use the previous structures as an indication of the data type we need;
3.Cycle Icons List: at this point, since we have a list, we can iterate through it in order to go through all the icons;
4.Get Icon Class: here we are retrieving the current icon name, that is the icon class;
5.Append Icon To List: next we are appending the current icon name into a list that will host all the icon names;
6.Output Icons List: in the end, we will output a list of text records that will be read/used by the screen in the form of a gallery and that we can iterate to perform a search.
After doing all the above steps, your page should end up with a fetch data similar to this one:
5. Display Icons on a Screen
To create a usable list of icons, we need to display them, give the ability to search for an icon and give the ability to very easily click on an icon and copy the class that we need to use on our screens.
1.Display icons on the screen: to display the icons, just create a screen, add the gallery component from OutSystems UI to it and use the output icons list created in the previous step 4. It’s a straightforward method that you should know how to do, has for any other list that may be coming from an entity;
2.Search icons: to create a search engine, add an input to your screen and create an action that is going to be triggered by the OnChange event of it. On that action, what you need to do is to perform a List Filter on the previous created output icons list.
Add the code “Index(Value,SearchValue, ignoreCase: True) <> -1 or SearchValue = “”” in the filter condition and use the output icons list created as the source list. This will cycle through the list and return a new list with the records corresponding to the search value entered in the input field.
In the end, just assign that new filtered list to the initial output list and you’re done.
3.Copy class to clipboard: to copy the class to clipboard, I recommend using a simple javascript function. Add a click event on each element of the gallery and in that action, add a JavaScript node:
var textToCopy = document.querySelector("#" + $parameters.WidgetId).innerText; - Create a temporary textarea element to hold the textvar tempTextArea = document.createElement("textarea"); tempTextArea.value = textToCopy; $parameters.Class = textToCopy - Append the textarea to the DOM document.body.appendChild(tempTextArea); - Select the text in the textarea tempTextArea.select(); tempTextArea.setSelectionRange(0, 99999); // For mobile devices - Copy the selected text to the clipboard document.execCommand("copy"); - Remove the temporary textarea document.body.removeChild(tempTextArea);What we are basically doing here is to get the text (using innerText) inside a widget (that is the place you are displaying the icon class on your screen).
Use the output (here represented by “$parameters.Class = textToCopy”) to display a feedback message on the screen saying something like “Class copied to clipboard” to indicate to the user that he can now pass the icon class to its component.
Update the Font Face
To update the font face, the process is quite easy since all you need to do is to change the JSON file in the resources for a new one.
Conclusions
Over time, I found that this process is the best one I found so far. This allows a very easy update font (which is something that almost surely will happen in the future) making virtually zero effort to keep the font.
Also, even if a font has hundreds of icons (and I’ve already used this method with fonts with over 420 icons) it only takes like a second to load the icons on the screen which I don’t consider a problem in this context and finding an icon is not something that would require an instant response but even so, having all the icons in an entity (static or not) would also take some time.
Another advantage is that by using a JSON file, if we need to send our screen to a different OutSystems server (like test server) we don’t need to maintain an entity or even a static entity (which occupies a lot of space and memory), the JSON may occupy something like 20KB for larger fonts.
