RECOMMENDATION: If you are using a version of The Portal Connector higher than 4.0, we strongly recommend utilizing the MVC based widgets and components to create your site. This documentation is for legacy purposes only and will soon be deprecated.
Widget Type:
Form Widgets
TPC Version:
  • 4.0
textfieldlogo
The CRM Text Field widget is a text field for your users to enter information. This widget has additional functionality in the form of appearance options which allows you to design the text field to fit the intended input and masked properties which allows you to direct the expected user input. Please note that if a read-only data field is selected, the Maximum Length numeric text field will be set to read-only.

Here are some examples of the available variations of the textfield widget:

TextfieldExample

Configuration

Basic

Make sure you have a CRM Form Configuration and a TPC Form Layout already attached and configured. This would reveal the Attributes available to the Entity Selected in the Form Configuration. 

Drag and drop the CRM Text Field widget from The Portal Connector tools into the TPC Form Layout and click edit to display the properties prompt.

The Title will allow you to set the label for the control. By default it is set to the whichever attribute you choose but it can be freely modified.

The Attribute dropdown list allows you to select an attribute for the widget to submit data to.
 
The Read Only option will not allow the user to interact with the widget when checked. 

The Hidden option will hide the widget from the form when checked.

The Required option will not allow the user to submit the form until they have populated the widget with data.
text-box-instructions-1

Appearance 

After configuring the basic widget settings, click on the Appearance tab. This section allows you to determine how a text field should appear.

The Empty Place Holder text field allows you to set some transparent text that will appear in the text field when it is empty.

The Input Mode dropdown list allows you to set the text field's appearance. Some of these selections have additional properties associated with them.
Available options are: 

  •  Text for a normal single-line text field, 
  •  Multiline for a text field with multiple lines, 
  • Password which is a text field wherein the input is masked with asterisks, 
  • HTML which is a multi-line text field with the option of adding a toolbar, enabling a user greater control over their input similar to a word processor.

text-box-instructions-2

Validation

The Validation section will only appear when a non-numeric field is selected. If a numeric field is selected, this section is replaced with the Numeric Properties tab. 

The Validation tab enables you add a mask or a regular expression to the field. You can only use  one of these options Regex or Mask (selecting one will disable the other).

Regex Options:

  • Url: Validates full website address. 
  • Phone: Validates North American phone numbers. Area code required. Extension and long distance codes are optional. 
  • Password which is a text field wherein the input is masked with asterisks. 
  • Custom: Enables the administrator to enter custom validation.


text-box-instructions-3

Numeric Properties 

The Numeric Properties tab enables you to control how numeric text fields work, as well as how the numbers from these fields will be displayed. This tab appears when a numeric attribute is selected.

Minimum and Maximum value defines the minimum and maximum allowable numbers for the textfield.

Numeric Precision controls the number of decimal places displayed.


text-box-instructions-4

Widget Properties

Basic Properties

Title

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

Attribute

The Attribute drop down list will allow you to change the data field that this widget will save the user’s input to (For example, a CRM Text Field with an Attribute of Account Name will save its input to the Account Name data field).

Read Only

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

Hidden

The Hidden checkbox will hide the widget from the page when checked.

Required Field

The Required Field 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.

ClientSideRequired

Allows you to enable or disable "required" from client side  

Empty Placeholder

The Empty Placeholder textfield will ‘fill’ the text box with whatever you enter here. This can be used to help guide user input or to give an example of proper input.

Tool Tip

The Tool Tip allows you to add a description or Hint to your widget.

Input Mode

The Input Mode dropdown list allows you to specify an appearance for a widget. Applicable options are dependent on the widget. For example, the Picklist widget includes: Radio button group and dropdown list. The Yes/No widget includes: Radio button group, dropdown list, checkbox, and mobile switch. The textfield widget includes: Text (single line), multiline, HTML, numeric, and currency.

Each view would contain the Input Labels associated with the values inside CRM in the case of the Picklist and Yes/No widgets..

This option is overridden if Read Only is selected.

Regex Validation

The Regex Validation property allows you to specify a regular expression for validating user input with the option of specifying a custom regular expression. Applicable options include: URL, Phone, and Custom.

When a regex validation option is chosen, you will be provided with a textfield to specify an error message.

Mask Validation

The Mask Validation drop down list will give you an assortment of common data types to choose from which serves to guide user input. For example, if you have a form that requires the user to enter their postal code, the Mask Type for the text box associated with the postal code should be of the postal code type. This will ensure that the textbox will only allow valid postal codes to be entered. The Mask Type drop down list also allows you to create your own custom masks; though this option is reserved for advanced users.

MailToText

Allows you the add a text to your "mailto" when it IsMailto property is enabled. 

IsMailto

Allows you to enable  "mailto" within a  hyperlink to generate a link for sending email.

IsHyperlink

Allows you to make the value as a Hyper Link 

Hide Title

You can hide the title by setting the property value to true

EscapeCrmData

Converts a data string into an HTML-encoded string.

ConvertNewLines

convert \r\n carters to <br>

Show Editor Toolbar

The Show Editor Toolbar checkbox will show the toolbar for use when set to true. By default, it is false. Please note that hot-keys will work regardless if the toolbar is shown or not. For example, Ctrl+B will still make text bold.

Minimum Value

The Minimum Value property will set the minimum number allowed in a numeric textfield.

Maximum Value

The Maximum Value property will define the maximum value that will be accepted in a numeric textfield.

Numeric Precision

The Numeric Precision property allows you to specify how many digits will appear to the right of a decimal point.

Show Spin Buttons

The Show Spin Buttons checkbox option will add the arrow keys onto the side of a numeric Text Field. This will enable users to increment or decrement these fields by clicking on the arrows.

PromptChar

The PromptChar is the character that is used to specify user input in a Mask Type. By default, the Prompt Char is '_'. For example, a mask type of telephone would appear as _-(___)-___-____ by default. If you were to switch the '_' with '#', this would become #-(###)-###-####.

LabelPosition

The LabelPosition advanced property specifies where the label of a widget will appear. By default, the label will appear on top of the widget. Applicable options include: Top and left. The content of the label is controlled by the Title property. The default value for this is 'Top'.

ToolTipPosition

This property determines the position of the tool tip. By default this property is set to "Auto". You can change this to Left , Right , Top , Bottom. 

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.

Title

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

Attribute

The Attribute drop down list will allow you to change the data field that this widget will save the user’s input to (For example, a CRM Text Field with an Attribute of Account Name will save its input to the Account Name data field).

Read Only

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

Hidden

The Hidden checkbox will hide the widget from the page when checked.

Required Field

The Required Field 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.

ClientSideRequired

Allows you to enable or disable "required" from client side  

Empty Placeholder

The Empty Placeholder textfield will ‘fill’ the text box with whatever you enter here. This can be used to help guide user input or to give an example of proper input.

Tool Tip

The Tool Tip allows you to add a description or Hint to your widget.

Input Mode

The Input Mode dropdown list allows you to specify an appearance for a widget. Applicable options are dependent on the widget. For example, the Picklist widget includes: Radio button group and dropdown list. The Yes/No widget includes: Radio button group, dropdown list, checkbox, and mobile switch. The textfield widget includes: Text (single line), multiline, HTML, numeric, and currency.

Each view would contain the Input Labels associated with the values inside CRM in the case of the Picklist and Yes/No widgets..

This option is overridden if Read Only is selected.

Regex Validation

The Regex Validation property allows you to specify a regular expression for validating user input with the option of specifying a custom regular expression. Applicable options include: URL, Phone, and Custom.

When a regex validation option is chosen, you will be provided with a textfield to specify an error message.

Mask Validation

The Mask Validation drop down list will give you an assortment of common data types to choose from which serves to guide user input. For example, if you have a form that requires the user to enter their postal code, the Mask Type for the text box associated with the postal code should be of the postal code type. This will ensure that the textbox will only allow valid postal codes to be entered. The Mask Type drop down list also allows you to create your own custom masks; though this option is reserved for advanced users.

MailToText

Allows you the add a text to your "mailto" when it IsMailto property is enabled. 

IsMailto

Allows you to enable  "mailto" within a  hyperlink to generate a link for sending email.

IsHyperlink

Allows you to make the value as a Hyper Link 

Hide Title

You can hide the title by setting the property value to true

EscapeCrmData

Converts a data string into an HTML-encoded string.

ConvertNewLines

convert \r\n carters to <br>

Show Editor Toolbar

The Show Editor Toolbar checkbox will show the toolbar for use when set to true. By default, it is false. Please note that hot-keys will work regardless if the toolbar is shown or not. For example, Ctrl+B will still make text bold.

Minimum Value

The Minimum Value property will set the minimum number allowed in a numeric textfield.

Maximum Value

The Maximum Value property will define the maximum value that will be accepted in a numeric textfield.

Numeric Precision

The Numeric Precision property allows you to specify how many digits will appear to the right of a decimal point.

Show Spin Buttons

The Show Spin Buttons checkbox option will add the arrow keys onto the side of a numeric Text Field. This will enable users to increment or decrement these fields by clicking on the arrows.

PromptChar

The PromptChar is the character that is used to specify user input in a Mask Type. By default, the Prompt Char is '_'. For example, a mask type of telephone would appear as _-(___)-___-____ by default. If you were to switch the '_' with '#', this would become #-(###)-###-####.

LabelPosition

The LabelPosition advanced property specifies where the label of a widget will appear. By default, the label will appear on top of the widget. Applicable options include: Top and left. The content of the label is controlled by the Title property. The default value for this is 'Top'.

ToolTipPosition

This property determines the position of the tool tip. By default this property is set to "Auto". You can change this to Left , Right , Top , Bottom. 

API

get_type()

Returns the widget type.

Returns

String

required()

Enables or disables client side validation.

Returns

None

clear()

Clears the value of the widget.

Returns

None

add_valueChanged()

Fired when the value of the widget is changed by the user.
The event handler function context (available via the this keyword) will be set to the widget instance.

Returns

None

get_container()

Returns the container element of the widget.     

Returns

jQuery Object     

get_element()

Returns the element of the widget.

Returns

jQuery Object

get_input()

Returns the input element of the widget.

Returns

jQuery Object

get_model()

Returns the model object of the widget, which contains a number of useful properties related to the widget.
In the case of theText Field widget, these returned properties and their types are:

  • DisplayPromptChar: Boolean
  • InputMode: Integer
  • Mask: String
  • MaxValue: Integer
  • MinValue: Integer
  • NumberOfRows: Integer
  • NumericPrecision: Integer
  • PromptChar: String
  • ReadOnly: Boolean
  • ShowEditorToolBar: Boolean
  • ShowSpinners: Boolean

Returns

Object

get_kendoInput()

Returns the Kendo Input Object associated with the widget.
In the case of the CRM Textfield, only certain input modes will use a Kendo Input Object, otherwise, it will throw an error.
These input modes are:
Numeric textfield, masked textfield, and HTML textfield.

Returns

Kendo Object:
Kendo.ui.Editor Object if set to HTML Editor
Kendo.ui.MaskedTextBox Object if Mask is set
Kendo.ui.NumericTextBox Object if Numeric attribute is used

get_value()

Returns the value of the widget.

Returns

String if text attribute.
Integer or Decimal if Numeric attribute.

set_value()

Sets the value of the widget.

Returns

None

remove_valueChanged()

Removes any delegate hooked up to the add_valueChanged() event.

Returns

None

hide()

Hides the widget from the form.

Returns

None

show()

Shows the widget on the form.

Returns

None

enable()

Enables the widget on the form.

Returns

None

toggle()

Toggles the visibility of the widget.

Returns

None

readonly()

 Sets the widget state to read only.

Returns

None

disable()

Disables the widget on the form.

Returns

None