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,
    });
}