Tips
UI Presentation Tips
Adding a simple page
To add a new presentation page in the application, you can use the
Dynamo code generator.
The web page is an XHTML file created under the web
directory.
The page name can contain a directory that will be created if necessary.
The new web page can be configured to use a given layout.
The layout file must exist to be used. The default layout is layout
.
You can create a new layout with add-layout
command.
You can also write your layout by adding an XHTML file in the directory:
web/WEB-INF/layouts
To create the new web page web/todo/list.xhtml
, you will use:
dynamo add-page todo/list
Depending on your application configuration and the URL used by the new
page, you may have to add or modify a url-policy
. By default, if
the new URL does not match an existing url-policy
, the access will
be denied for security reasons. To allow anonymous users to access
the page, use the following url-policy
:
<url-policy>
<permission>anonymous</permission>
<url-pattern>/todo/list.html</url-pattern>
</url-policy>
and if you want only logged users, use the following:
<url-policy>
<permission>logged-user</permission>
<url-pattern>/todo/list.html</url-pattern>
</url-policy>
Note: make sure to replace the .xhtml
extension by .html
.
Add Open Graph
Use a combination of fn:trim
, fn:substring
and util:escapeJavaScript
to create the Open Graph description. The first two functions will remove
spaces at begining and end of the description and will truncate the string.
The util:escapeJavaScript
is then necessary to make a value HTML attribute
when the description contains special characters.
<meta property="og:description"
content="#{util:escapeJavaScript(fn:substring(fn:trim(post.description),1,128))}"/>
Formatting dates
A date can easily be formatted by following the Java Server Faces patterns
by using the f:convertDateTime
converter. The pattern attribute controls
how the date is formated and it takes into account the locale used to render
the request. For example:
<h:outputText value="#{event.member.payment_date}">
<f:convertDateTime pattern="%A %d %B %Y"/>
</h:outputText>
Sometimes, the date must be formatted within an attribute of some HTML
element. In that case, the h:outputText
cannot be used but instead
we can use the util:formatDate
EL function. For example:
date="#{util:formatDate(post.date,'%Y-%m-%d')}"
Configuration Tips
Adding a permission on user creation
Sometimes it is useful to add some permission when a user is created.
This can be done programatically but also through some simple configuration.
By using the on-event
XML definition, it is possible to create a set of
permissions when the user-create
event is posted, hence during user creation.
The following XML extract from Atlas demonstrator will add several Wiki permissions to the new user.
<on-event name="user-create">
<action>#{permission.create}</action>
<property name="entity_type">awa_wiki_space</property>
<property name="entity_id">1</property>
<property name="workspace_id">1</property>
<property name="permission">wiki-page-create,wiki-page-update,wiki-page-delete,wiki-page-view,wiki-space-delete,wiki-space-update</property>
</on-event>
Secure configuration
Setting up the secure configuration is made by using a secure keystore with the akt
tool.
The secure configuration is stored in the keystore file that akt
will protect by encrypting each
configuration property with their own encryption key. In order to setup and use the secure configuration
the following steps are necessary:
- Create the keystore file and protect it with a password or a GPG key,
- Populate the keystore file with the configuration values,
- Launch the server with specific options in order to use and access the keystore file.
The two initial steps are done by using the akt
tool.
To create the keystore file, one way is to run the akt
command and give
it the keystore password:
mkdir secure
akt create --wallet-key-file=secure/wallet.key -c 100000:300000 \
secure/config.akt
This will generate the secure/wallet.key
file and setup the keystore file
in secure/config.akt
. The password must be given to the server when it is
started. To avoid that, it is possible to store it in a file and make sure
the file is protected against read and write access. If the password is
stored in such file, the keystore is created by using:
akt create --wallet-key-file=secure/wallet.key \
--passfile=secure/master.key -c 100000:300000 \
secure/config.akt
Once the keystore is created, the configuration are inserted. Because the server
command can use only one keystore and have several applications, the configuration
parameter must be prefixed by the application name. For example, to setup the
database
configuration for the atlas
application, you will use the command:
akt set --wallet-key-file=secure/wallet.key \
--passfile=secure/master.key \
secure/config.akt \
atlas.database 'mysql://localhost:3306/atlas?user=atlas&password=PiX2ShaimohW6eno
To avoid having to specify several configuration parameters when launching the server,
it is good practice to create a server global configuration file and indicate
several parameters that the server will use. Create a file secure/config.properties
that contains:
keystore-path=secure/config.akt
keystore-masterkey-path=secure/master.key
keystore-password-path=secure/password.key
Then, to start the server we just need to give it the server global configuration path:
bin/atlas-server -c secure/config.properties start
Note that in order to use this configuration setup, the directory must have
the rwx------
rights and files must have the rw-------
rights.
Overriding some AWA navigation rules
AWA and its modules are using Ada Server Faces for the presentation pages and
navigation. The navigation rule describes what is the next page to render when
a form is submitted. In some cases, the default navigation rules provided by
AWA or some of its module may not fit your application needs. You can override
them by creating an application override XML file that you configure to load
after the awa.xml
configuration file. For example, to override the default
redirection used after a login, you can use the following XML file:
<?xml version='1.0' encoding='UTF-8'?>
<module version="1.0">
<navigation-rule>
<from-view-id>/auth/login.xhtml</from-view-id>
<navigation-case>
<from-outcome>success</from-outcome>
<to-view-id>/index.xhtml</to-view-id>
<redirect/>
</navigation-case>
</navigation-rule>
</module>
and then configure the app.config
property to define the list of XML
configuration file to load. Each name must be separated by ;
.
For example:
app.config=awa.xml;app-override.xml
Trouble shotting Tips
No AWA service context
When the AWA framework emits the following error:
ERROR - AWA.Services.Contexts - : No AWA service context: may be a 'filter-mapping' is missing to activate the 'service' filter in the request path
it is often followed by a Constraint Error
such as:
CONSTRAINT_ERROR: awa-services-contexts.adb:53 access check failed
and it is caused by an application that uses the AWA.Services.Contexts.Current
operation
on an incoming request but there is no AWA service context. In most cases, the root cause
is that a servlet filter is missing in the configuration for the current URL request.
You may add such servlet filter by using the configuration:
<filter-mapping>
<filter-name>service</filter-name>
<url-pattern>/*.html</url-pattern>
</filter-mapping>
and replace the /*.html
pattern by the URL that caused the error.