Loading...

CRM Lookup

Properties API

Widget Type:
Form Widgets
TPC Version:
  • 3.3 +
lookuplogo
The CRM Lookup widget is a dropdown list that has the added functionality of allowing users to look for the desired input by typing in their selection. In addition, the user may also browse the list just like they would browse a drop down list. Please note that you cannot preview the CRM Lookup widget in the form designer. 

Configuration

Basic

  1. From the Portal Connector widget list, click and drag the CRM Lookup widget into the body of your form.
  2. In order for the CRM Lookup widget to properly work, a variety of options must be configured. Click on the edit button to display the prompt page. It should look like this:

      CRM Lookup Properties
Basic

Account Data

 

  1. Depending on the CRM Field chosen, there will be a number of Data tabs. For example, in the picture above, the CRM Field of Company Name can be used to look up both Accounts and Contacts. This means that if you would only like to look up Contacts, you only need to configure the Contact Data tab.

  2. Next, navigate to the Data tab that you would like the widget to be able to look up, it should look like this: 

    Look up Properties Data Tab

Filters

  1. When you are finished configuring the Data tab, click on the Filters tab. The Filters tab is used to include or exclude data. It should look like this: 

    Look up Filters Tab

  2. When you are finished configuring the widget, click on the save button to save it.

Regarding the Regarding Data Tab

The regarding data field and tab is an addition to the CRM Lookup widget that will allow you to attach records to other CRM Entities. The regarding data field itself is reserved for Activities. For example, the Email entity contains the regarding field which allows you to attach email logs to a chosen CRM Entity. The Regarding tab should look like this:

CRM Look up Regarding Properties

As pictured above, you can choose any CRM Entity for the CRM Lookup field to attach a successful submission to with the ability to diversify your choices via FetchXML.

Widget Properties

Basic Properties

Select a Template - Lookup

The Select a Template drop down list will allow you to select a template for your product to use with the option of creating a new template. If a template is selected, you will be given the additional option of editing the selected template.

FetchXML

The FetchXML text area determines what sort of data a widget will be populated with. Clicking the Load Default Fetch option will populate the FetchXML area with a default fetch based on the CRM Entity chosen.  By clicking the Build button, we will be sent to another page in order to determine what the widget will look up. For more information on how to use the FetchXML function, please see the FetchXML Builder How-To.

Value Field

The Value Field text box will determine what actual value is passed when an option is selected. It is different from the Display Field in that the Display Field will be the actual, selectable options.

Display Field

The Display Field text box will determine what selectable options are present in a widget. However, it is different from the Value Field text box in that the Value Field passes the actual value to be submitted which may not necessarily be the visible option.

Title

The Title text box will allow you to set the label of your widget. The title will usually appear above the associated widget.

Read Only

The Read Only checkbox will not allow the user to interact with the widget when checked.

Make Required

The Make Required checkbox will not allow a user to successfully submit the form until there is data within it. Upon selecting the checkbox you will be prompted to enter an error message for invalid input.

CRM Field

The CRM Field drop down list allows you to change what options will appear in a particular widget. For example, in a CRM Picklist, a CRM Field of Marital Status would contain the options: Single, married, divorced, and widowed. The CRM Fields available are dependant upon which CRM Entity has been chosen. Please note that some selections have a grey backdrop. This means that the CRM Field is a read-only field. Upon selection, the Read-Only checkbox will be automatically selected.

Expose Row Object Data

The Expose Row Object Data advanced property will allow you to use the get_selectedRowData method on a chosen record in a CRM Lookup, which will give you both the display and value of the selected record. More information can be found here.

Enable Accessibility Mode

The Enable Accessibility Mode advanced property will allow the widget to still function if the user's browser has JavaScript disabled. By default this is set to false.

Show Customer Type

The Show Customer Type advanced property will show the type of entity that a user belongs to when a customer field is selected. By default this is set to true.

Always Query

The Always Query advanced property allows you to choose whether the CRM Lookup widget will use a display value derived from the FetchXML. This advanced property is only used when the widget is set to be read-only. By default it is set to false.

Drop Down Height

The Drop Down Height advanced control allows you to set the maximum height in pixels of a drop down list. If the drop down list contains more items than the maximum height can accommodate, a scrollbar is added. By default, this value is 280.

Custom Edit Record Query String

The Custom Edit Record Query String advanced property allows you to set the parameter name of the query string associated with the chosen record. This allows you to work with multiple records of the same entity in the same form.

AddButtonText

The AddButtonText advanced property allows you to set the text that will appear inside of the add button. By default this is 'Add'.

EditButtonText

The EditButtonText advanced property allows you to set what text will appear in the edit button. By default this is 'Edit'.

Window Modal

The Window Modal advanced property allows you to choose if the main browser window will be disabled when another window is displayed. By default, this is set to 'true'.

Window Modal Centered

The Window Modal Centered advanced property will allow you to choose if any additional windows will be automatically centered when they appear. By default this is set to 'true'.

Window Title Visible

The Window Title Visible advanced property will determine if a pop-up window will have a visible title. By default this is set to 'true'.

Window Statusbar Visible

The Window Statusbar Visible advanced property wil allow you to choose if any pop-up windows will have a visible statusbar. By default, this is set to 'false'.

Window Auto Size

The Window Auto Size advanced property will automatically resize any pop-up windows based upon its content. By default, this is set to 'true'. Please note that this advanced property will override the set Window Height and Window Width values.

WindowWidth

The WindowWidth advanced property allows you to define a default height for any pop-up windows to use. By default this is set to 1024 pixels. Please note that if the Window Auto Size advanced property is set to true, this property will not apply.

WindowHeight

The WindowHeight advanced property allows you to define a default height for a pop-up window to adhere to. By default this is set to 640 pixels. Please note that if the Window Auto Size advanced property is set to true, this property will not apply.

Window Minimum Width

The Window Minimum Width advanced property will allow you to set the minimum width at which a window will display. This means that you cannot adjust the window to be narrower than the minimum width.

Window Minimum Height

The Window Minimum Height advanced property will allow you to set the minimum height at which the window will display. This means that you cannot adjust the window to be shorter than the set minimum height.

Window Maximum Width

The Window Maximum Width advanced property will allow you to set the maximum height at which the window will display. This means that you cannot adjust the window to be wider than the set maximum width.

Window Maximum Height

The Window Maximum Height advanced property will allow you to set the height at which the window will display. This means that you cannot adjust the window to be taller than the set maximum height.

UseUnencryptedGuids

The UseUnencryptedGuids advanced property will decrypt any query string values that are passed through the URL. If a widget has been set to pass a query-string to another widget, the Use Unencrypted Guids properties must match each other or the widgets will be unable to communicate with each other.

Querystring ID for Passed Value

The Querystring ID for Passed Value advanced property will set the name of the parameter for a querystring. If the Pass Value to Querystring property is set to true, then this property must be set as well.

Pass Value to Querystring

The Pass Value to Querystring advanced property will allow you to set the widget to pass its value through a querystring. If this property is set to true, the Querystring ID for Passed Value property must also be set. In addition, if this option is selected, both the sending widget and retrieving widget must have their UseUnencryptedGuids properties set to the same state as one another or else the widgets will not communicate with each another.

Advanced Properties

Advanced properties provide additional functionality. They can be accessed by clicking on the "Advanced" Button in the bottom right corner of the widget designer.

Select a Template - Lookup

The Select a Template drop down list will allow you to select a template for your product to use with the option of creating a new template. If a template is selected, you will be given the additional option of editing the selected template.

FetchXML

The FetchXML text area determines what sort of data a widget will be populated with. Clicking the Load Default Fetch option will populate the FetchXML area with a default fetch based on the CRM Entity chosen.  By clicking the Build button, we will be sent to another page in order to determine what the widget will look up. For more information on how to use the FetchXML function, please see the FetchXML Builder How-To.

Value Field

The Value Field text box will determine what actual value is passed when an option is selected. It is different from the Display Field in that the Display Field will be the actual, selectable options.

Display Field

The Display Field text box will determine what selectable options are present in a widget. However, it is different from the Value Field text box in that the Value Field passes the actual value to be submitted which may not necessarily be the visible option.

Title

The Title text box will allow you to set the label of your widget. The title will usually appear above the associated widget.

Read Only

The Read Only checkbox will not allow the user to interact with the widget when checked.

Make Required

The Make Required checkbox will not allow a user to successfully submit the form until there is data within it. Upon selecting the checkbox you will be prompted to enter an error message for invalid input.

CRM Field

The CRM Field drop down list allows you to change what options will appear in a particular widget. For example, in a CRM Picklist, a CRM Field of Marital Status would contain the options: Single, married, divorced, and widowed. The CRM Fields available are dependant upon which CRM Entity has been chosen. Please note that some selections have a grey backdrop. This means that the CRM Field is a read-only field. Upon selection, the Read-Only checkbox will be automatically selected.

Expose Row Object Data

The Expose Row Object Data advanced property will allow you to use the get_selectedRowData method on a chosen record in a CRM Lookup, which will give you both the display and value of the selected record. More information can be found here.

Enable Accessibility Mode

The Enable Accessibility Mode advanced property will allow the widget to still function if the user's browser has JavaScript disabled. By default this is set to false.

Show Customer Type

The Show Customer Type advanced property will show the type of entity that a user belongs to when a customer field is selected. By default this is set to true.

Always Query

The Always Query advanced property allows you to choose whether the CRM Lookup widget will use a display value derived from the FetchXML. This advanced property is only used when the widget is set to be read-only. By default it is set to false.

Drop Down Height

The Drop Down Height advanced control allows you to set the maximum height in pixels of a drop down list. If the drop down list contains more items than the maximum height can accommodate, a scrollbar is added. By default, this value is 280.

Custom Edit Record Query String

The Custom Edit Record Query String advanced property allows you to set the parameter name of the query string associated with the chosen record. This allows you to work with multiple records of the same entity in the same form.

AddButtonText

The AddButtonText advanced property allows you to set the text that will appear inside of the add button. By default this is 'Add'.

EditButtonText

The EditButtonText advanced property allows you to set what text will appear in the edit button. By default this is 'Edit'.

Window Modal

The Window Modal advanced property allows you to choose if the main browser window will be disabled when another window is displayed. By default, this is set to 'true'.

Window Modal Centered

The Window Modal Centered advanced property will allow you to choose if any additional windows will be automatically centered when they appear. By default this is set to 'true'.

Window Title Visible

The Window Title Visible advanced property will determine if a pop-up window will have a visible title. By default this is set to 'true'.

Window Statusbar Visible

The Window Statusbar Visible advanced property wil allow you to choose if any pop-up windows will have a visible statusbar. By default, this is set to 'false'.

Window Auto Size

The Window Auto Size advanced property will automatically resize any pop-up windows based upon its content. By default, this is set to 'true'. Please note that this advanced property will override the set Window Height and Window Width values.

WindowWidth

The WindowWidth advanced property allows you to define a default height for any pop-up windows to use. By default this is set to 1024 pixels. Please note that if the Window Auto Size advanced property is set to true, this property will not apply.

WindowHeight

The WindowHeight advanced property allows you to define a default height for a pop-up window to adhere to. By default this is set to 640 pixels. Please note that if the Window Auto Size advanced property is set to true, this property will not apply.

Window Minimum Width

The Window Minimum Width advanced property will allow you to set the minimum width at which a window will display. This means that you cannot adjust the window to be narrower than the minimum width.

Window Minimum Height

The Window Minimum Height advanced property will allow you to set the minimum height at which the window will display. This means that you cannot adjust the window to be shorter than the set minimum height.

Window Maximum Width

The Window Maximum Width advanced property will allow you to set the maximum height at which the window will display. This means that you cannot adjust the window to be wider than the set maximum width.

Window Maximum Height

The Window Maximum Height advanced property will allow you to set the height at which the window will display. This means that you cannot adjust the window to be taller than the set maximum height.

UseUnencryptedGuids

The UseUnencryptedGuids advanced property will decrypt any query string values that are passed through the URL. If a widget has been set to pass a query-string to another widget, the Use Unencrypted Guids properties must match each other or the widgets will be unable to communicate with each other.

Querystring ID for Passed Value

The Querystring ID for Passed Value advanced property will set the name of the parameter for a querystring. If the Pass Value to Querystring property is set to true, then this property must be set as well.

Pass Value to Querystring

The Pass Value to Querystring advanced property will allow you to set the widget to pass its value through a querystring. If this property is set to true, the Querystring ID for Passed Value property must also be set. In addition, if this option is selected, both the sending widget and retrieving widget must have their UseUnencryptedGuids properties set to the same state as one another or else the widgets will not communicate with each another.

API

get_isReadOnly()

Returns true if the widget is in read only mode. 

Returns

Boolean

get_customEditRecordQueryString()

Returns the parameter name of the Custom Edit Record Querystring. 

Returns

String

get_confirmYes()

Returns the text for the yes button when creating a customer record. 

Returns

String

get_confirmNo()

Returns the text for the no button when creating a customer record.

Returns

String

get_lblReadOnly()

Returns the label if the widget is in read only mode. 

Returns

String

get_btnAddNew()

Returns the 'Add' RadButton object.

Returns

RadButton 

get_btnEdit()

Returns the 'Edit' RadButton object. 

Returns

RadButton

Returns the RadWindow object. 

Returns

RadWindow 

get_lookupPanel()

Returns the RadAjaxPanel object.

Returns

RadAjaxPanel 

get_value()

Returns the value (GUID) of the selected record. 

Returns

Value

set_value()

Sets the value (GUID) of the selected record. 

Returns

none

Sets the display text of the selected record. 

Returns

Value

clearSelection()

Deselects the current, chosen option of the widget. 

Returns

none

enable()

Enables the widget. 

Returns

none

disable()

Disables the widget. 

Returns

none

get_selectedRowData()

Returns the display and value of a chosen record in the lookup as an object. The advanced property ExposeRowData must be set to true prior to using this method.

Returns

Object

Full API With Examples

How to's

Examples of CRM Lookup Configuration