Customizing GUI appearance

Owned by Marcin Kubala (Unlicensed)
Last updated: Jul 01, 2013Version comment
2 min read

You can override some Qcadoo Framework resources (such as images, CSS)  without need to modify them by adding plugin with new version of given resource inside the same relative path as in qcadoo-view.

I recommend placing all resource's overridings in one separate plugin to avoid of time-consuming searching for appearance modifications in whole application or accidental overriding your previous changes.

As long as we do not have any impact on the order of loading JAR archives' resources under Tomcat (http://issues.qcadoo.org/browse/QCADOO-352) and the default order based on their (JARs) names there is need to give your GUI-customizing plugin name that will be lexicographically smaller than 'qcadoo-view'.

I. Overriding resources

For example: We want to replace logo seen at top left corner.

All we need to do is:

  1. Create (arbitrary named) plugin for UI customizations (if such plugin does not already exists in your application)

    Note that you do not need to specify an <view:resource /> element in qcadoo-plugin.xml for resources which you override. They are already registered in qcadoo-view plugin.

  2. Find relative path of resource which you want to replace with your own.
    In our case this is /qcadooView/public/css/core/images/logo_small.png.

  3. Put new resource in src/main/resources/<relative path obtained in step 2>. 
    For example: src/main/resources/qcadooView/public/css/core/images/logo_small.png

Be aware that path contains plugin identifier of the original resource owner (in above example - qcadooView), not plugin in which you placing new version (for example appNameCustomLook)!

II. Adding custom CSS rules

Qcadoo Framework allow you to appending additional CSS rules without need to overriding whole existing CSS file since we provide empty qcadooView/public/css/custom.css in version 1.2.0.
You can appending additional rules instead of replacing whole CSS sheets just by override custom.css (see previous section).

III. Telling your application about GUI customizations

Tomcat

Tomcat doesn't require any additional modifications. You can also change existing application's appearance without need of redeploying them by putting appropriate customization plugin (see step 1 in 1st section of this document) in webapps/ROOT/WEB-INF/lib directory, and restarting application.

Jetty

If you running application on Jetty (which is quite reasonable choice if you want to test some GUI modifications outside production environment without need of restarting application) you have to register customization plugin's resources directory in ResourceCollection.
It may sound complicated but all you need to do is open *-application/pom.xml and find lines like below in maven-jetty-plugin plugin build configuration:

<webAppConfig>
	<contextPath>/</contextPath>
	<baseResource implementation="org.mortbay.resource.ResourceCollection">
		<resourcesAsCSV>
			${basedir}/src/main/webapp;
			${basedir}/../../qcadoo/qcadoo-view/src/main/resources;
			${basedir}/../../qcadoo/qcadoo-report/src/main/resources;
			${basedir}/../../qcadoo/qcadoo-plugins-plugin-management/src/main/resources;
			<!-- some other entries -->
		</resourcesAsCSV>
	</baseResource>
</webAppConfig>

And append path to customization plugin's src/main/resources direcotory above (before) ${basedir}/../../qcadoo/qcadoo-view/src/main/resources; (line 6)

List of resources paths are given in the CSV format which uses semicolon as a separator of items. Do not forgot to put a ';' at the end of line.

For better illustrate let's look at example: I want to run application on Jetty with customization plugin named 'qcadoo-custom-look' and placed inside mes-plugins/ directory, so I prepend ${basedir}/../mes-plugins/qcadoo-custom-look/src/main/resources; to jetty's resources list configuration. Now my <webAppConfig> node looks like (new item in line 5):

<webAppConfig>
	<contextPath>/</contextPath>
	<baseResource implementation="org.mortbay.resource.ResourceCollection">
		<resourcesAsCSV>
			${basedir}/../mes-plugins/qcadoo-custom-look/src/main/resources;

			${basedir}/src/main/webapp;
			${basedir}/../../qcadoo/qcadoo-view/src/main/resources;
			${basedir}/../../qcadoo/qcadoo-report/src/main/resources;
			${basedir}/../../qcadoo/qcadoo-plugins-plugin-management/src/main/resources;
			<!-- some other entries -->
		</resourcesAsCSV>
	</baseResource>
</webAppConfig>