AppThena - Customising Your Application

This document is an index of the different approaches that you can use to customise and extend an AppThena application. It assumes that you have already installed AppThena and you can navigate through the objects in your database and modify them at will.

The Application Configuration File


WEB-INF/classes/appthena.xml

AppThena monitors this file and applies any changes automatically when its modified.

Changing Security Settings

By default, AppThena requires that users log in to use the application but it doesn't require them to use a secure connection.

If you don't require users to log in then you can disable logins by editing the WEB-INF/web.xml file. Just comment out the entire security-constraint element with the display-name of "All Resources Security Constraint".

If you want users to log in then you should force them to use a secure connection. i.e. HTTPS. This ensures that their passwords are encrypted by the browser before being sent to AppThena.

Enabling HTTPS is a two step process. First of all, you must obtain a security certificate for your domain and install it in the web server. Please see your web server's documentation for instructions on this step. Secondly, you must tell AppThena to demand secure logins by editing the WEB-INF/web.xml file. To do this, change the security-constraint with the display-name of "All Resources Security Constraint" so that the transport-guarantee element is CONFIDENTIAL. Set this value back to NONE if you don't require HTTPS.

Branding Your Application

The name of the application appears in the title of every page. It is taken directly from the display-name element in the application's WEB-INF/web.xml file. You may need to restart the application if you change this value.

You can change the colour scheme by editing the cascading style sheets in the CSS directory in the web application.

If you want to change the page template to add logos, copyright notices etc you should edit the .JSP files in the root of the application. These files are used by all the types in your application, so changing a handful of JSPs re-brands the entire application.

Changing the Way a Type and Its Properties are Displayed

You can change the way that AppThena displays a type quite considerably by editing the application configuration file.

To modify a type, you must create a type element under hints/types. We won't describe the element in detail here as it is documented in the configuration file. However, you can make the following changes to your type:

  • hide the type completely
  • make the type read only
  • tell the system that the type is used as a link table in a many-to-many relationship
  • change the type's display name
  • change the default sort order for collections of this type
  • change the order in which the type's properties are displayed

You can make similar changes to the type's properties. Specifically:

  • hide a property completely
  • make a property read only
  • change the property's display name
  • specify the width of the property when it's displayed in a confined space such as a table

Changing the Standard Actions

An Action is a plugin for the Controller that responds to a page request. AppThena ships with a set of standard actions that perform the most fundamental operations on your objects. e.g. create, edit, delete, search.

You can change the way that AppThena treats the standard actions by editing the application configuration file.

The plugins/actions element contains a list of the Actions that are registered. Each action element tells AppThena about a single Action. If you edit these entries you can change the following:

  • change the name of the action in the GUI
  • remove the action from the system completely
  • add a new action
  • replace the class that carries out the action
  • change the actions view JSP
  • restrict the action to certain types or read-only objects
  • decide which Action buttons will be displayed by this Action's view

The last point needs a little explanation. The standard AppThena views display Action buttons next to each object whenever they are allowed. The action entry in the configuration file tells it which actions are allowed. For example, the standard EDIT action has the following action element.

      <action name="EDIT" display-name="Edit" view="/edit.jsp" submit="false"
        class="com.glasspaw.appthena.controller.action.impl.SimpleObjectAction">
        <allowed-by read-only="false" classes="com.glasspaw.appthena.info.ObjectInfo" />
        <allowed-actions>
          <allowed-action context="page" actions="SEARCH, BLANK, UPDATE, DELETE"/>
          <allowed-action context="list" actions="BLANK, SEARCH, EDIT, DELETE"/>
        </allowed-actions>
      </action>

The allowed-by element tells the system that an object cannot have an Edit button unless it implements com.glasspaw.appthena.info.ObjectInfo. This means that it doesn't apply to search results or type objects. If you wanted to, you could add a types attribute to this element and restrict the action to a list of data types.

The allowed-actions element tells the system which actions the view (edit.jsp) should consider displaying when it builds a page. If you removed the DELETE action from these entries then the users wouldn't see Delete buttons on any of the Edit pages.

Adding a New Action

If you need a add new Action to the system then you just create a class which implements the Action interface and register it in the configuration file. For example, you could create an Action to copy an object or to display a report.

As far as AppThena is concerned there's no difference between the standard actions and ones that you create. They are configured and handled in exactly the same way. Just add your new action to the application configuration file and AppThena will include it in the user interface.

See the section above for information about adding the action to the configuration file. See the javadoc for the Action interface for more information about creating an action class.

Adding Business Logic to a Type with an ObjectEventHandler

The Model triggers events every time it does something with an object. You can create an event handler to respond to these events by implementing ObjectEventHandler and registering your new class in the application configuration file.

ObjectEventHandlers are an excellent way to implement business rules that are specific to a particular type. This is the sort of code that goes in the "business object layer" of a more traditional architecture. For example, you can check that an object's properties are valid before it's saved and return the user to the edit or new screen if it isn't. You could also check to see if a user is authorised to view an object before loading it, or update an audit trail every time an object is modified.

Once you've created your event handler class you must register it in the application configuration file by adding an object-event-handlers/object-event-handler element. You can register the event handler for all types by omitting the type attribute. If you want to apply the event handler to just a few types then you should register it once for each type.

One of the great advantages of using event handlers instead of business objects is that you don't have to create an event handler unless you need one. This reduces the amount of work needed to introduce and maintain types.

Adding Business Logic to the Controller with an ActionEventHandler

The Controller triggers events before and after it asks an Action to handle a request. You can use these events to perform action-related business logic such as logging requests, authenticating users or redirecting the output of an action to a different view.

For more information see the ActionEventHandler and ObjectActionEventHandler interfaces.

You must register event handlers in the application configuration file before they will take effect. You can register the handler with all actions or just specific ones. For more information see the comments on the plugins/action-event-handlers section of the configuration file.

Adding a Custom View

You can create views from scratch using JSP if necessary. This allows you to create a view for a custom action, use a custom page to display a particular type or to re-design the user interface completely.

If you want to use your view as the default for a certain action then you need to modify the Action's "view" attribute in the application configuration file.

The simplest way to use different views with the same action is to create an ActionEventHandler that works out which view to use and calls ActionEventHandlerContext.setView() to tell the Controller which view to use.