pacx forms addhandler

Registers a javascript event handler on the main form of a given table

Aliases

pacx form addhandler

Usage

Registering event handlers via the form designer is a manual, per-form activity. This command writes the same formLibraries and events entries into the form definition that the designer would, so the registration stays visible (and editable) in the designer afterwards.

Attach an OnLoad handler to the main form of a table:

pacx forms addhandler --table account --library myprefix_scripts.js --function My.Account.onLoad

Attach an OnChange handler to a specific column:

pacx forms addhandler -t account -l myprefix_scripts.js -fn My.Account.onNameChange -e OnChange --field name

If the webresource library is not yet referenced by the form, it is added automatically. If the same function of the same library is already registered on the event, the command makes no change (only the passExecutionContext setting is updated when it differs), so it is safe to run repeatedly (e.g. from a setup script).

Use --output to save a backup of the original form before any change is applied, e.g. when running against forms you care about:

pacx forms addhandler -t account -l myprefix_scripts.js -fn My.Account.onLoad --output C:\temp

By default the form is updated through a temporary solution, so the change goes through the all-or-nothing validation of a solution import. Use --fast to update the formxml of the form directly instead, which takes seconds instead of minutes:

pacx forms addhandler -t account -l myprefix_scripts.js -fn My.Account.onLoad --fast

Please note: to update the form the command needs to create a temporary solution in the target environment. The temporary solution is deleted automatically once the operation is complete.

Arguments

Long Name	Short Name	Required?	Description	Default value	Valid values
table	t	Y	The name of the table to which the form belongs	-	String
library	l	Y	The name of the javascript webresource that contains the handler function (e.g. myprefix_/scripts/account.js)	-	String
function	fn	Y	The name of the function to call, including its namespace (e.g. My.Account.onLoad)	-	String
event	e	N	The form event to attach the handler to.	OnLoad	OnLoad, OnSave, OnChange
field	col	N	The logical name of the column to watch. Required for (and only valid with) the OnChange event.	-	String
passContext	ctx	N	Whether the execution context is passed as first parameter to the handler.	True	true, false
form	f	N	The name of the form to update. It is required only if the table has more than one Main form.	-	String
solution	s	N	The name of the solution that contains the table. If not provided, the default solution will be used	-	String
output	out	N	If specified, the command will export the original version of the form in the specified folder before applying any change. The folder must exist.	-	String
fast	ft	N	Updates the formxml of the form directly instead of going through a temporary solution. Much faster; the platform still validates the formxml on update, but the all-or-nothing safety of a solution import is skipped.	False	true, false