Skip to main content

myEvolv Tips: Subform Field Manipulation

Credit for figuring these out/discovering them goes to Perry. I find myself referring to them in a training binder I got from last year’s NY Training Summit and figured it would be easier to just get them up on the web so I don’t have to go hunting for that binder every time. The following code works for Classic.

Subform Considerations

Subforms have to be handled differently than forms when it comes to JavaScript because while in the form designer, the two things look identical, the way that myEvolv renders a subform in the browser is very different from how it renders a form. But it isn’t radically different and the main changes account for the fact that a subform can have one or more rows and so you need to be more specific about which field you are trying to manipulate so that you don’t change every line simultaneously.

Scenario 1: Get the Value of a Subform Field

This code is for use within the subform, e.g. if you want to default the value of one field based on the value of another on the same subform.

self.getElementFromXML(currentRowXML, 'column_name');

Note the self object is being used here. This is the subform object as distinguished from the parent form object. The parameter currentRowXML then further narrows it down to the current record/row on the subform that you are concerned with.

Scenario 2: Set the Value of a Subform Field

Again, for use within a subform, this code can be used to set the value of a field in the same subform, e.g. when you want the On Change event to auto-populate a field.

this.form.'column_name'.value;

If you are checking a checkbox, use this code:

this.form.'column_name'.checked = true;

Note that in this code, you do keep the single quotes in the code for it to work properly. All you change is the column_name

Scenario 3: Get the Value of a Parent Form Field

With this code, you can get the value of a field in the parent form based on an action in the subform.

window.parent.getFormElement('column_name');

Note the window.parent is the only difference from the code you would use on the parent form. This is what allows your code to ‘jump up out of the subform’.

Scenario 4: Set the Value of a Parent Form Field

Maybe you figured it out by now but you can use the same small change to set values on the parent form from the subform.

window.parent.setFormElement('column_name', value);

Scenario 5: Trigger an Alert from the Subform

Alerts are useful in guiding user activity and you can trigger them from subforms. Similar to the last two, the trick is moving back up the DOM to the parent form to trigger it.

window.parent.window.alert('Alert Message');

Other Possibilities

It is possible to go the other way and get and set values on subform records from the parent form, however, it becomes a much more complex problem that requires very specific solutions for very specific challenges. That is because of the One-to-Many relationship that the subforms have with the parent form. For these types of situations, you will probably be targeting the subform itself and then looping through each record to get or set values.

How To: Enforce ZIP+4 in Client Demographics

Some payors are beginning to require that client addresses utilize the ZIP+4 ZIP code in order to get paid.  The ZIP code field in myEvolv has a datatype of Zip Code which appears to be a string field that allows up to 10 characters.  This means that you can store a 5-digit ZIP code or a ZIP+4 in the field.  Furthermore, the functionality for auto-filling the city and state fields based on the ZIP code will work with either type of ZIP code.

One thing that is lacking is the ability to force users to input a ZIP+4 in the ZIP code field.  The following guide will show how you can add some form validation to the Client Demographics form that will help to prevent users from entering only the 5-digit ZIP code.  While we will be looking at only one set of forms, you should be able to apply the same changes to other forms and address subforms to achieve the desired result elsewhere in the system that addresses are collected or edited.

Setup New Demographics Formset Member

For the purposes of this demo, we are going to modify the Client Demographics form.

This is a system form and we cannot directly make changes to it so instead, we must create a custom demographics form, address subform and formset member so that we can make the changes we want.

Copy the ‘Address by ZIP code‘ Form

This form is in the Address Info for People form family. This is the form that is used for the Personal Address subform on the Client Demographics.

Copy the ‘Client Personal Information‘ Form

This form is in the Personal Information form family and is listed at the top as the default form. This is the main form that loads when you go to the Client Demographics formset.

On your newly-copied, custom version of this form, swap your custom Address by ZIP code subform in for the default Address by ZIP code subform.

Remember that when you copy and begin editing these system forms, a good rule of thumb is to only add to the form or carefully edit what is on the form so that you do not have downstream effects. Avoid deleting elements. If you don’t want them to be visible, simply hide them.

Create New Formset Member

Select the Client Personal Information FormSet in Formset Maintenance. By Default, the Client Demographics formset member is ordered #1. Add a new formset member and copy the settings for it just like the system default Demographics formset member EXCEPT that we will be using our custom Client Personal Information form instead of the system form in the Default Form field.

With the new formset created, remember to make it available to all navigation schemes which need the ZIP+4 validation. In order to avoid confusion, you can make the default formset member unavailable to those with the new formset.

Pro Tip: I temporarily put “TEST” in the Tab Caption of my custom formset so that I could find it easily when adding it to the navigation schemes.

You now have a separate and customizable Client Demographics formset to play with in your system

Modify Forms to Validate for ZIP+4

We will need to make changes to both of our forms in order to cover all of our bases. Our method for validating is to check the subform zipcode field when it is changed and determine if the zipcode entered is comprised of 10 characters. If the zip code is other than 10 characters, we will alert the user that they must enter a ZIP+4. If they ignore the warning and attempt to save anyway, we will prevent the save and alert them again that a ZIP+4 must be entered.

Custom ‘Client Personal Information’ Form

Step 1) Add a variable to the form just above the Personal Address subform. This variable will be used to store our ZIP code validation state that we will check before saving.
I named my variable is_zip_invalid and gave it a Regular Numeric datatype. You can set your variable to be not visible.

Step 2) Add the following code to the form’s “Before Save Code” property:

if(getFormElement('is_zip_invalid') == '1'){{
alert('You must use ZIP+4');
formValid = false;
}}

The code above checks to see if the value of the variable we just created is ‘1’. If it is, then it gives an alert and tells myEvolv to abort the save because this form is not valid. On the subform, we will add code that will set the value this variable based on what is entered in the zip code fields.

Custom ‘Address by ZIP Code’ Form

Step 1) Add the following code to the ZIP Code field’s “On Change” property:
This code can go under the setAddressFromZip(this); line.

var zip = self.getElementFromXML(currentRowXML, 'zip_code');
if(zip.length != 10){{
window.parent.window.alert('You must use a ZIP+4');
window.parent.setFormElement('is_zip_invalid', 1);
}} else {{
window.parent.setFormElement('is_zip_invalid', 0);
}}

The code above creates a variable named zip and assigns it the value that user enters into the ZIP Code field. The script then checks to see if the value is 10 characters long. If it is not, the code produces an alert to remind the user that a ZIP+4 is required and then sets the value of is_zip_invalid on the parent form to 1. If the value is 10 characters long, the script sets the value of is_zip_invalid on the parent form to 0.

Step 2) Add the following code to the form’s “Before Save Code” property:
Since it is possible for users to open the subform in a new window, we also need to do some validation on the subform itself in case a user ends up adding or editing addresses via this method/

var zip = getFormElement('zip_code');
if(zip.length != 10){{
alert('You must enter a ZIP+4 in order to save');
formValid = false;
}}

The above code does the the same thing that the “Before Save Code” from the other form does. The only difference here is that we have direct access to the value entered in the ZIP code field so we use that to validate the form rather than the variable flag.

When put altogether, you will have a custom Client Demographics formset that will warn users at the time of changing a ZIP code field if they are not entering a ZIP+4 and will not allow saving until the ZIP code is fixed.

One Vulnerability

The way that this is setup, the value of our variable is_zip_invalid is changed any time a zip code is updated so if the last zip code altered is valid, all zip codes will be accepted as valid. So for example, let’s say that I edit two zip codes on the form. On the first one, I only put in the 5-digit ZIP code. I get an alert telling me to use the ZIP+4 and my variable gets assigned a value of ‘1’. Next, I close the alert and alter the second ZIP code and this time I enter the ZIP+4. Our code executes to check that the ZIP code I entered here is valid. It sees that it is and assigns our variable a value of ‘0’. The form will successfully save even though I still have a 5-digit zip in the first address that I edited.

More complicated code might be able to do a more thorough job of validating multiple zip codes before save but I haven’t figured that out yet.

How To: Use a Default Value on a Progress Note

EDIT 8/3/2018: Reader Rosemary asked about using text templates in conjunction with this code rather than including the raw HTML in the JavaScript code. Indeed there is a way to do that, so I have included that method at the bottom of the post. Reviewing the post also exposed that my code had a syntax error so I fixed that. Thank you, Rosemary!

Progress notes in Evolv are system fields in myEvolv that have special properties that make them particularly useful in certain situations. For example, the Progress note field is included in many of the views available to subreports so being able to use the progress note column on a form allows the data contained therein to be fed back on other forms via subreport.

Unlike other form fields, however, you do not add a progress_note field to your form in the form designer. Instead, you add the progress note in the Event Setup area by checking the “Has Single Note” checkbox.

has-single-note-checkbox

Just like with the Service Related Encounter Information that I addressed in another post, checking this checkbox will append fields to your form at the time that the event is launched. Unlike the Service Related Encounter Information, however, there is no way to add the progress note field to your form in the form designer so that you can manipulate its attributes. It is therefore tricky to set a default value for the progress note, but not impossible. The following guide will show how you can use jQuery and the form header attributes to simulate the use of the default value attribute on a progress note field. This can be useful for defaulting in a template when you know only one template would be used and you want decrease the risk that the clinician forgets to apply the template.

How Memo Fields Render

One of the things that makes manipulating a Memo field more difficult in myEvolv is that they are a much more complex field being rendered on the form. With a custom_string type of field, for example, there is just a label/caption and an html input field so you can use some pretty basic javascript to get and set the value of the field or use some of the formfunctions.js functions to get or set the form elements.

Memo fields, on the other hand, have their own menus for manipulating the formatting of the text and spellcheckers, etc. When you are dealing with a Memo field, you are actually dealing with an iframe element that contains a series of div elements that hold those buttons and then finally, buried deep in the iframe you will find a div with the id of “Composition”. That is where the text value of the memo resides.

Further complicating things is the fact that unlike other types of fields that you can easily target by column name, Memo fields must be targeted by their id, which is the GUID that represents their form_lines_id.

Accessing the Text Value of a Memo Field

To target the divelement that contains the text value of your memo field, you must turn to jQuery and use the following code:

var memo_text = $(form_lines_id).contents().find('#Composition').html();

Since the Progress Note field is a system column that has existed for a long time, it has the same form_lines_id in everyone’s system, so to get the memo text of a Progress Note memo field, plug in the form_lines_id:

var memo_text = $('#BFE6BE66-7983-4C3B-8374-1606E7D909A5').contents().find('#Composition').html()

Explanation of Code

var memo_text =
This creates a variable called “memo_text” that will hold the value of the memo field we target.

$('#BFE6BE66-7983-4C3B-8374-1606E7D909A5')
This targets the element on the form that has and id of ‘BFE6BE66-7983-4C3B-8374-1606E7D909A5’, which is the progress note’s iframe. If you want to target a different memo field, you will need to determine the form_lines_id of that field and plug it in here.

.contents()
This gets all of the contents of the iframe targeted above.

.find('#Composition')
This searches the contents above for an element with an id of “Composition”. This is the element that contains the Memo field’s text.

.html()
This gets the html value contained inside the “Composition” div targeted above. We use the html() method because this will preserve the rich text formatting that has been applied to the text in the box.

Setting the Value of the Progress Note

You can set the value of the progress note field with very little changes to the above code. if I want to set the text inside the progress note to “Hello”, I use this code:

$('#BFE6BE66-7983-4C3B-8374-1606E7D909A5').contents().find('#Composition').html('Hello');

Since we are using the html() method, you can insert HTML markup with your text, which is what will allow you to insert a nice template. Remember that you have to escape your >’s and <‘s

Replicating the Default Behavior

Using the code above, we are able to manipulate the text inside the Memo field with On Change and On Click events on the loaded form just fine, but what can we do if we want to default a specific value into the progress note field when the form loads?

We can use the code above to set the value but we need that code to fire AFTER the form has been loaded. Fortunately, there is an attribute on the form called After Load Code that we can use as the trigger for this code.

after-load-form-attribute

But, it’s not as simple as just dropping the code in there because while the code in this field will fire after the form loads, it does not necessarily fire after the memo field iframes are loaded. it is therefore necessary to wrap the code in a javascript setTimeout() function.

setTimeout(function(){$('#BFE6BE66-7983-4C3B-8374-1606E7D909A5').contents().find('#Composition').html('Hello');}, 5000);

The setTimeout() function takes two arguments. The first is the code that you want to execute. In the example above, I wrapped the code into an anonymous function. The second is the number of milliseconds it should wait before executing the code. In my example, I set the timer for 5000 milliseconds or 5 seconds. You can tweak this number as desired to achieve what you want it to do. With this code in place in the After Load Code attribute of the form, 5 seconds after the form loads, ‘Hello’ fills in on the progress note field.

Using A Text Template

You can use a text template in myEvolv to make this all a little easier, especially when it comes to formatting your progress note text. Create your default text in the text templates area of myEvolv.

Then within the setTimeout function, before the line of code that sets the progress note html, add the following line of code:

var myTextTemplate = getDataValue('text_template', 'description', '<text template description>', 'template_text');
where <text template description> is the description you have given your text template (beware of special characters). This line of code will grab your text template, then you can just use the variable you just created in the html() method.

Here’s what the final code would look like if you wanted to use your Incident Narrative text template.

setTimeout(function(){
var myTextTemplate = getDataValue('text_template', 'description', 'Incident Narrative', 'template_text');
$('#BFE6BE66-7983-4C3B-8374-1606E7D909A5').contents().find('#Composition').html(myTextTemplate);
}, 5000);

How To: Prevent Backdated Entries

This may not be the only or even best way of preventing backdated entries in myEvolv but this method worked for me in a recent configuration.

Scenario

We wanted our prescribers to be able to provide a Script for Therapy Services to children in our preschool services program from myEvolv. Scripts for Service must have a start date on them and that start date needs to be no earlier than the date indicated on the child’s IEP but cannot but previous to the date that the script is being signed.

Further, an administrative assistant was going to be setting up the scripts in myEvolv and then the prescribers were going to be reviewing and e-signing them. We could imagine a scenario where the administrative assistant put a date, for example (9/1) on the script, believing that the prescriber would e-sign it on or before that date but the prescriber does not get into myEvolv to sign it until after that date has passed and then the script gets e-signed as though it were backdated. We needed a way to prevent the start date from ever being previous to the approved date while also allowing the start date to be in the future.

Form Design

script-for-service-form

The actual_date field was not suitable for use as the script start date since we needed to be able have multiple scripts that start on the same day for an individual. If I set the actual date as ‘Date Only’ Display Type Code, then two scripts in the same day would overlap at 00:00 AM. In this case I ended up creating a new database field for my Start Date and kept actual date on the form, receiving todaysDate() as the default value. This more or less prevents the service overlap problem. My new database field is named udf_rx_4_svc_start and is Date Only.

The end date on the script is using the expiration_date column and is also using the Display Type Code “Date Only”.

Before Save Code

The first task to accomplish is to prevent a user from saving the form with a backdate on it. For this I used the Before Save code property on the form. This code executes every time that the form is saved BUT because of the algorithm myEvolv uses to save form data, the udf_rx_4_svc_start column in the database will only be updated if the form field has been flagged as being modified. This is something that I was not able to figure out how to do in the Before Save code yet and is largely responsible for what feels like a more-complex-than-is-strictly-necessary-solution — more on that later.

First step is to get the value that is on the form field and turn it into a JavaScript date object.
var start = new Date(getFormElement('udf_rx_4_svc_start'));

Second step is to get today’s date and turn it into a JavaScript date object. todaysDate() is a myEvolv form function that you can use to get today’s date in a format suitable for placing in a myEvolv form field.
var today = new Date (todaysDate());

With that accomplished, we can compare the two date objects to see if the date on the form is previous to today’s date and if so, set the form field’s value to today’s date.
if(start <= today){{setFormElement('udf_rx_4_svc_start', todaysDate())}};

Note that the { and } brackets are doubled up in the conditional statement. This will prevent the “Not a Valid XSLT or XPath Function” error previously discussed here.

With this code in place, when a new Script for Service is entered or a draft Script for Service has it’s udf_rx_4_svc_start field modified, myEvolv will check to make sure that the start date is not not in the past and if it is, update the start date to today’s date. If the date is today’s date or a future date, it is left as it is.

Full Code Block

var start = new Date(getFormElement('udf_rx_4_svc_start'));
var today = new Date (todaysDate());
if(start <= today){{setFormElement('udf_rx_4_svc_start', todaysDate())}};

On Load Script

Just the Before Save Code alone would not be enough to prevent backdating. We still have the possibility of someone simply opening the draft and e-signing the form as in our scenario where the prescriber gets into myEvolv to e-sign scripts later than intended. Even if the form is edited in some way, if the Start Date is not touched, the Before Save code will execute but the column will not be flagged as modified and myEvolv will ignore it when updating the database. My approach here was to try to update the form as it loads upon viewing or editing so that myEvolv would see the column as modified when saving. I was unable to get the toolbar containing the ‘Save’ button to recongize the change, however, I was able to still get the desired effect another way.

The first thing to keep in mind with the On Load Script is that the form DOM has not loaded yet when this code runs. You can not therefore target the form field with JavaScript, update its value and focus/blur to make myEvolv notice a change to the value as we can with the On Click and On Change Scripts. Instead, you have to manipulate the Record XML Data before it gets loaded into the form.

The first step here is to determine whether the script had been signed. If it has been signed, it will have a non-null date_locked value. We check for this by using the myEvolv form function getDataValue() and then seeing if the form is being opened for viewing or editing.

var locked = getDataValue('event_log', 'event_log_id', keyValue, 'date_locked');
if(locked == '' && formXML.documentElement.getAttribute('formAction') == 'EDIT'){{
...
}}

This code gets the value of date_locked from the event_log table where the event_log_id is equal to keyValue which is a variable equal to the event log id of the current event you are looking at.

Then the code checks to see if there is a locked_date. If the locked date is blank AND the form is opened for editing, then it will execute the rest of the code. So basically, only perform a date manipulation if we are still working with a draft. If you leave this piece out then every time you look at a completed script for service in the future, myEvolv will overwrite the form field value for start date to be today’s date and you will be scratching your head.

Inside the ellipses we start the date manipulation. First we load the node for udf_rx_4_svc_start from the XML Record so that we can manipulate it.
node = formXML.documentElement.selectNodes("form_group/form_item [@column_name = 'udf_rx_4_svc_start']");
node = node[0];
This code returns an Array of all of the nodes in the XML documents with the column_name “udf_rx_svc_start”. There is only one but it is in an array so we load it into our variable directly on the next line.

Then we get the start date value and turn it into a JavaScript date object.
var start = new Date(node.text);

Then we do the same for today’s date.
var today = new Date(todaysDate());

Now we check to see if start date is before today’s date and if so, we will update the text of the node to be today’s date.

if(start < today){{
node.text = todaysDate();
node.setAttribute('modified', 'true');
...
}}

I also set the “modified” attribute to ‘true’ for this node. I don’t know if that makes a difference in this setup but I am including it since that is how my code is and it works.

If you leave the code as it is like this, when the form loads, if the start date is previous to today’s date, the value on the form will have been updated to today’s date AND the form field will be maroon like it is when a form field is changed. However, you will also notice that the “Save” button is nevertheless disabled and a user would be able to e-sign the service without being forced to hit save. And apparently, even though a “saving…” dialog pops up upon e-signing, the form is not saved. I tried a bunch of things to try to get the save button to enable and the e-sign button to disable but it is difficult since the form DOM is not loaded at the time that the On Load script runs. In the end, I decided to just call the save form function directly.

So where the ellipses above are, I put
SaveForm2();

The end result here is that when the form is opened for editing, if the start date is before today’s date, myEvolv will update the start date to be today’s date and then save. The users will see the form start to open and then abruptly close if the conditions are met. When they reopen it, they will find that today’s date has been updated to today’s date and they are free to e-sign.

Full Code Block

var locked = getDataValue('event_log', 'event_log_id', keyValue, 'date_locked');
if(locked == '' && formXML.documentElement.getAttribute('formAction') == 'EDIT'){{
node = formXML.documentElement.selectNodes("form_group/form_item [@column_name = 'udf_rx_4_svc_start']");
node = node[0];
var start = new Date(node.text);
var today = new Date(todaysDate());
if(start < today){{
node.text = todaysDate();
node.setAttribute('modified', 'true');
SaveForm2();
}}
}}

Bonus: After Save Code

Since the form is going to be auto-saving itself, I also added a snippet of code to the After Save Code that keeps the form from closing after save:
window.closeAfterSave = false;

Tips & Tricks: Remove Unwanted Service Related Encounter Information from Services

I was recently working on configuring an event in myEvolv that required making a custom form in the People Placement and Treatment History form family.  Once I got the form looking right, I set about configuring the event.  I needed this event to be a service so that I could take advantage of the electronic signature functionality so I checked the “Is Service Event” checkbox for the event.

event-config

 

When I added a new service entry to test after saving this configuration, there was now Service Related Encounter Information appended to my form.

service-encounter-info

 

This was a problem since many of these fields were not applicable to the event that I was setting up and I did not want the clinicians to mess with them if they did not need them.  I looked back at the form designer to find out if I could hide them like other fields but they did not show up in the form designer.

form-designer-before

 

Fortunately, there is a way to get around this.  myEvolv automatically adds the Service Related Encounter Fields to your form if the event is a service.  myEvolv also does not allow a form to have the same field on it twice.  Therefore, if you add the fields to your form in form designer, you gain control of the form field properties and myEvolv will not append them to your form again.

As the automatically appended fields indicate, Program Providing Service and Facility Providing Service are required on service events in myEvolv so you do not want to hide these or make them not modifiable or not required. You can still move them around to make your form flow better. The other fields are able to be hidden.

 

Here is a list of the Service Related Encounter Information field column names so that you can add them to your form:

Form Label Event Log Field Column Name
Exempt from Billing do_not_bill
Activity Type activity_type_id
Client Involved is_client_involved
Program Providing Service program_providing_service
Facility Providing Service site_providing_service
Encounter With encounter_with_id
Service Authorization service_authorization_details_id

 

I added those that I wasn’t planning to display to their own Form Group and hid them.  I left the Program Providing Service and Facility Providing Service as they were in order to allow myEvolv to append those to my form automatically.

form-designer-after

 

When I saved the new form design and opened the event, the Service Related Encounter Fields I did not want to use were gone.

service-encounter-info-after

We are using cookies on our website

Please confirm, if you accept our tracking cookies. You can also decline the tracking, so you can continue to visit our website without any data sent to third party services.