The KNS provides a number of ways to integrate Javascript into maintenance and transactional documents. A configuration parameter allows a core set of Javascript files to be imported on all pages. External Javascript files specific to a limited set of documents can easily be imported into pages using the data dictionary. Several KNS tags also support response to Javascript events.
Setting the configuration parameter is easiest of all. In the {project name}-config.xml file for most client applications, there already exists a generated line which looks like this:
<param name="javascript.files">kr/scripts/core.js,kr/scripts/dhtml.js,kr/scripts/documents.js,kr/scripts/my_common.js,kr/scripts/objectInfo.js</param>
These scripts will be pulled in on every page which uses the kul:page tag. Note that the file path is relative to the root path of the project. It bears mentioning, too, that the css.files property works the same way for CSS files:
<param name="css.files">kr/css/kuali.css</param>
It’s not always the best idea to include Javascript pages, which the browser must parse, onto every single page. If only certain documents or even a single document needs a given Javascript file, it is easiest to simply tell the data dictionary entry to import the file. Here is an example from KFS’s Account Maintenance Document (AccountMaintenanceDocument.xml):
<bean id="AccountMaintenanceDocument" parent="AccountMaintenanceDocument-parentBean"/>
<bean id="AccountMaintenanceDocument-parentBean" abstract="true" parent="MaintenanceDocumentEntry" p:businessObjectClass="org.kuali.kfs.coa.businessobject.Account" p:maintainableClass="org.kuali.kfs.coa.document.KualiAccountMaintainableImpl">
...
<property name="webScriptFiles">
<list>
<value>../dwr/interface/SubFundGroupService.js</value>
<value>../scripts/coa/accountDocument.js</value>
</list>
</property>
...
</bean>Values are expected to be relative to the base application URL of the document. In this case of a maintenance document, the URL is /application-name/kr/maintenance.do and the javascript files are located under /application-name/scripts, hence the “..” in the directories.
As will be covered in the KNS tags section, most controls in KFS documents are rendered using the kul:htmlControlAttribute tag. That tag has three attributes which will be passed on to the rendered HTML control: onblur, onclick, and onchange, which will be passed on to the rendered control. (Though there is an exception to keep in mind: radio buttons will render what was passed in the onchange attribute as onclick, to enhance support for a highly popular legacy browser.)
Extra buttons also support Javascript, specifically the “onclick” event handler. By setting the extraButtonOnclick property of an org.kuali.rice.kns.web.ui.ExtraButton object to the text that should appear in the button’s onclick call, the developer gains the ability to react, with Javascript, to the button’s click.
Finally, we want to make our maintenance documents as interactive as possible to facilitate efficient user experience. In this example, KFS’s AccountMaintenanceDocument wants to instantly give an error to users if the sub fund group assigned to the account is restricted, based on other values of the account.
To accomplish this, in the data dictionary file for the AccountMaintenanceDocument, extra JavaScript files are imported.
<property name="webScriptFiles">
<list>
<value>../dwr/interface/SubFundGroupService.js</value>
<value>../scripts/coa/accountDocument.js</value>
</list>
</property>The ../scripts/chart/accountDocument.js is a JavaScript file that defines the functions onblur_subFundGroup and checkRestrictedStatusCode_Callback. onblur_subFundGroup uses the SubFundGroupService, and to that successfully, DWR needs to create a JavaScript/Java bridge for that access. That's the purpose of the inclusion of the ../dwr/interface/SubFundGroupService.js file: it's not a real JavaScript file at all, but instead a bridge created on the fly by DWR.
Maintainable fields can then trip off the AJAX call when certain events happen:
<bean parent="MaintainableFieldDefinition" p:name="subFundGroupCode" p:required="true" p:webUILeaveFieldFunction="onblur_subFundGroup" p:webUILeaveFieldCallbackFunction="checkRestrictedStatusCode_Callback"/>
In the above example, when the user leaves the UI field for the sub-fund group code, the onblur_subFundGroup JavaScript function will be called, and that should populate the name of the sub-fund group in the page under the UI field.