Adding forms into your VertiGIS Studio Workflow applications can help you to capture the information you need! By using the simple, activity-based frameworks offered in VertiGIS Studio Workflow, you can easily configure customizable forms with the questions and prompts that will benefit both your users and your business.
This Tech Tip provides an overview of building customizable forms in VertiGIS Studio Workflow. Additionally, it provides a demonstration of what forms look like to end-users in order to help you best support the individuals actually using your forms!
Video Transcription:
Hey everybody, my name is Patrick Fingler. In this Tech Tip video, we’re going to take a look at how to retrieve information collected in a form using expressions within VertiGIS Studio Workflow. Let’s see it in action!
Here you can see I have logged into the Workflow Designer, and I have an empty design area to get started. We’re going to go ahead here and use our “Toolbox” control and search for a “Display Form”. I’ll drag it onto our design canvas.
Let’s go ahead and double click our “Display Form” to customize it a little bit. We’ll start out really simple and search for a “Text Box” control and drag it onto the design area.
Each of these form elements is going to have their own properties associated with them, and more importantly, they’re also going to have an “Element ID”. So, this “Text Box” control has an “Element ID” of “textBox1”. The header control has an “Element ID” of “header” and this button bar at the bottom has an “Element ID” of “footer”.
I might want to present a form to ask the user for some type of text input. Maybe I want to ask for their “Name”. I would want to then retrieve the value of that text box, or of the name that they entered, and do something with it.
We’ll jump back to the beginning of our workflow. In order to retrieve that information and then pass it to another activity I’m going to use an “Alert”. This is going to present an alert dialog to the user. In this scenario I’m going to present a dialog of the value that the user entered dynamically into that text box. Let’s drag this “Alert “onto this form.
You’ll see here there’s some required inputs, and we have some validation warnings telling us that “a required input is missing”. For this activity to run it needs to have some text input.
You can see here if you hover over it, it’s going to tell you the type of input required – in this case it’s a “string”. The foundational scripting logic of Workflow is JavaScript so the different objects that you’re working with are going to follow the JavaScript rules and syntax. If I open this in a new tab, you can learn more about what a string is. But basically, a string is a text object.
Let’s look at some examples. This would be considered a string where you have two quotes around some text. You can also have single quotes. You can even use these backticks, which is called a template literal, to define a string.
If we go back to the workflow, the simplest method would be to hard code some text into the “Text” “Input” box. We could call this “Hello World” and we no longer have that validation warning. It’s also worth mentioning that this is the exact same as if I were to type equals and add some double quotes around this. If we have double quotes, we’re basically just saying that this is a string. I can also add single quotes or backtick notation as well. Any of those options work.
In our scenario, rather than hardcoding a value in here, we want to dynamically retrieve the value that the user entered in the form. To do that you can add a “$”. So, “=$” and this will find all of the activities within your workflow. So, for example, if I added a “Buffer Geometry” activity, the next time I add a dollar sign we’re going to see that we have “$buffer1” as well as “$form1”.
We’ll select “$form1” because we want the value of the text box within the form. I’ve now selected “=$form1”. If I add a period, you can get some code completion. So, the “result” property for the form is going to be the result of the form. Did they click submit or did they click cancel? You can see it’s also of type string.
If we drill into the “state” of the form and add a period, you’re going to get a list of all the different form elements. Here’s our “footer”, our “header”, and our “textBox1”. You can also give yourself more space using this expand control and you can use the control and scroll wheel to zoom in.
I’m going to search for “textBox1” which is our text box control. I’ll add another period, and these are going to be the properties of the text box. We’re interested in the “value”, which again is of type string, and which is the text that the user entered into the text box. Now we’re happy and the validation is correct. I’ll go ahead and click “OK”. Give this a save and call this “Tech Tip videos – Form Input”.
I can use our sandbox to run this. So, I’ll go to the info tab and click “Run in Sandbox”. I’ll go ahead and “Run Workflow”. I’ll enter my “Name” as “Patrick” and click “Submit”. It says “Patrick” so, we can see that we’re dynamically retrieving the value that I entered into that form.
Let’s go a step further and say that I need to get a first name and a last name. Let’s double click this “Display Form” and add another “Text Box”. Let’s call this “Last Name” and we’ll call this “First Name”. You can see here that this is “textBox1” and this is “textBox2”.
Let’s go back and open our “Alert”. Currently, this is my first name but now I want to include both my first name and my last name. That can be done by writing an expression. The simplest approach would be to use concatenation, where you can add a “+” anytime you want to join something. But, in this scenario we might want to add a space between our first and our last name. So, I can add “ “ and close that. So, I’m adding a space character and then I’ll add another “+” to retrieve the value of my last name. I’m going to drill into my “$form1”, go into the “state” of the form, find “textBox2”, which is my last name, add a period and get the “value” of that.
So, this will be my first name, we’ll have a space, and then this will be my last name.
Let’s go ahead and rerun this. You don’t actually have to save it when you’re in the Sandbox you can just go ahead and rerun it. We can see we’ve got my “First Name” “Patrick” “Last Name” “Fingler”. If I click “Submit” I now have a space here with my first name and my last name.
It’s also worth mentioning that as you’re designing your workflows, these element IDs don’t really make a lot of sense, so you can edit them. I might want to call this “firstName” and I might want to change the “Element ID” of this and call it my “lastName”. This makes it’s a little bit easier for me to find when I’m searching for the IDs. If I go back to my workflow and go to the alert, you can see that it’s percolating those changes throughout the rest of the workflow. So, anytime you’re referencing that form element, it’s going to replace the ID.
Similarly, see how this is called “$form1”? I could change this to “userForm” and then you’ll see here that it’s also been updated. And, as I start to drill into my form, we’ll see those changes being included. What we’re seeing here is standard concatenation. You can also include double quotes as well.
Another way of building these expressions would be using template literals, which is accomplished using backticks. So, here I’m going to add a backtick. What’s nice with this is that you don’t need to worry about single quotes or double quotes or anything like that. As I start typing I could say, this is my “First Name:” and then I want to then pass in this value, and I might want to have a space, and then this my “Last Name:”. The only thing to be aware of is that if you want to dynamically retrieve these values or these variables, you need to add a “$” in the front and a “{}” in the front and back. That will then recognize this as a variable instead of a hard coded string. I’ll just do the same thing for my last name and add a dollar sign and a curly brace behind that.
So, here this will be first name, we’ll dynamically get the first name, space, last name, and then we’ll dynamically get the last name. Within here you can see that we can still dynamically get that code completion.
Let’s go ahead and “Save” this and rerun it. I’ll do “Patrick” “F” and click “Submit”. And now you can see that it says, “First Name: Patrick Last Name: F”.
If you want to learn more about these expressions, I’d recommend going to our Documentation Center and navigating to the “Expressions” section. This is where you can learn more about the different type of expression syntax, for example the “Standard Concatenation” versus the “Template Literal” approach.
Bye for now!
Want to learn more about the capabilities of VertiGIS Studio Workflow? Click the button below for more information on what is possible with VertiGIS Studio Workflow.
Contributors