XDAT uses Apache Turbine to manage its web architecture. Turbine supports the use of Actions and Screens to manage the flow of web requests. The majority of screens are auto-generated for you. However, you may want to build some custom screens and actions to facilitate new features.
Actions are written as Java classes and must be located in the org.apache.turbine.app.PROJECT_NAME.modules.actions package. The classes can extend the org.nrg.xdat.turbine.modules.actions.SecureAction class to make use of the XDAT security model. Action processing goes in the doPerform(data,context) method. As an action completes, it should be directed to a screen for user response. Custom created actions and screens can be accessed through the standard Turbine mechanisms or can be tied into XDAT’s site management system.
In order to tie new features into the XDAT site, you can create custom screens and reference them using the data type ‘element actions’ in the administration section. Doing this will create a link in the actions box on all reports for the specified data type. In the administration section, go to the ‘Data Types’ listing. Click on the Data Type which you would like to edit. This brings up the report for the specified data type. From here you can access the edit page which lists the current ‘element actions’ for this data type and allows for the insertion of new ones. The name of the action must map to the name of your custom screen using the XDATScreen naming convention.
XDATScreen Naming Convention
The report page ‘action’ links generated by adding data type ‘element actions’, link to the org.nrg.xdat.turbine.modules.actions.XDATActionRouter class defined in the XDAT jar. This jar will use the name of the element action and data type name to pass processing to the proper velocity screen. All custom screens which map to an element action must begin with the ‘XDATScreen_’ header. The XDATActionRouter will look for a screen which is named using the header, the sql name of the data type, and the element action name (‘XDATScreen_’ + sql_name + ‘’ + element_action_name). If this screen is not found, then it will look for a screen named using the header and the element action name (‘XDATScreen’ + element_action_name). If this screen, is not found then an error is thrown.
If you are creating a custom screen which will be linked to from the actions box, you should either name it “‘XDATScreen_’ + sql_name + ‘’ + element_action_name” or “‘XDATScreen’ + element_action_name”. (case-sensitive) Using the second convention will allow the screen to be accessed by any data type which has the corresponding element action. The first convention will only be accessible by the defined data type.
Element Action Attributes
Element Actions are accessible from the ‘Data Type’ report or edit page and affect the links which are available in report pages. There are several attributes which can be set for a given element action. (These can also be customized from the Admin menu.)
- Name: This is the name which will be used in the Action link and must be used in the screen file’s naming convention.
- Display Name: This is the text which will be displayed in the ANCHOR tag on the report page in the Actions box.
- Image: This is the name of an image file (located in the src/images directory) which will be displayed with the Display Name text.
- Popup: Specifies whether or not the Action link should generate a new window or not. If it’s blank (or ‘never’), then the link will never produce a popup. If it’s ‘sometimes’, then the link will produce a new window if the report page itself is not a popup page, otherwise it will not popup a new window (Useful to prevent popup proliferation). If it’s ‘always’, then the link will always generate a new window.
- Secure Access: This will be used to decide whether or not a user has permission to access this action for a particular instance of a data type. It uses the data type permissions defined in the Admin User page (‘edit’, ’read’, ’create’, or ’delete’). If the user does not have permission for the corresponding access type, then no link will show up on the report.
- Additional Parameters: This text will be appended to the request url which is sent to the screen.
- Sequence: Governs the ordering of the element action links in the Actions box on a report page.
Customizing Edit Forms
Data Entry forms are generated by the setup or update scripts. They are placed in the PROJECT_NAME/src/xdat-templates directory and are named ‘XDATScreen_edit_’ + data type sql name. These generated edit templates contain every possible field and may need customization for active use. To customize the edit forms, copy them into the PROJECT_NAME/src/templates directory and modify the files as desired.
To modify the preliminary java processing for the screen (if necessary), copy the appropriate org.nrg.xdat.turbine.modules.screens class to the org.apache.turbine.app.PROJECT_NAME.modules.screens package. Add your customized java code to the finalProcessing method and change the package name to reflect the new package location.