Sdk212.CustomProject

How to create a custom project

This guide explains how to create a custom project for openCRX. A custom project allows to extend the customizing delivered with the standard distribution of openCRX by adding and modifying

  • Headers, footers and logos
  • Groovy-based controls
  • Code tables
  • Wizards
  • Reports
  • Backend extensions
  • Model and database extensions
  • Custom WARs

A custom project allows to separate the directory structure of the openCRX distribution and the custom-specific files.

This guide assumes that the openCRX SDK is installed (also see here).

Checkout and build the sample custom project

openCRX SDK comes with a sample custom project. Follow the steps below to install and build it.

Build for Linux

In a first step open a shell and cd to a directory where you have installed openCRX SDK (see here for more information).

cd /tmp/dev
./setenv.sh

Then checkout and build the sample project.

git clone ssh://<user>@git.code.sf.net/p/opencrx/opencrx2-custom-git opencrx2-custom
cd opencrx2-custom
cd opt
ant install-opt
cd ..
cd sample
ant all

Build for Windows

In a first step open a shell and cd to a directory where you have installed openCRX SDK (see here for more information).

cd \temp\dev
setenv.bat

Then checkout and build the sample project.

git clone ssh://<user>@git.code.sf.net/p/opencrx/opencrx2-custom-git opencrx2-custom
cd opencrx2-custom
cd opt
ant install-opt
cd ..
cd sample
ant all

Verify project structure

After successfully building the project the directory structure looks as shown below.

  • jre-1.6/sample/deployment-units: custom-specific EARs
  • jre-1.6/sample/lib: custom-specific JARs
  • sample/etc/deployment-unit: custom web application.
  • sample/build.properties: allows to customize project-specific properties
  • sample/build.xml: custom-specific Ant build.xml
  • sample/src/data/org.opencrx.sample: contains the custom-specific UI extensions. You have to put the custom-specific files such for ui, codes, reports, wizards, etc. in these directories. They are added to the WAR. A very important file is the ./WEB-INF/web.xml which contains the configuration of all servlets.
  • sample/src/java: custom-specific backend
  • sample/src/ear: custom-specific deployment descriptors
  • sample/src/model: custom-specific model extension

Import the Eclipse projects

Import the Eclipse projects which come with the sample project:
sample/.project: openCRX 2 Custom ~ Sample (jre-1.6) sample/src/model/emf/.project: openCRX 2 Custom ~ Sample (EMF)
* sample/src/model/papyrus/.project: openCRX 2 Custom ~ Sample (Papyrus)

MyWebApp

MyWebApp shows how to add a custom-specific web application to openCRX. MyWebApp is developed with Google Web Toolkit (GWT).

Unzip MyWebApp.zip to a directory of your choice. Open a shell and switch to this directory. Before you can build the project we have to adapt build.xml. Open build.xml with a text editor and adapt the following variables to your environment:

<!-- Configure path to GWT SDK -->
<property name="gwt.sdk" location="/opt/gwt-2.5.1" />
<property name="openmdx.sdk" location="/tmp/SF/opencrxSdk-2.12.0/opt/openmdx-2.12.7/jre-1.6/core/lib" />
<property name="opencrx.sdk" location="/tmp/SF/opencrxSdk-2.12.0/opencrx-2.12.0/jre-1.6/core/lib" />

Now build the project with ant war. Copy the resulting MyWebApp.war to the directory sample/etc/deployment-unit and build the sample EAR with ant assemble.

MyWebApp.war is now part of the resulting opencrx-core-CRX.ear. The web module is registered in application.xml (see src/ear/opencrx-core-CRX.ear/META-INF).

The class com.mycompany.mywebapp.server.GreetingServiceImpl shows how a GWT service accesses the openCRX backend. Deploy the EAR and lauch MyWebApp with the URL http://localhost:8080/mywebapp.

Store

The Store application shows how to build a stand-alone web application which uses openCRX as backend.
After running ant all you will find in jre-1.6/sample/deployment-units the file opencrx-sample-store.war.
You can deploy this WAR to any application server instance. E.g. deploy to the webapps directory of your
current Tomcat instance. In order to be able to connect to your openCRX Server instance, check the
following entries in the ./sample/src/war/opencrx-sample-store.war/WEB-INF/web.xml:

<context-param>
    <param-name>url</param-name>
    <param-value>http://127.0.0.1:8080/opencrx-rest-CRX/</param-value>
</context-param>
<context-param>
    <param-name>userName</param-name>
    <param-value>admin-Standard</param-value>
</context-param>
<context-param>
    <param-name>password</param-name>
    <param-value>admin-Standard</param-value>
</context-param>

Adapt the parameter values according to your environment and run ant assemble again after having made modifications.

The Store application comes with some sample data which you can load with the standard openCRX GUI:

  • Login as segment administrator (e.g. admin-Standard).
  • On the user's home select File > Import and import the file sample/src/war/opencrx-sample-store.war/data/uoms.xml.
  • Next import the file sample/src/war/opencrx-sample-store.war/data/products.xml.
  • Now launch the Store application with http://localhost:8080/opencrx-sample-store/Store.jsp. Adapt host and
    port according to your environment.

You then get the start screen as shown below:

If you want to build your own web application and use openCRX as backend it should be straight-forward
to use the Store application as template and adapt it to your use-cases and GUI frameworks.

Model extension

openCRX follows a Model Driven Software Development (MDSD) approach. Hence, many openCRX artifacts (API,
XML schemas, persistence mappings and classes, etc.) are the derived from the model. I.e. they are generated
at build-time by model mapping tools provided by the underlying MDA framework
openMDX (see here for more information). As a consequence, the openCRX Core model
must be extended in case new attributes or operations are to be added to the API, GUI, or database. In order
to get a basic understanding of the MDSD approach it is a good idea to read the following documents:

The sample project comes with a simple model extension. In Eclipse open the Papyrus model by opening
openCRX 2 Custom ~ Sample (Papyrus)/models.di. Then select the diagram named org.opencrx.sample.account1-Main. It should look as shown below:

The sample project extends the openCRX Core model by the following elements:

  • Class org:opencrx:sample:account1:MyContact: MyContact extends the class org:opencrx:kernel:account1:Contact
    from openCRX/Core. It adds the and adds the multi-valued attribute hobby.
  • Class org:opencrx:sample:account1:Gadget: Gadget extends the classes org:opencrx:kernel:base:Note,
    org:opencrx:kernel:base:SecureObject, org:opencrx:kernel:base:Auditee, and org:openmdx:base:BasicObject.
    All attributes are inherited.
  • Association org:opencrx:sample:account1:MyContactOwnsGadget: the composite association allows to add 0..n gadgets
    to a MyContact.

Next steps

  • If you want to rename the project sample by your own name, e.g. myname then you have to adapt build.xml, build.properties and the directory name containing the data files in src/data
  • If you want to learn more about UI customizing then see here for more information

Congratulations

You have successfully created your first openCRX custom project.


Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks