More about the Values and FormValues collections

2 minute read time.
The Values() and FormValues() collections are serverside methods that are analogous to the ASP Request.Form() and Request.QueryString() collections. In an ASP page we can see the submitted values of the HTML form by examining the Request.Form() collection:

e.g.

[code language="javascript"]
var strPostCode = Request.Form("addr_postcode");
[/code]

or the contents of the QueryString using the Request.QueryString() collection

e.g.

[code language="javascript"]
var strSwitchName = Request.QueryString("mode");
[/code]

The ASP objects like the Request object are not available within the internal COM API of Sage CRM. To access the information passed from the Form we can use either the Values() collection or the FormValues() collection within the serverside code:
    • Create Scripts
    • Validate Scripts
    • TableLevel scripts
    • and Workflow JScript conditions

The Values() collection will allow you to access the data within the fields associated with the EntryBlock (screen) used to build the edit screen for the record. So in editing a company record you would use the CompanyBoxLong screen.

The FormValues() collection will allow you to access the data from within the whole of the HTML form submitted. This means in a screen like the new Company screen when you are actually inserting data to several tables (Company, Person, Address etc) then you can access any of the submitted data. So in an InsertRecord event function of an Company Entity script we could access the submitted address information:

[code language="javascript"]
var strPostCode = FormValues("addr_postcode");
[/code]

The Values collection allows us to do several very clever things for example we can access the QueryString information. Because of this we can even know what the ID of the record being edited is.

e.g.

[code language="javascript"]
Valid = false;
ErrorStr = Values("key1") ;
[/code]

Another useful trick is being able to access data that has been declared in fields that have been added to the custom content of the Screens (so not formally part of the Sage CRM screen strcuture and with no corresponding data field in the database). If you add the text

[code language="html"]

[/code]

to the custom content box of the CompanyBoxLong then this value can be accessed in scripts e.g.

[code language="javascript"]
var strTestValue = Values("comp_test");
[/code]

Tablelevel scripts can't access the information in the QueryString. This means if we want to know which record is being updated then we will have to use another method.

Sage CRM provides the internal system variable WhereClause that contains the restriction used to find the record being edited.

The general idea though can be seen from this snippet that could be added to a company tablelevel script UpdateRecord event function.

[code language="javascript"]
var myCompany = CRM.FindRecord("company",WhereClause);
Valid = false;
ErrorStr = myCompany.comp_companyid;
[/code]

So we know that we can use the Values() or FormValues() collections to access data passed into Sage CRM but that if we require to access data already in the system we can use the WhereClause to retrieve the data.