core_v2_widget Script API

Ben Tiedt — Wed, 20 Nov 2019 14:54:30 GMT

Current Revision posted to API Documentation by Ben Tiedt on 11/20/2019 14:54:30

Enables scripted content fragments to get contextual and configuration data related to the current widget / content fragment.

Properties
ApplyTokens
ClearValue
ExecuteEmbeddedFile
ExecuteFile
GetBoolValue
GetColorValue
GetCustomValue
GetDateTimeValue
GetDoubleValue
GetEmbeddedFile
GetEmbeddedFileByUrl
GetEmbeddedFiles
GetExecutedEmbeddedFileUrl
GetExecutedFileUrl
GetExecutionParameterValue
GetExecutionParameterValues
GetFileUrl
GetGuidValue
GetHtmlValue
GetIntValue
GetScheduledFileStatus
GetStringValue
GetUnitValue
GetUrlListValue
GetUrlValue
Hide
RenderEmbeddedFile
RenderFile
ScheduleFile
SetBoolValue
SetColorValue
SetCustomValue
SetDateTimeValue
SetDoubleValue
SetGuidValue
SetHtmlValue
SetIntValue
SetStringValue
SetUnitValue
SetUrlListValue
SetUrlValue
UniqueId

Properties

Name	Access	Type	Description
IsInWidgetPreviewMode	Read	`Boolean`	Returns true when the widget's containing page, header, or footer is being edited
RegionName	Read	`String`	Name of the current widget's region
WrapperElementId	Read	`String`	DOM Id of the current widget's wrapper element

Methods

ApplyTokens

Process tokens, such as resources, in a string

Velocity

#set($stringResponse = $core_v2_widget.ApplyTokens($html))

JavaScript

var stringResponse = core_v2_widget.ApplyTokens(html);

Parameters

Name	Type	Description	Required	Default	Options
html	`String`	Html	Required

Returns

String

ClearValue

Removes the configured value for a property.

Velocity

$core_v2_widget.ClearValue($propertyName)

JavaScript

core_v2_widget.ClearValue(propertyName);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required

Returns

Nothing

ExecuteEmbeddedFile

Velocity

#set($stringResponse = $core_v2_widget.ExecuteEmbeddedFile($propertyName, $fileName))

JavaScript

var stringResponse = core_v2_widget.ExecuteEmbeddedFile(propertyName, fileName);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
fileName	`String`	File Name	Required

Returns

String

ExecuteFile

ExecuteFile Overload 1

Loads, executes, and returns the content of an attached widget script file

Velocity

#set($objectResponse = $core_v2_widget.ExecuteFile($fileName))

JavaScript

var objectResponse = core_v2_widget.ExecuteFile(fileName);

Parameters

Name	Type	Description	Required	Default	Options
fileName	`String`	Name of attached widget script	Required

ExecuteFile Overload 2

Loads, executes, and returns the content of an attached widget script file. If any execution options are defined, the result will not support interaction--objects returned from JavaScript will not support setting properties or executing functions.

Velocity

#set($objectResponse = $core_v2_widget.ExecuteFile($fileName, "%{ DisableAbuseChecking = $disableAbuseCheckingArg, DisableActivityStories = $disableActivityStoriesArg, DisableNotifications = $disableNotificationsArg, Parameters = $parametersArg, RunAsServiceUser = $runAsServiceUserArg, RunAsUserName = $runAsUserNameArg }"))

JavaScript

var objectResponse = core_v2_widget.ExecuteFile(fileName, { DisableAbuseChecking: disableAbuseCheckingArg, DisableActivityStories: disableActivityStoriesArg, DisableNotifications: disableNotificationsArg, Parameters: parametersArg, RunAsServiceUser: runAsServiceUserArg, RunAsUserName: runAsUserNameArg });

Parameters

Name	Type	Description	Required	Default
fileName	`String`	Name of attached widget script	Required
DisableAbuseChecking	`Boolean`	Disables abuse checking while executing the file	Optional	False
DisableActivityStories	`Boolean`	Disables activity story creation while executing the file	Optional	False
DisableNotifications	`Boolean`	Disables notification creation while executing the file	Optional	False
Parameters	`IDictionary`	Dictionary of parameters to provide to the widget script being executed. Parameters are available through the GetExecutionParameterValue and GetExecutionParameterValues methods.	Optional
Parameters	`[[QueryString Script API Type\|QueryString]]`	QueryString of parameters to provide to the widget script being executed. Parameters are available through the GetExecutionParameterValue and GetExecutionParameterValues methods.	Optional
RunAsServiceUser	`Boolean`	Executes the file as the service user (with full permissions)	Optional	False
RunAsUserName	`String`	The username of the user to execute the file as	Optional

Returns

Object

GetBoolValue

GetBoolValue Overload 1

Returns the boolean widget configuration value specified by the property name

Velocity

#set($nullableResponse = $core_v2_widget.GetBoolValue($propertyName))

JavaScript

var nullableResponse = core_v2_widget.GetBoolValue(propertyName);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required

GetBoolValue Overload 2

Returns the boolean widget configuration value specified by the property name

Velocity

#set($nullableResponse = $core_v2_widget.GetBoolValue($propertyName, $defaultValue))

JavaScript

var nullableResponse = core_v2_widget.GetBoolValue(propertyName, defaultValue);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
defaultValue	`Boolean`	Default Value	Required

Returns

Nullable of Boolean

GetColorValue

Returns the color widget configuration value specified by the property name

Velocity

#set($stringResponse = $core_v2_widget.GetColorValue($propertyName, $defaultValue))

JavaScript

var stringResponse = core_v2_widget.GetColorValue(propertyName, defaultValue);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
defaultValue	`String`	Default Value	Required

Returns

String

GetCustomValue

Returns the custom widget configuration value specified by the property name

Velocity

#set($stringResponse = $core_v2_widget.GetCustomValue($propertyName, $defaultValue))

JavaScript

var stringResponse = core_v2_widget.GetCustomValue(propertyName, defaultValue);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
defaultValue	`String`	Default Value	Required

Returns

String

GetDateTimeValue

GetDateTimeValue Overload 1

Returns the DateTime widget configuration value specified by the property name

Velocity

#set($nullableResponse = $core_v2_widget.GetDateTimeValue($propertyName))

JavaScript

var nullableResponse = core_v2_widget.GetDateTimeValue(propertyName);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required

GetDateTimeValue Overload 2

Returns the DateTime widget configuration value specified by the property name

Velocity

#set($nullableResponse = $core_v2_widget.GetDateTimeValue($propertyName, $defaultValue))

JavaScript

var nullableResponse = core_v2_widget.GetDateTimeValue(propertyName, defaultValue);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
defaultValue	`DateTime`	Default Value	Required

Returns

Nullable of DateTime

GetDoubleValue

GetDoubleValue Overload 1

Returns the double widget configuration value specified by the property name

Velocity

#set($nullableResponse = $core_v2_widget.GetDoubleValue($propertyName))

JavaScript

var nullableResponse = core_v2_widget.GetDoubleValue(propertyName);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required

GetDoubleValue Overload 2

Returns the double widget configuration value specified by the property name

Velocity

#set($nullableResponse = $core_v2_widget.GetDoubleValue($propertyName, $defaultValue))

JavaScript

var nullableResponse = core_v2_widget.GetDoubleValue(propertyName, defaultValue);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
defaultValue	`Double`	Default Value	Required

Returns

Nullable of Double

GetEmbeddedFile

Velocity

#set($fileResponse = $core_v2_widget.GetEmbeddedFile($propertyName, $fileName))

JavaScript

var fileResponse = core_v2_widget.GetEmbeddedFile(propertyName, fileName);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
fileName	`String`	File Name	Required

Returns

[[File Script API Type|File]]

GetEmbeddedFileByUrl

Velocity

#set($fileResponse = $core_v2_widget.GetEmbeddedFileByUrl($propertyName, $url))

JavaScript

var fileResponse = core_v2_widget.GetEmbeddedFileByUrl(propertyName, url);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
url	`String`	Url	Required

Returns

[[File Script API Type|File]]

GetEmbeddedFiles

Velocity

#set($iEnumerableResponse = $core_v2_widget.GetEmbeddedFiles($propertyName))

JavaScript

var iEnumerableResponse = core_v2_widget.GetEmbeddedFiles(propertyName);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required

Returns

IEnumerable of [[File Script API Type|File]]

GetExecutedEmbeddedFileUrl

Velocity

#set($stringResponse = $core_v2_widget.GetExecutedEmbeddedFileUrl($propertyName, $fileName))

JavaScript

var stringResponse = core_v2_widget.GetExecutedEmbeddedFileUrl(propertyName, fileName);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
fileName	`String`	File Name	Required

Returns

String

GetExecutedFileUrl

Returns an absolute URL for a given widget attachment which, when requested, processes the attachment and reeturns its output

Velocity

#set($stringResponse = $core_v2_widget.GetExecutedFileUrl($fileName))

JavaScript

var stringResponse = core_v2_widget.GetExecutedFileUrl(fileName);

Parameters

Name	Type	Description	Required	Default	Options
fileName	`String`	Name of attached widget script	Required

Returns

String

GetExecutionParameterValue

Gets an execution parameter value

Velocity

#set($stringResponse = $core_v2_widget.GetExecutionParameterValue($name))

JavaScript

var stringResponse = core_v2_widget.GetExecutionParameterValue(name);

Parameters

Name	Type	Description	Required	Default	Options
name	`String`	Parameter value key	Required

Returns

String

GetExecutionParameterValues

Gets all execution parameter values matching a key

Velocity

#set($stringResponse = $core_v2_widget.GetExecutionParameterValues($name))

JavaScript

var stringResponse = core_v2_widget.GetExecutionParameterValues(name);

Parameters

Name	Type	Description	Required	Default	Options
name	`String`	Parameter value key	Required

Returns

Array of String

GetFileUrl

Returns an absolute URL for a given widget attachment

Velocity

#set($stringResponse = $core_v2_widget.GetFileUrl($fileName))

JavaScript

var stringResponse = core_v2_widget.GetFileUrl(fileName);

Parameters

Name	Type	Description	Required	Default	Options
fileName	`String`	Name of widget attachment	Required

Returns

String

GetGuidValue

GetGuidValue Overload 1

Returns the Guid widget configuration value specified by the property name

Velocity

#set($nullableResponse = $core_v2_widget.GetGuidValue($propertyName))

JavaScript

var nullableResponse = core_v2_widget.GetGuidValue(propertyName);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required

GetGuidValue Overload 2

Returns the Guid widget configuration value specified by the property name

Velocity

#set($nullableResponse = $core_v2_widget.GetGuidValue($propertyName, $defaultValue))

JavaScript

var nullableResponse = core_v2_widget.GetGuidValue(propertyName, defaultValue);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
defaultValue	`Guid`	Default Value	Required

Returns

Nullable of Guid

GetHtmlValue

Returns the HTML widget configuration value specified by the property name

Velocity

#set($stringResponse = $core_v2_widget.GetHtmlValue($propertyName, $defaultValue))

JavaScript

var stringResponse = core_v2_widget.GetHtmlValue(propertyName, defaultValue);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
defaultValue	`String`	Default Value	Required

Returns

String

GetIntValue

GetIntValue Overload 1

Returns the integer widget configuration value specified by the property name

Velocity

#set($nullableResponse = $core_v2_widget.GetIntValue($propertyName))

JavaScript

var nullableResponse = core_v2_widget.GetIntValue(propertyName);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required

GetIntValue Overload 2

Returns the integer widget configuration value specified by the property name

Velocity

#set($nullableResponse = $core_v2_widget.GetIntValue($propertyName, $defaultValue))

JavaScript

var nullableResponse = core_v2_widget.GetIntValue(propertyName, defaultValue);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
defaultValue	`Int32`	Default Value	Required

Returns

Nullable of Int32

GetScheduledFileStatus

GetScheduledFileStatus Overload 1

Retrieves the status of a script execution scheduled with a 'ProgressKey' for reporting its status.

Velocity

#set($scheduledFileStatusResponse = $core_v2_widget.GetScheduledFileStatus($key))

JavaScript

var scheduledFileStatusResponse = core_v2_widget.GetScheduledFileStatus(key);

Parameters

Name	Type	Description	Required	Default	Options
key	`String`	Identifier matching the 'ProgressKey' passed to core_v2_widget.ScheduleFile()	Required

GetScheduledFileStatus Overload 2

Retrieves the status of a script execution scheduled with a 'ProgressKey' for reporting its status.

Velocity

#set($scheduledFileStatusResponse = $core_v2_widget.GetScheduledFileStatus($key, "%{ IncludeResult = $includeResultArg }"))

JavaScript

var scheduledFileStatusResponse = core_v2_widget.GetScheduledFileStatus(key, { IncludeResult: includeResultArg });

Parameters

Name	Type	Description	Required	Default	Options
key	`String`	Identifier matching the 'ProgressKey' passed to core_v2_widget.ScheduleFile()	Required
IncludeResult	`Boolean`	Includes the completion result, when available.	Optional	False

Returns

[[ScheduledFileStatus Script API Type|ScheduledFileStatus]]

GetStringValue

Returns the string widget configuration value specified by the property name

Velocity

#set($stringResponse = $core_v2_widget.GetStringValue($propertyName, $defaultValue))

JavaScript

var stringResponse = core_v2_widget.GetStringValue(propertyName, defaultValue);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
defaultValue	`String`	Default Value	Required

Returns

String

GetUnitValue

Returns the Unit widget configuration value specified by the property name

Velocity

#set($stringResponse = $core_v2_widget.GetUnitValue($propertyName, $defaultValue))

JavaScript

var stringResponse = core_v2_widget.GetUnitValue(propertyName, defaultValue);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
defaultValue	`String`	Default Value	Required

Returns

String

GetUrlListValue

Returns the URL list widget configuration value specified by the property name

Velocity

#set($iListResponse = $core_v2_widget.GetUrlListValue($propertyName))

JavaScript

var iListResponse = core_v2_widget.GetUrlListValue(propertyName);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required

Returns

IList of String

GetUrlValue

Returns the URL widget configuration value specified by the property name

Velocity

#set($stringResponse = $core_v2_widget.GetUrlValue($propertyName, $defaultValue))

JavaScript

var stringResponse = core_v2_widget.GetUrlValue(propertyName, defaultValue);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
defaultValue	`String`	Default Value	Required

Returns

String

Hide

Hides the current widget

Velocity

$core_v2_widget.Hide()

JavaScript

core_v2_widget.Hide();

Returns

Nothing

RenderEmbeddedFile

Velocity

#set($stringResponse = $core_v2_widget.RenderEmbeddedFile($propertyName, $fileName))

JavaScript

var stringResponse = core_v2_widget.RenderEmbeddedFile(propertyName, fileName);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
fileName	`String`	File Name	Required

Returns

String

RenderFile

Loads and returns the content of an attached file without executing it

Velocity

#set($stringResponse = $core_v2_widget.RenderFile($fileName))

JavaScript

var stringResponse = core_v2_widget.RenderFile(fileName);

Parameters

Name	Type	Description	Required	Default	Options
fileName	`String`	Name of widget attachment	Required

Returns

String

ScheduleFile

ScheduleFile Overload 1

Schedules the execution of an attached widget script to be run on the job server.

Velocity

$core_v2_widget.ScheduleFile($fileName)

JavaScript

core_v2_widget.ScheduleFile(fileName);

Parameters

Name	Type	Description	Required	Default	Options
fileName	`String`	Name of attached widget script	Required

ScheduleFile Overload 2

Schedules the execution of an attached widget script to be run on the job server.

Velocity

$core_v2_widget.ScheduleFile($fileName, "%{ Durable = $durableArg, Parameters = $parametersArg, ProgressKey = $progressKeyArg, StartInSeconds = $startInSecondsArg }")

JavaScript

core_v2_widget.ScheduleFile(fileName, { Durable: durableArg, Parameters: parametersArg, ProgressKey: progressKeyArg, StartInSeconds: startInSecondsArg });

Parameters

Name	Type	Description	Required	Default
fileName	`String`	Name of attached widget script	Required
Durable	`Boolean`	When a script file is executed with a 'ProgressKey' for reporting its progress, 'Durable' controls whether the script continues to run if the initiating user disconnects. When 'true', the script file will continue to run if the initiating user disconnects. When 'false', the script file will request cancellation via context_v2_scheduledFile.IsCancellationRequested 5 seconds after the initiating user disconnects without reconnecting.	Optional	True
Parameters	`IDictionary`	Dictionary of parameters to provide to the widget script executed on the job server. Parameters are available through the GetExecutionParameterValue and GetExecutionParameterValues methods.	Optional
Parameters	`[[QueryString Script API Type\|QueryString]]`	QueryString of parameters to provide to the widget script executed on the job server. Parameters are available through the GetExecutionParameterValue and GetExecutionParameterValues methods.	Optional
ProgressKey	`String`	Arbitrary string identifier for the scheduled file which can be used to retrieve its execution status with core_v2_widget.GetScheduledFileStatus() or to render its execution progress with core_v2_ui.ScheduledFile(). Scripts executed with a 'ProgessKey' are also provided the context_v2_scheduldFile API for reporting their progress.	Optional
StartInSeconds	`Int32`	Number of seconds to delay before the scheduled script should start.	Optional	0

Returns

Nothing

SetBoolValue

Sets a boolean widget configuration value

Velocity

$core_v2_widget.SetBoolValue($propertyName, $value)

JavaScript

core_v2_widget.SetBoolValue(propertyName, value);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
value	`Boolean`	Value	Required

Returns

Nothing

SetColorValue

Sets a Color widget configuration value

Velocity

$core_v2_widget.SetColorValue($propertyName, $value)

JavaScript

core_v2_widget.SetColorValue(propertyName, value);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
value	`String`	Value	Required

Returns

Nothing

SetCustomValue

Sets a custom widget configuration value

Velocity

$core_v2_widget.SetCustomValue($propertyName, $value)

JavaScript

core_v2_widget.SetCustomValue(propertyName, value);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
value	`String`	Value	Required

Returns

Nothing

SetDateTimeValue

Sets a DateTime widget configuration value

Velocity

$core_v2_widget.SetDateTimeValue($propertyName, $value)

JavaScript

core_v2_widget.SetDateTimeValue(propertyName, value);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
value	`DateTime`	Value	Required

Returns

Nothing

SetDoubleValue

Sets a double widget configuration value

Velocity

$core_v2_widget.SetDoubleValue($propertyName, $value)

JavaScript

core_v2_widget.SetDoubleValue(propertyName, value);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
value	`Double`	Value	Required

Returns

Nothing

SetGuidValue

Sets a guid widget configuration value

Velocity

$core_v2_widget.SetGuidValue($propertyName, $value)

JavaScript

core_v2_widget.SetGuidValue(propertyName, value);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
value	`String`	Value	Required

Returns

Nothing

SetHtmlValue

Sets an HTML widget configuration value

Velocity

$core_v2_widget.SetHtmlValue($propertyName, $value)

JavaScript

core_v2_widget.SetHtmlValue(propertyName, value);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
value	`String`	Value	Required

Returns

Nothing

SetIntValue

Sets an integer widget configuration value

Velocity

$core_v2_widget.SetIntValue($propertyName, $value)

JavaScript

core_v2_widget.SetIntValue(propertyName, value);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
value	`Int32`	Value	Required

Returns

Nothing

SetStringValue

Sets a string widget configuration value

Velocity

$core_v2_widget.SetStringValue($propertyName, $value)

JavaScript

core_v2_widget.SetStringValue(propertyName, value);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
value	`String`	Value	Required

Returns

Nothing

SetUnitValue

Sets a unit widget configuration value

Velocity

$core_v2_widget.SetUnitValue($propertyName, $value)

JavaScript

core_v2_widget.SetUnitValue(propertyName, value);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
value	`String`	Value	Required

Returns

Nothing

SetUrlListValue

Sets a URL list widget configuration value

Velocity

$core_v2_widget.SetUrlListValue($propertyName, $value)

JavaScript

core_v2_widget.SetUrlListValue(propertyName, value);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
value	`IList of String`	Value	Required

Returns

Nothing

SetUrlValue

Sets a URL widget configuration value

Velocity

$core_v2_widget.SetUrlValue($propertyName, $value)

JavaScript

core_v2_widget.SetUrlValue(propertyName, value);

Parameters

Name	Type	Description	Required	Default	Options
propertyName	`String`	Property Name	Required
value	`String`	Value	Required

Returns

Nothing

UniqueId

Strengthens a given id to be unique across an entire page. Used to explicitly generate safe ids for DOM elements

Velocity

#set($stringResponse = $core_v2_widget.UniqueId($id))

JavaScript

var stringResponse = core_v2_widget.UniqueId(id);

Parameters

Name	Type	Description	Required	Default	Options
id	`String`	Non-unique string	Required

Returns

String