SugarCRM: relate field passing default values to pop-up select form

Note: This article needs some pictures, which I will do in good time.

These are notes on how to set up a pop-up select form on a relate field in SugarCRM 6.5 to default to a value from the parent form.

So for example, you have a module Job Applications, and each application is made by a Contact. The contact has a number of CVs uploaded in the CV module. In the application, a relate field allows one of the CVs to be selected as relevant to the application. That relate field will pop up a search form for CVs, and by default will list all CVs on the system. What I would like it to do, is to limit the CVs to just those connected with the Contact who is connected with the Job Application being entered.

In the Job Application edit form we have a Contact selection field (this is a relationship – each Job Application has one Contact). A similar relationship exists for CVs – each CV has one Contact, an each Contact can have many CVs. We don’t have a full relationship between the CVs and the Job Applications – a simple relate field is good enough for our purposes.

So, you edit a Job Application for a Contact, click on the “selected CV” button on the form, and then will get a popup form giving you a list of CVs for that Contact, to choose from.

Now, a few notes on how far we want to go with this. Firstly, we just want this to be quick and efficient for the users. We are not trying to limit the CVs only to those of the job applicant. Yes, that would be nice, but is another level of customisation for another day. It is also worth noting that I am dealing with custom modules under development here, so I am editing the core files of those modules. Applying this solution to any of the standard modules would involve putting the changes into the custom/Extensions area of the CRM.

The Approach

When a pop-up search form is used in SugarCRM, it can be be passed initial values to go into the form fields. These are passed as GET parameters of the form {field-name}_advanced. The field name could be something simple like contact_name, assuming it is a simple field. It could be a more complex name if it is part of a relationship, as it is in this case (the Contact for a CV is in the relationship between the CV and the Contacts modules – the Contact is not stored in the CV module main tables at all).

Whatever the field name is, you will need it. Take a look at the source of the pop-up search form and the field name will be in there. Put “_advanced” onto the end of the name, and that will be the GET parameter that needs to be passed into the pop-up form when it is invoked.

So, where does the value for this parameter come from, and how do we get it into the pop-up form URL?

This is all done in the edit form metadata for the relate field. In my Job Application module, this metadata is defined in:

modules/ACAD_JobApplications/metadata/editviewdefs.php

If you have edited the module using Studio or are dealing with a standard module, then you will need to locate the appropriate upgrade-safe metadata file. Here is my definition for the related field:

array (
0 =>
array (
'name' => 'selected_cv',
'studio' => 'visible',
'label' => 'LBL_SELECTED_CV',
),
},

What we can do is add some new display parameters to this field. The parameter we add is called “initial_filter”, and SugarCRM will add the value of that to the URL when the pop-up search form is invoked. This is what it looks like in its basic form:

array (
0 =>
array (
'name' => 'selected_cv',
'studio' => 'visible',
'label' => 'LBL_SELECTED_CV',
'displayParams' => array(
'initial_filter' => '&my_field_advanced=some_default_value',
),
),
},

Adding that will pass “some_default_value” into a field called “my_field” on the pop-up search form. In the main edit page, that intial_filter string will be quoted (“) then passed to the pop-up form function as a parameter. It is possible to insert JavaScript into that string by closing the quotes, and that is a technique we will take advantage of.

First it is worth looking at where some_default_value is going to come from. In the main edit form we have a field that has the data in that we want to pass on to the pop-up search form. There are two ways to get at this data:

1. At the time the edit page is generated.
2. At the time the “select CV” button is pressed.

In the first instance, the value will be the value that comes out of the database. So in this case it will be the contact name when you first edit the job application. If this is a new job application, then there will be no contact name, and so the pop-up will not start with an specific contact by default. Even if you then select a contact in the main edit form, until you save the record, the pop-up search form will not know about that contact.

To get at the contact name (or the value of any other field) in the form, we take advantage of Smarty syntax. The string passed to initial_filter is treated as a Smarty template, and so you use Smarty code within it. To set my_field in the pop-up to the value of the field contact_name, you would use this:

'initial_filter' => '&my_field_advanced={$fields.contact_name.value}',

However, we do need to be a little cleverer than that. Since that contact name will passed as the value of a GET parameter, we need to ensure it is URL-safe, so special URL characters are appropriately escaped. This is done in Smarty like this:

'initial_filter' => '&my_field_advanced={$fields.contact_name.value|escape:'url'}',

Alternatively (or perhaps more correctly):

'initial_filter' => '&my_field_advanced={$fields.contact_name.value|urlencode}',

There is more escaping to be done. Because this string will appear on the edit form page as a JavaScript string that is quoted with “double-quotes”, we must make sure it is escaped for JavaScript too:

'initial_filter' => '&my_field_advanced={$fields.contact_name.value|escape:'url|escape:'jacascript'}',

Now, there is a problem here – or perhaps it’s not. The value of $fields.contact_name.value is automatically HTML encoded. That means quotes are converted to " entities and some other special characters are converted to entities too. Since this string is appearing in JavaScript and going out to a URL, we really don’t want it to be HTML encoded. However, the pop-up search form seems to cope with that HTML encoded data; I suspect it does a html_decode() on its parameters “just in case”. Personally I would prefer not to have encoding or escaping that is not appropriate, and there may be a way to tell this mini-Smarty template not to do that encoding, but I don’t know how that would would work.

The other approach to obtaining the field data to pass to the pop-up form, is to pick it off the current page using JavaScript right at the last moment. One advantage of this, is that the contact name can be set or changed in the Job Application edit form, and the pop-up CV search form will see that name every time.

Adding JavaScript to extract a field value from the current edit form is done like this:

'initial_filter' => '&my_field_advanced="+document.getElementById("contact_name").value+"',

Note we break out of the quoted string with a “, then append the JavaScript, then drop back into the quoted string with a final ” at the end.

We also need to think about URL escaping here:

'initial_filter' => '&my_field_advanced="+encodeURIComponent(document.getElementById("contact_name").value)+"',

However, JavaScript escaping is not needed, as we are not creating any quoted JavaScript strings in the page containing data; the JavaSscript that is generated only contains instructions.

So that’s it. We went for the second method as it was more flexible and made sense when new Job Applications were created from the start. Taking all the above, the full field that appears in our edit form metadata is:

array (
0 =>
array (
'name' => 'selected_cv',
'studio' => 'visible',
'label' => 'LBL_SELECTED_CV',
'displayParams' => array(
'initial_filter' => '&contact_name_advanced="+encodeURIComponent(document.getElementById("contact_name").value)+"',
),
),
},

So the CV search pop-up form now has the job applicant contact name in it by default. You still need to hit the search button to bring back the list of CVs for that contact, but at least you don’t need to be copying and pasting or typing up names between forms.

Special thanks to Marian Dobre for the final pieces to the puzzle in solving this little problem.