A couple of the most common things you might want to do on you forms is get the value of a field or set the value of a field. Getting the value that a user has entered allows you to validate the form or drive form field behavior with disable rules. Being able to set form values can help make the user experience faster and more enjoyable. You can do a lot with the simple ability to get and set form field values. The following post will get into the myEvolv functions getFormElement and setFormElement.
The getFormElement function returns the value that is entered in a form field. The function takes a single argument– elementName
The elementName is the name of the column used for the form field, NOT the caption. So for example, if I want to get the value of the Actual Date/Time field on the form, I would use
The setFormElement function sets a form field’s value. The function takes two arguments — elementName and elementValue
The elementName is the name of the column used for the form field, just as with getFormElement. The elementValue is the value you want to set the form field to. If I wanted to set the remarks field to “Approved!”, I would use
Some additional considerations are again needed with dates and times – the elementValue must be a formatted date string. And for a lookup table, you must provide the GUID of the item you want to be select.
Where to use?
Before Save Code
This code executes right after the user clicks the Save button on the form but before the Save function executes. This makes it a good trigger for code that you want to run one time after the user has entered values in all of the fields. This might be a good candidate for code that will calculate a value based on the values entered in several fields on the form. You might not be able to trust the order that the users will fill in the values so triggering them at the field level might be tricky.
Note that at the point this code executes, you can no longer manipulate the DOM of the form and have those values become part of the Save function so you have to instead use the setElementFromXML() function (I will cover in another post) to get the calculated value into the save.
After Save Code
This code executes just after the Save function executes in the system. Because of this it is mostly used for popping up alerts or keeping windows open after saves.
This code will execute after the Delete function executes. I have not used this one yet. It could be useful for popping up alerts.
Before Load Code
This code will execute before the form XML is rendered into HTML and displayed on the screen. There is a note that this code does not run on forms when they are used as subforms.
After Load Code
This code will execute after the DOM is fully loaded and the form is displayed on the screen. This trigger would be good for popping up alerts when the form is first opened.
On Load Script
On Click Script
This code triggers when the form element is clicked. It works best for checkboxes but you can get it to fire for other form fields as well.
On Change Script
This code triggers when the form element’s value is changed. This one does not work great with checkboxes but is perfect for date/times, strings, foreign key id fields.
You can use getFormElement() in the disable rule property to determine if a field should be disabled or not disabled based on the values retrieved. You return
true if you want the field to be disabled and
false if you want it to be enabled.
What about Memo fields?
Memo fields are a little more complicated than the other form fields in how they generate in the DOM and so setFormElement() does not work on them. Instead, you must use the setMemoField() function.
The difference between this function and setFormElement is that the first argument here is for the GUID of the Memo field’s form field id and not the column name. So to make this usable, you should pair it with a getDataValue() call to grab that form_lines_id.
The following code will get the form_lines_id of a memo field on the form (form_code = “MY_TEST_FORM”) that is captioned ‘My Memo’. It then uses that GUID value in the setMemoField() function to set MyMemo to ‘Updated text value.’
var formLineId = getDataValue('form_view', 'caption', 'My Memo', 'form_lines_id', 'form_code=\'\'MY_TEST_FORM\'\'');
setMemoField(formLineId, 'Updated text value.');
When reusing this code on your form, you just need to change the caption (‘My Memo’) to be the caption of your memo field, the form_code (‘MY_TEST_FORM’) to be the form code of the form you are putting this code on and then your updateText (‘Updated text value.’). You must be sure that your Memo field has a unique caption on the form you are using– you cannot return more than one value with getDataValue().