Forms 2.0 - Javascript APIs

caution

This page is preliminary and subject to change as Forms 2.0 continues to be developed.

Forms 2.0 comes with a JavaScript API, exposed on the global paa object, that lets your own scripts control forms and the other Plant an App modules on the page - showing and hiding a form, opening it as a modal, refreshing a Listing, switching Tabs, driving Search results, and reading or updating the query string.

The API replaces the legacy dnnsf.* API used by the classic Form module. Each section below lists the new method alongside the legacy method it replaces, and the Migration quick reference at the end of the page maps every legacy call in one table.

The API is grouped into namespaces:

Namespace	Controls
paa.form	Forms 2.0 forms
paa.listing	Listings (grids)
paa.tabs	Tabs
paa.search	Search results
paa.common	General utilities (UUIDs, time zones, URLs, query string)

Form

Every paa.form method takes a moduleIdentifier as its first argument. This can be either the form's module ID or its Popup Name - the popup name works with every paa.form method, not only when showing the form.

Method	What it does	Replaces
paa.form.show(moduleIdentifier, ...)	Shows the form. Use display: 'inline' to show it on the page, or display: 'popup' to open it as a modal.	dnnsf.api.actionForm.showFormInline(mid) dnnsf.api.actionForm.openPopupById(mid, params, refresh) dnnsf.api.actionForm.openPopupByName(moduleName, params, refresh)
paa.form.hide(moduleIdentifier)	Hides the form, whether it is shown inline or as a modal.	dnnsf.api.actionForm.hideFormInline(mid) dnnsf.api.actionForm.closePopupById(mid)
paa.form.reinit(moduleIdentifier, params)	Reinitializes the form, optionally passing it new parameters.	dnnsf.api.actionForm.initForm(mid, params)
paa.form.showLoading(moduleIdentifier)	Shows the form's loading animation.	dnnsf.api.actionForm.showFormLoading(mid)
paa.form.hideLoading(moduleIdentifier)	Hides the form's loading animation.	dnnsf.api.actionForm.hideFormLoading(mid)
paa.form.refreshField(moduleIdentifier, fieldName)	Refreshes a field. If the field sits inside a repeater, every repeater entry of that field is refreshed.	dnnsf.api.actionForm.refreshField(mid, fieldName)
paa.form.isModalOpen(moduleIdentifier)	Returns whether the form is currently open as a modal.	dnnsf.api.actionForm.isFormPopupOpen(mid)

note

Parameters passed when showing a form are now sent as Paa-Data headers, not added to the query string as they were with openPopupById / openPopupByName. If your form's logic reads these values from the query string, update it accordingly.

Dropped form methods

The following legacy methods have no Forms 2.0 equivalent, because Forms 2.0 has no settings object to read or patch:

• dnnsf.api.actionForm.getSettings(mid, settings?)
• dnnsf.api.actionForm.patchSettings(mid)

Listing

The Listing methods keep their legacy names, now under the paa.listing namespace.

Method	What it does	Replaces
paa.listing.refresh(moduleIdentifier, delay)	Refreshes the Listing's data, after an optional delay in milliseconds.	dnnsf.api.actionGrid.refresh(mid, delay)
paa.listing.showGrid(moduleIdentifier)	Shows the Listing.	dnnsf.api.actionGrid.showGrid(mid)
paa.listing.hideGrid(moduleIdentifier)	Hides the Listing.	dnnsf.api.actionGrid.hideGrid(mid)
paa.listing.showGridPopup(moduleIdentifier, modalSettings, refresh)	Opens the Listing as a modal. There is no parameters argument.	dnnsf.api.actionGrid.showGridPopup(mid, modalSettings, refresh)
paa.listing.hideGridPopup(moduleIdentifier)	Closes the Listing modal.	dnnsf.api.actionGrid.hideGridPopup(mid)
paa.listing.clearGridQueryString(moduleIdentifier)	Clears the query string parameters that belong to the Listing.	dnnsf.api.actionGrid.clearGridQueryString(mid)

Tabs

The Tabs methods take a single object argument, as the legacy methods did. The object always includes mid, the Tabs module ID.

Method	What it does	Replaces
paa.tabs.changeTab(options)	Switches to another tab.	dnnsf.api.tabspro.changeTab(options)
paa.tabs.refreshTabPro(options)	Re-evaluates the tabs' conditions.	dnnsf.api.tabspro.refreshTabPro(options)
paa.tabs.openModal(options)	Opens the Tabs module as a modal.	dnnsf.api.tabspro.openModal(options)
paa.tabs.closeModal(options)	Closes the Tabs modal.	dnnsf.api.tabspro.closeModal(options)

For changeTab, viewOrder is the zero-based position of the tab to switch to, and refresh controls whether the tab is refreshed:

// Switch the Tabs module 402 to its third tab and refresh it
paa.tabs.changeTab({ mid: 402, viewOrder: 2, refresh: true });

// Open the Tabs module 402 as a modal
paa.tabs.openModal({ mid: 402 });

Search

The Search methods don't take a module identifier: they always apply to the Search results module on the page.

Method	What it does	Replaces
paa.search.changeCategory(category)	Filters the results by a category.	dnnsf.api.searchboost.changeFilter(category)
paa.search.clearCategory()	Clears the category filter.	dnnsf.api.searchboost.clearFilter()
paa.search.changePageSize(pageSize)	Changes how many results are shown per page.	dnnsf.api.searchboost.changePageSize(pageSize)
paa.search.changePageTo(page)	Moves to a given results page. The page's query string parameter name still comes from the Search results settings.	dnnsf.api.searchboost.changePageTo(page)
paa.search.changeSort(sort)	Changes how the results are sorted.	dnnsf.api.searchboost.changeSort(sort)
paa.search.searchMoreLikeThis(docId)	Searches for results similar to a given document.	dnnsf.api.searchboost.searchMoreLikeThis(docId)

Common

paa.common holds general-purpose utilities, and paa.common.qs groups the helpers for reading and changing the page's query string.

Method	What it does	Replaces
paa.common.generateUUID()	Returns a new UUID.	dnnsf.generateUuid()
paa.common.getTimezoneOffset(date?)	Returns the time zone offset, optionally for a given date.	dnnsf.getTimezoneOffset()
paa.common.getUrlParts(url?)	Splits a URL into its parts. The url argument is optional and defaults to the current page URL.	dnnsf.getUrlParts(url)
paa.common.qs.get(key)	Returns the value of a query string parameter, or undefined if it isn't present.	dnnsf.urlParam(key)
paa.common.qs.list()	Returns all the query string parameters.	dnnsf.urlParams
paa.common.qs.set(key, value)	Adds or updates a query string parameter.	dnnsf.updateQueryStringParam(key, value)
paa.common.qs.delete(key)	Removes a query string parameter.	New - no legacy equivalent

note

When migrating code, watch for these behavior changes:

• paa.common.qs.get(key) returns undefined when the parameter is missing, whereas dnnsf.urlParam(key) returned 0. Update any checks such as if (dnnsf.urlParam('id') === 0).
• paa.common.qs.list() is a function, whereas the legacy dnnsf.urlParams was a property.

// Read the "id" parameter from the current URL
var id = paa.common.qs.get('id');

if (id === undefined) {
    // Set it, then generate a UUID for a new record
    paa.common.qs.set('id', paa.common.generateUUID());
}

Migration quick reference

Legacy method	Forms 2.0 method
dnnsf.api.actionForm.openPopupById(mid, params, refresh)	paa.form.show(moduleIdentifier, ...) with display: 'popup'
dnnsf.api.actionForm.openPopupByName(moduleName, params, refresh)	paa.form.show(moduleIdentifier, ...) with display: 'popup'
dnnsf.api.actionForm.closePopupById(mid)	paa.form.hide(moduleIdentifier)
dnnsf.api.actionForm.showFormInline(mid)	paa.form.show(moduleIdentifier, ...) with display: 'inline'
dnnsf.api.actionForm.hideFormInline(mid)	paa.form.hide(moduleIdentifier)
dnnsf.api.actionForm.initForm(mid, params)	paa.form.reinit(moduleIdentifier, params)
dnnsf.api.actionForm.showFormLoading(mid)	paa.form.showLoading(moduleIdentifier)
dnnsf.api.actionForm.hideFormLoading(mid)	paa.form.hideLoading(moduleIdentifier)
dnnsf.api.actionForm.refreshField(mid, fieldName)	paa.form.refreshField(moduleIdentifier, fieldName)
dnnsf.api.actionForm.isFormPopupOpen(mid)	paa.form.isModalOpen(moduleIdentifier)
dnnsf.api.actionForm.getSettings(mid, settings?)	Dropped
dnnsf.api.actionForm.patchSettings(mid)	Dropped
dnnsf.api.actionGrid.refresh(mid, delay)	paa.listing.refresh(moduleIdentifier, delay)
dnnsf.api.actionGrid.showGrid(mid)	paa.listing.showGrid(moduleIdentifier)
dnnsf.api.actionGrid.hideGrid(mid)	paa.listing.hideGrid(moduleIdentifier)
dnnsf.api.actionGrid.showGridPopup(mid, modalSettings, refresh)	paa.listing.showGridPopup(moduleIdentifier, modalSettings, refresh)
dnnsf.api.actionGrid.hideGridPopup(mid)	paa.listing.hideGridPopup(moduleIdentifier)
dnnsf.api.actionGrid.clearGridQueryString(mid)	paa.listing.clearGridQueryString(moduleIdentifier)
dnnsf.api.tabspro.changeTab(options)	paa.tabs.changeTab(options)
dnnsf.api.tabspro.refreshTabPro(options)	paa.tabs.refreshTabPro(options)
dnnsf.api.tabspro.openModal(options)	paa.tabs.openModal(options)
dnnsf.api.tabspro.closeModal(options)	paa.tabs.closeModal(options)
dnnsf.api.searchboost.changeFilter(category)	paa.search.changeCategory(category)
dnnsf.api.searchboost.clearFilter()	paa.search.clearCategory()
dnnsf.api.searchboost.changePageSize(pageSize)	paa.search.changePageSize(pageSize)
dnnsf.api.searchboost.changePageTo(page)	paa.search.changePageTo(page)
dnnsf.api.searchboost.changeSort(sort)	paa.search.changeSort(sort)
dnnsf.api.searchboost.searchMoreLikeThis(docId)	paa.search.searchMoreLikeThis(docId)
dnnsf.generateUuid()	paa.common.generateUUID()
dnnsf.getTimezoneOffset()	paa.common.getTimezoneOffset(date?)
dnnsf.getUrlParts(url)	paa.common.getUrlParts(url?)
dnnsf.urlParam(key)	paa.common.qs.get(key)
dnnsf.urlParams	paa.common.qs.list()
dnnsf.updateQueryStringParam(key, value)	paa.common.qs.set(key, value)
-	paa.common.qs.delete(key)