version

Multi-control

This field type inserts the controls specified by an sql query into the normal flow of controls on the page.

If the multi-control is in temp table mode then its data will be saved in a temp table like this:

CREATE TABLE #xxx
(
	/* The value from the Id column when the multi-control created the controls,
		or field name if the multi-control did not use the Id column, but
		using an explicit Id column is strongly recommended. */
	Id nvarchar(MAX) NOT NULL,

	/* The control's value. */
	Value nvarchar(MAX) NULL,

	/* This column only exists if the multi-control contains controls that
		return binary data, for example the File control. For those controls
		Value will be NULL and ImageValue will contain their data. */
	ImageValue varbinary(MAX) NULL,
	
	/* This column only exists when the ImageValue column is used and 
		multi-control contains a control type that returns a filename.
		For example, the File control uses file names but the Signature
		control does not. */
	ImageValueFileName nvarchar(MAX) NULL,

	/* This column only exists when the ImageValue column is used. */
	ImageValueContentType nvarchar(MAX) NULL,

	/* This column only exists for backwards compatibility. Ignore it.
		It will be present when the multi-control contains a File control. */
	ImageValueContentSize int NULL,

	/* This column only exists when the multi-control contains controls
		that return their data in a temporary table, for example the
		multirow control. */
	TableName sysname NULL
)

Start value: Value that is passed to the stored procedure specified in the SQL field as the parameter @id. It is also passed to the insert / update procedure of the newedit.aspx page.

Return value: Two modes are supported:

In the temp table mode all data from the controls is passed to a temporary table. The start value is returned to the insert / Update procedure. The name of the temporary table is also passed to the insert update procedure in a parameter called <fieldname>TableName.

In the classic mode a '¤' separated list of values is passed as a parameter.

Supported in: NewEdit

SQL

SQL Call: Control specifications (mandatory)

Return one row for each control to insert.

Optimize your code by creating field information with common properties instead of assigning all properties dynamically. Reference this field information using the FieldInfo column and use dynamic field information for customizing the remaining properties.

Using FieldInfo is also helpful when you encounter properties that can only be set on field information and can't be assigned dynamically.

May modify database: No

Parameters

@id string

Value supplied from the database record being edited or default value of the field depending on the action parameer to newedit.aspx.

Resultset: Control specifications

Return field information for the controls to insert.

Table count: repeated exactly once

Row count: zero or more rows

Columns

FieldName optional string

The name of the field if referring to it from other controls.You should avoid using special characters in the fieldname column. If you need to pass complex data to the insert/update procedure then use the id-column instead.

FieldInfo optional varchar

Name of field information to base the dynamic field on, specified as "FieldTable.FieldName". All properties not explicitly overridden by dynamic field information will be copied from this field. The referenced field must be found in the menu item's field tables.

id optional string

A custom id value identifying this control. This is passed back as the column Id if the temporary table mode is used.

Value optional string

Start value of the control. Only applicable in edit and duplicate modes. In new mode the default value is used as start value.

AllowHtml optional bit

Allow HTML.

When set to true, it uses legacy functionality and is therefore only recommended to be used to disallow HTML. To allow HTML, it is recommended to use the FieldInfo column.

ButtonJavaScript<xxx> optional string

Inserts a button next to the control that is used to execute the JavaScript supplied here. <xxx> is an arbitrary text that can be empty if only one button is required.

ButtonJavaScript<xxx>_Label optional string

The label for the JavaScript button <xxx>.

CanOrderRows optional bit

Only applicable to the Multirow control.

CellAlignment optional string

The alignment of grid columns and InfoSQL values.

Possible value	Description
center	Only applicable to grid columns.
left
right

ColumnTooltip optional string

Sets the tooltip on the column title. Only supported by the Grid component.

DefaultValue optional string

The default value for the control or if prefixed by 'SQL:' the sql to run to determine the default value.

DefaultValueSql optional string

SQL that evaluates default value for field. Can contain other fields for value dependency.

Description optional string

The description for the field.

EnabledJavaScript optional string

Javascript that controls the enabled status of the field. The control is only enabled if the expression specified here evaluates to true. The expression is evaluated every time the value of a dependent control is changed. This is only available to control types for which the enabled javascript field is visible in the user interface.

ExtendedDescription optional string

Extended description for the field.

FieldGroupId optional int

The field group to use.

FieldInfoId optional int

It is recommended to use FieldInfo instead.

ID of field information to base the dynamic field on. All properties not explicitly overridden by dynamic field information will be copied from this field. The referenced field must be found in the menu item's field tables.

FieldLabel optional string

If present the field label is used as the heading for fields instead of the field name.

FieldType optional string

The name of the control type to use. It is usually recommended to use FieldInfo instead unless the column is used to make fields hidden or uneditable.

Possible value	Description
boolean checkbox	Legacy alias. Use "checkbox" instead.
boolean dropdown
chart
checkbox
checkbox tree
colorpicker
date
datetime
dropdown
file
file upload area
heading
heading with checkbox
hidden
html	Legacy alias. Use "html editor" instead.
html editor
info text
listbox
multi-autosearch
multi-listbox
multi-picker
multirow
password
picture
radio buttons
radio cards
signature
textarea
textbox
textbox with autosearch
textbox with autosuggest
textbox with dropdown
textbox with popup
time
uneditable text

Height optional int

The height of the control.

IgnoreOnSave optional bit

Do not pass the field value to the insert/update procedure.

InfoSqlLayout optional string

Where the label is shown in relation to the contents in InfoSQL.

Possible value	Description
Default	Inherit layout from menu item.
LabelAbove	Full width, label above.
LabelLeft	Label to the left.
NoLabel	Full width, no label.
Standard	Deprecated. Use LabelLeft instead.

MandatoryJavaScript optional string

JavaScript that controls the mandatory status of the field, this overwrites nullchoice if set. This is only available to control types for which the mandatory JavaScript field is visible in the user interface.

MaxDate optional date

Only applicable to the Date and Datetime controls.

MaxLength optional int

If the control is a textbox or textarea, limits how many characters are allowed in it.

MinDate optional date

Only applicable to the Date and Datetime controls.

NullChoice optional bit

Specifies whether the control allows null values.

NumberOfDecimals optional int

The number of decimals to display for numeric values.

OnChangeJavaScript optional string

Javascript run when the value of the control has changed.

OutputFormat optional string

Special formatting to be applied when the field is displayed.

Possible value	Description
Hyperlink
MailToLink
PhoneLink

Placeholder optional string

Text shown when the field is empty.

ShowRightOfPreviousField optional bit

Display this field to the right of the previous field in the multi-control.

Sql optional string

The SQL that determines the control's behavior. (Refer to control documentation for more information)

TempTableName optional sysname

Only applicable to the Multi-control and Multirow controls. Do not include #-sign, it will be prepended automatically.

TextDirection optional string

Which direction the script is written in. Not to be confused with the CellAlignment property.

Possible value	Description
default	System default. Not useful unless you are trying to override an already explicit text direction on existing field information.
ltr	Left-to-right (for example English)
rtl	Right-to-left (for example Arabic)

ThousandDelimiter optional string

The thousand grouping delimiter for numeric values.

TimePickerFrom optional string

Only applicable to the Time and Datetime controls.

TimePickerTo optional string

Only applicable to the Time and Datetime controls.

Width optional int

The width of the control.

At one point, this was a pixel value. Back when Softadmin used Verdana 10px, and before fields had width-categories. Now, it is just a value that is converted to a width category.

The possible values listed below are just suggestions. For example, both 1 and 30 will be converted to *shortest*, and both 500 and 9999 to *longest*.

Possible value	Description
150	Medium-long
30	Shortest
300	Long
500	Longest
60	Short
90	Medium short

VisibleJavaScript optional string

JavaScript that controls the visibility of the field. The control is only visible if the expression specified here evaluates to true. The expression is evaluated every time the value of a dependent control is changed.

Examples

Simple multi-control

CREATE PROCEDURE Example.Question_MultiControl
	@Id		int = NULL
AS
BEGIN
	SELECT
		-- Name that can be used to reference the field in visibility, defaultvalue and SQL fields
		'MultiControlTable' + CONVERT(varchar(100), Q.QuestionId) AS [FieldName],
		Q.QuestionHeading AS [FieldLabel],
		Q.QuestionId AS [Id],
		Q.DefaultChoice AS Value,
		-- All non dynamic field info properties should come from the field info.
		123 AS FieldInfoId,
		-- Any properties that needs to be set dynamically.
		A.AnswerSql AS SQL
	FROM
		Example.Question Q
		CROSS APPLY Example.Question_AnswerSql(Q.QuestionId) A
	ORDER BY
		Q.SortOrder;
END;

Multi-control from table data

Example multicontrol procedure. In the example an input field per row in MultiControlTable will be created and if there is a corresponding value in MultiControlTable it will populate the field.

The [FieldName] column is only needed if you have dependencies.

CREATE PROCEDURE Example.MultiControlTable_MultiControl
	@Id		int = NULL
AS
BEGIN

	SELECT
		-- Name that can be used to reference the field in visibility, defaultvalue and SQL fields
		'MultiControlTable' + CONVERT(varchar(100), MCTT.MultiControlTableTypeId) AS [FieldName],
		MCTT.MultiControlTableTypeName AS [FieldLabel],
		MCTT.Description,
		-- Id value passed to InsertUpdate procedure in Id column to identify value
		MCTT.MultiControlTableTypeId AS [Id],
		MCT.Value,
		-- Use "SQL: " an in regular field info to run a SQL statement
		MCTT.DefaultValue,
		MCTT.CanAllowNullValues AS [NullChoice],
		-- The different field types in Softadmin are valid choices
		CASE
			WHEN MCTT.IsDropdown = 1 THEN
				'dropdown'
			WHEN MCTT.IsHeading = 1 THEN
				'heading'
			WHEN MCTT.IsTextbox = 1 THEN
				'textbox'
		END AS [FieldType],
		-- SQL statement for field types that require it
		MCTT.SQL,
		MCTT.Height,
		MCTT.Width,
		-- Visibility field
		CASE
			WHEN MCTT.MultiControlTableTypeId = 4 THEN
				'{MultiControlTable3}=="test"'
		END AS [VisibleJavascript]
	FROM
		-- One field per row in Example.MultiControlTableType
		Example.MultiControlTableType MCTT
		-- Get value from Example.MultiControlTable if it exists
		LEFT JOIN Example.MultiControlTable MCT ON
			MCT.MultiControlTableTypeId = MCTT.MultiControlTableTypeId AND
			MCT.RowId = @Id
	ORDER BY
		MCTT.MultiControlTableTypeName

END

Best practice

Name of stored procedure

The stored procedure should be named "<Schema>.<TableMultiControlGetsRowsFrom>_MultiControl".