Hsl JS Library Form Helpers
⚠️ Hsl.form is designed to work on Unified Interface forms only. It may have problems when running on the Classic UI.
Hsl.form
Hsl.form(_e: Xrm.Events.EventContext | Xrm.FormContext): FormContext;
// Be sure to check 'Pass execution context as first parameter'
function hsl_formOnLoad(e) {
const form = Hsl.form(e);
form.attribute('hsl_field').setVisible(false);
}
// Be sure to add PrimaryControl as a parameter to the ribbon callback
function hsl_ribbonButtonClick(e) {
const form = Hsl.form(e);
const field = form.attribute('hsl_field');
field.setSingleValue({
entityType: 'hsl_test',
id: '{9BE8A771-D9D4-43B8-8995-2F6E4F907333}',
name: 'My Test Record',
});
}
FormContext
The Hsl FormContext provides methods for helping interact with the form.
xrmForm
form.xrmForm: Xrm.FormContext;
Gets the wrapped xrm form context.
form.xrmForm.data.entity.save();
attribute
/** Returns the Xrm.Attributes.Attribute object as an Hsl.attribute object.
* @param {Xrm.Attributes.Attribute} attr The Xrm attribute object to wrap */
form.attribute(attr: Xrm.Attributes.Attribute | string): Attribute;
/** Gets the attribute with the specified id.
* @param {string} attributeName Id of the attribute to retrieve.
* @param {boolean} errorIfNotFound Default: true. Optional. Specifies whether an error
* should be thrown if the attribute is not found. If
* false and the attribute is not found, null is returned.
* @returns {Hsl.attribute} */
form.attribute(attributeName: string, errorIfNotFound?: boolean): Attribute | null;
Creates a new Hsl.Attribute object based on either the attribute name or an Xrm Attribute object.
If the attribute is a Lookup or Picklist field LookupAttribute or PicklistAttribute will be returned.
function attributeSample(xrmForm) {
const form = Hsl.form(xrmForm);
form.attribute('name').setVisible(false);
const nameAttribute = form.attribute(xrmForm.getAttribute('name'));
nameAttribute.setVisible(false);
}
control
/** Gets an Xrm.Controls.Control object as an Hsl.control object.
* @param {Xrm.Controls.Control} control The control object or the id of the control */
form.control(control: string | Xrm.Controls.Control): Control;
/** Gets the control with the specified id.
* @param {string} controlName Id of the attribute to retrieve.
* @param {boolean} errorIfNotFound Optional. Default: true. Specifies whether or not an error
* should be thrown if the control is not found. */
form.control(controlName: string, errorIfNotFound?: boolean): Control | null;
Creates a new Hsl.Control object based on either the control name or an Xrm Control object.
setDisabled
/** Disables/enables all controls on the form except the specified ones.
* @param controlIdsToExclude list of controls to not disable.
* @param disable Boolean indicating whether the form should be disabled.
*/
setDisabled(controlIdsToExclude: string[], disable: boolean): Dictionary<boolean>;
Disables/enables
function hsl_formOnLoad_setDisabledSample(e) {
const form = Hsl.form(e);
if (form.attribute('hsl_approvalstatus').getValue() !== 29601001) {
// Disable everything except the field 'hsl_approvalcomments'.
form.setDisabled(['hsl_approvalcomments'], true);
}
}
getRecordId
form.getRecordId(): string | null
Gets the id of the current record. If the record has not been created, null will be returned.
getsReference
form.getsReference(): RecordReference | null
Gets a RecordReference for the current record. If the record has not been created, null will be returned.
disableAutoSave
form.disableAutoSave(_opts?: AutoSaveDisableOptions): void
Call this in the form load to prevent the autosave event when it fires. This can be used to prevent autosave on a single form. To disable autosave globally, use the system setting.
interface AutoSaveDisableOptions {
/** Whether the user should explicitely have to hit the save button.
* If true, SaveAndClose will be prevented in addition to autosave.
* This is because Navigating away from the form triggers a SaveAndClose.
* Set to false if you just don't want auto-save to keep triggering plugin logic or something similar.
* Default: true
*/
requireExplicitSave?: boolean;
}
function hsl_formOnLoadSample(e) {
const form = Hsl.form(e);
form.disableAutoSave({
requireExplicitSave: false,
});
}