Upgrading from version 8 to 9 of the JavaScript Library
General
- Hsl.Dialog.confirm and Hsl.Dialog.alert now return promises instead of having function passed as parameter. No longer accept dialog options.
- DialogOptions
content
setting for Hsl.Dialog.open and related methods is nowcontentHtml
- Hsl.enumHasFlag removed. Use
(enumValue & flag) === flag;
instead. - Hsl.lookup is now Hsl.Dialog.lookup and now returns a Promise instead of using a callback parameter.
Form
Due to the Xrm.Page deprecation, most methods relating to the form were moved to be on a new FormContext class. For more details see Using Form Context
- Form.getRecordId and LookupAttribute.getValue (and related methods like getValueId) now return guids in all lower case.
- LookupAttribute setSingleValue no longer accepts an EntityReference and only takes a RecordReference.
- Many methods are removed. See the Documentation for details on what remains.
Using the FormContext
Form code that referenced Hsl.Form will need to replace calls to methods of global Hsl.Form with methods using the local FormContext.
So code like this for the v8 version of the library:
function hsl_accountOnLoad(e) {
const nameAttribute = Hsl.attribute('hsl_name');
nameAttribute.setVisible(false);
const nameValue = nameAttribute.getValue();
}
Now needs to use methods on the Hsl.FormContext
object returned from Hsl.form
.
function hsl_accountFormOnLoad(ctx) {
const form = Hsl.form(ctx);
const nameAttribute = form.attribute('hsl_name');
nameAttribute.setVisible(false);
const nameValue = nameAttribute.getValue();
}
⚠️ When registering the on load event in the form editor, be sure to check "Pass execution context as first parameter"
WebApi
- Hsl.WebApi.client now defaults to version 9 of the WebApi endpoint and the equivalent of
Hsl.WebApi.getClient('9.0')
. For backwards compatibility, you can setHsl.WebApi.client = Hsl.WebApi.getClient('8.0')
which will change the default client for all scripts on the current page. - Not specifying a select list for retrieve or expand will now result in an error. Specify
null
to select all columns. bulkRetrieveByIds
,fetchAll
, andqueryAll
now support synchronous execution.- Hsl.WebApi.encodeEntityType and Hsl.WebApi.bindReference now return a placeholder object
- Added new
useNonStandardSyncPromise
setting. - Hsl.currentUser redone. See documentation page (TODO: add link) for details. It is now part of the main library.core.js and no longer part of the library.orgservice.js file.
- Added Hsl.WebApi.executeService. Works similar to Hsl.OrgService.executeService but only supports execution using custom actions. Doesn't support retrieve or create.
- Overloads using
CollectionReference
orAlternateKeyLookupReferenceCollection
that reference the webapi collection name likeclient.create({ collectionName: 'accounts' }, { name: 'abc' })
are removed. Use the overloads referencing the entity logical name instead.client.create('account', { name: 'abc' })
- Methods on the retrieved records (getValue, getFormattedValue, getLookupLogicalName, and getRecordReference) now throw an error for properties not included in the select list. Ex: if you retrieve just the 'name' property of an account,
record.getValue('accountnumber')
will throw an error instead of returning null. Use'accountnumber' in record
to determine whether it contains a particular property. For compatibility with older versions, use theallowUnknownGet
setting ofHsl.WebApi.getClient
. createAndGet
,updateAndGet
, andupsertAndGet
now allow specifyingformattedValues: true
orannotations: '*'
.- FetchXml is now minified prior to passing it to the web service (excess whitespace and xml comments are removed).
Removed Functionality
- Hsl.Cloning - This has been split off into its own separate solution. See the documentation for Hsl Hierarchy Cloning for details on upgrading.
- Hsl.OrgData (library.legacyodata.js). Used for connecting to the 2011 oData v2 endpoint.
- CEI (library.legacycei.js)
- jQuery - Hsl.$, Hsl.jQuery, hsl.jquery.js file. JQuery is still available through the dialog context when using Hsl.Dialog but if you need it elsewhere, create a custom web resource to use jQuery https://jquery.com/download/.
- JQuery UI -
loadJQueryUI
in Hsl.Dialog and jquery-ui-modified.js file. You can load jQuery UI yourself using loadScriptResource and the contentCss setting of the Dialog options. - Removed getCopyright, getMajorVersion, getMinorVersion, getPatchVersion
- Hsl.Console - use standard console methods with string substitutions. https://developer.mozilla.org/en-US/docs/Web/API/Console
- Hsl.Client
- Hsl.newGuid, Hsl.normalizeGuid, Hsl.guidEquals - use Hsl.Guid.getNew, Hsl.Guid.normalize, and Hsl.Guid.equals.
- DateAttributeClass setToUtcNeutral, setToNoonUtc, normalizeDate, normalizeDateOnChange - use date only behavior instead.
- Hsl.getOrganizationServiceUrl - SOAP Endpoint is deprecated.
- Hsl.fieldSet
- createFieldSet
- Hsl.getCompanyName, Hsl.getProductName
- Hsl.Notification
- LookupAttributeClass.setViewSelectorEnabled
- Hsl.WebResource.createUrl no longer accepts boolean as the third parameter to 'passParams'. It now takes a form context which, if passed, is used to build parameters.
- Hsl.Tooltips, FieldSet.setTooltip
- Hsl.Validation
- Hsl.tab, Hsl.tabSet, Hsl.section, Hsl.sectionSet
- Hsl.getEntityTypeCode, Hsl.getEntityNameFromTypeCode
- Hsl.getContextParametersString
- Hsl.userInformation, Hsl.teamInformation (Hsl.currentUser still exists but redone)
- Hsl.List (makeArray, selectMany, unique)
- Hsl.normalizeDate
- Form save handlers
- Hsl.String.format
- Hsl.dateFormat - most uses can be handled using Intl.DateTimeFormat API (see contructor details for options available)
- Hsl.Dialog methods openError, openWarning, openInfo, and openHelp. Use
Hsl.Dialog.open
instead.