Working with Blockly scripts
Scripts in iCL Designer provide a variety of ways to change answers dynamically, restrict visibility, perform calculations, and more. At the same time, scripts are very approachable, as you do not need to have programming skills to use them, although it doesn't hurt to have some. This is achieved by using Blockly, a powerful script tool that allows you to define scripts similar to assembling a puzzle.
In this guide, we will explore the possibilities offered by Blockly scripts.
We'll be using the workbook that we created in the previous tutorial - with a few changes.
Before we start this tutorial, we need to refactor our workbook a little bit. Let's create a new chapter called 'General information' where we move the 'Building' headline. From now on, we create a new chapter for each floor (not just a headline), so the 'Check' headline should not be repeatable anymore. You will soon see why these changes were necessary.
Introduction to Blockly scripts
In iCL Designer, a little puzzle icon next to a property indicates that the property can be scripted. Titles are for example always scriptable, as well as the 'Exists' and 'Hidden' properties. In case of questions, we can script many more properties, e.g. 'Mandatory', 'Readonly' or most importantly, 'Scripted answer'. You can find the complete list of scriptable properties here.
Titles
If you've been following the whole series of this guide, you have already got some insight into the world of Blockly scripts. In the Adding repeatable sections guide we created a script to dynamically change the title of a headline. First of all, let's move this script to the chapter's title as the chapter is now the repeated for each floor, not the headline.
You can copy-paste headlines by right-clicking on them. First, right-click on the existing script and select 'Copy'. Then, select the chapter node and right-click on the puzzle icon next to its title, you can then paste the script. The only thing left is to select the headline again, right-click on the script again and click 'Delete'.
Let's improve this title script a little bit. Instead of just the name of the floor, we could concatenate the word 'Floor: ' and the name of the floor.
You can open the Blockly editor by double-clicking the already existing script.
Blocks are grouped into tabs to make them easier to find. Each group has its own color to make them even more distinct.
For example, text related blocks are green.
To concatenate texts, we can use the 'Create text with' block which can be found in the 'Text' tab.
The first blank block in the 'Text' tab is a block that allows you to add any (translatable and non-translatable) text. Combining that with the 'Create list with' and with the already used 'answer of floor' blocks, we can reach our goal.
The 'Translatable' checkbox has a role only in multilingual workbooks, otherwise it doesn't matter whether it's checked or not. Read more about multilingual workbooks here.
Some blocks (like 'Create text with') can be customized by clicking their blue settings button. For instance, in case of 'Create text with' block, you can specify the number of inputs of the block, which allows you to specify how many texts you want to concatenate.
We can also script the checklist's title using the building's address similarly:
These small title scripts may not seem like a big deal, but they can be really helpful in repeated areas as it's easy to lose track of what that area contains since they share the same name. You can avoid this confusion by creating a simple script which shows the answer of a question within that chapter or headline.
The result in iCL Filler is the following:
States of a question fields
Each question field has 4 scriptable properties with boolean (yes/no) answers: 'Mandatory', 'Exists', 'Hidden', 'Readonly'. These properties can also be changed dynamically using Blockly scripts.
Before we see an example for them, we need to refactor our workbook a little bit more. In case of a safety violation on a floor, it would be much more useful to collect more information about the issue. To do so, we create a new headline called 'Defect' where we can add a few more defect-related questions alongside with the already existing 'Description'.
Previously, the 'Description' field was a follow-up field of the 'No' answer of the 'Is the floor safe?' question. This solved the problem that the question must only exist if something is wrong at that floor. This concept is true for the newly created headline as well, however, headlines cannot be added as follow-ups.
We can solve this using the 'Exists' script of the new headline.
The 'Defect' headline should only exist if:
- the question 'Is the floor safe?' has an answer,
- and the answer is 'No'.
The whole script is as follows:
Let's break it down step-by-step.
Open the Blockly editor for the 'Exists' property of the new headline. Firstly, we use the 'test - if true - if false' block from the 'Logic' group because if the above described criteria is met, we want to return true, false otherwise.
We want to check 2 conditions and we return true only when they both are true - this can be reached by the 'and' block from the 'Logic' group.
Now we use 2 blocks from the 'Checklist Fields' group: the first is called 'has value'.
When using the value of a field in a script, it is always a good idea to first check that the field has a value, because all scripts (except of scripts for Title and RepeatFor) will be evaluated regardless of whether all dependent fields have a value. Therefore, if you do not check if a required field has a value, you may end up with script errors while using the form which may break other scripts as well! When using the value of a field in a script, it is always a good idea to first check whether the field has a value.
So first, we check whether the 'Is the floor safe?' question has a value. If it does, the second condition to check is its answer. To check that, use the 'is one of' block from the 'Checklist Fields' group.
The 'is one of' block checks whether one of the answers specified in the right input is selected for the question given in the input on the left.
You can easily drag&drop answers too, it works just like by question fields.
Let's add two more questions to the 'Defect' headline.
We added a 'Yes/No' field and an image field (called 'Take a picture' in iCL Designer) so the inspector can take a picture of the problem.
There is no star next to the name of the 'Photo' field. It means it's not a mandatory field. However, if the defect is very dangerous, a photo should be mandatory! Do you have an idea, how to do that?
Show me the solution!
The script in the 'Mandatory' property of the image field should be:
Let's see this in iCL Filler.
The first thing you can notice is that when the floor is set to not safe, the 'Defect' headline appears. Then, when the defect is set to very dangerous, a red indicator on left to the 'Photo' field appears, indicating that the field became mandatory. Also, notice that when the photo question turns mandatory, the indicators showing the number of mandatory questions increase their values accordingly.
Values
Blockly scripts also allow you to answer questions dynamically. You can create answers using one or more other fields, do calculations, create complex texts or more. Let's see a few examples!
First, let's script the answer of the date field in the 'Conclusion' chapter. This date should always contain the current date. The 'now' block is for exactly this case.
Add a new headline to the 'General information' chapter, call it 'Inspector'. Within that headline, add a new text field 'Name'
You can query some information about the current inspector using Blockly blocks from the 'User Properties' group. For example, we can create a script to set the name of the inspector automatically. To do so, we concatenate the first name, a space and the last name. Therefore, we need to modify the 'create text with' block so it has 3 inputs.
Let's see a last example. Add a readonly text field to the 'Conclusion' part.
The goal of this text field is to show a short summary like this: "This inspection was made by Antoine Gadget on 20/05/2023."
If you want to challenge your knowledge, try it on your own! Tip: you need a block from the 'Formatting' tab.
Show me the solution!
We will start with the 'create text with' block again.
In the first input, we add a static text block with the text: "This inspection was made by ".
The next input contains the name field from the first chapter.
Then, add another static text: " on ". Don't forget to add spaces on both sides.
In the next input, use the 'format date as' block from the 'Formatting' group. The default formatting is dd/MM/yyyy which is exactly what we want. Of course, you can choose any other formatting you like.
Then, add one last input where you add a static text again with a "." to close the sentence.
You can download the improved icl file from here.
Value scripts vs. transient scripts
The evaluation of scripts in iCL Filler differs depending on the type of the script.
We distinguish between two groups:
- value scripts (scripts that have an effect on a value of a field)
- transient scripts (scripts that are re-evaluated every time)
Value scripts are 'Scripted answer', 'Exists' and 'Repeat for' scripts. Everything else is transient script.
Value scripts are only evaluated once when they're loaded for the first time. For example, when the checklist is created, a headline or chapter is added manually, or a follow-up field with a 'ScriptedAnswer' script is added as the parent question is answered.. After that they are re-evaluated only when any of their dependencies has changed. For example, in case of out last 'Conclusion' text field: it has a 'Scripted answer' script which is a value script. This script depends on 2 fields: 'name' and 'date'. If any of these fields changes, the script is re-evaluated.
Transient scripts' values are not stored, they are re-evaluated every time when they're needed. For instance, the 'Mandatory' script of the image field is transient. If we navigate to another chapter, then back to it, the script will be re-evaluated.
💡 You can read more about script evaluation here.
Conclusion
This tutorial introduced you to the world of Blockly scripts. Using scripts can make your workbooks more efficient and powerful.
There are many more use cases for Blockly scripts that this tutorial did not cover, for example there is a 'Math' group which contains blocks for mathematical calculation, in the 'List' tab you can find many blocks that allow you to create, filter, modify lists, etc. With scripts you can do (almost) anything, the sky's the limit.
You can find a complete list of all Blockly blocks here.