As an example for this tutorial, we will create a Car Repair Shop application. The following diagram shows the entities model and the user roles that we need.
To further stimulate your imagination, the following screen shows what the generated Service Orders page would look like for a Customer Advisor user. You see that every Order has a Customer and a Vehicle assigned and has an Order Status. Also, there are buttons for each order to manage Service Tasks and to view, edit and delete orders. Another button is available to attach documents (like invoices) to an order.
Additionally, the above screen shows some general features, which generjee will create for you: User login and logout, multi language support, and data export to Excel, PDF, and CSV. Furthermore, the entries will be shown within a customizable table, which lets you search, sort, and paginate the data.
You can see this example application live on OpenShift. Please take a look on car-repairshop.rhcloud.com. (Unfortunately, it sometimes is down because it is a free limited account.) Use the credentials user="usermanager" and password="password" to login. Then start with User Management, create a test user account and use it to explore the Car Repair Shop example.
Click here to start the generjee tool. It will open in a new browser window.
You will see the start screen where you can set some general options for the application you want to be generated. Your first action now is to change the application name to "Car Repair Shop" and replace the predefined package name with "com.repairshop.example".
We need to add a role "Customer Advisor". To create it, click the + button. Then click on the name of the new role and change it to "Customer Advisor".
Repeat these steps and create another role "Mechanic".
The settings should now look like this:
Now we are ready to create the entities. Click on the button "Add Entity". Note that a new button appears, named "New entity 1" and the page for configuration of the new entity is opened automatically.
Change the entity name to "Customer".
Then click the + Button in the fields area. A new entry will be created in the fields table. Click on the name "New Field 1" and rename it to "First Name". We need this field type as a String which is already set by default.
When you click on the pencil in the table row, there will be some more options for this field on the right side of the fields table (or below it if you use a smaller screen resolution). These additional options belong to the currently selected field and depend on the field type.
The first additional option you see is "Required". It defines whether this field must be entered by the user or if it may be left empty. Because we don't need First Name to be mandatory, leave this option unchecked.
The 2nd option is the maximum length of the String values. You can keep the default value.
Now let's look at the checkbox "Show in Table". Our generated application will have a table for each entity, which lists the entries and lets the user complete the actions he is permitted to. When you uncheck the option "Show in Table Overview", you define that a field must not be displayed in the overview table, but only in the detail dialogs. Use this option if an entity has a lot of fields, and you want to prevent the table from becoming oversized. Because we want the first name to be displayed on the overview page, leave the option "Show in Table" selected.
Now compare this screen with your settings to see if you entered all the values correctly:
Create another field and call it "Last Name". It must have the same options as the First Name. Additionally, check the Option "This is the lookup field". This means, that this field will be shown as the identifier for a customer, if the customer is referenced by another entity. For example, in the Service Orders table, the column Customer will show the Last Name value:
A lookup field must must not be empty, of course. So select the "Required" option for the Last Name field. In the generjee Preview, every entity can have only one lookup field which must be of type String. If there is no lookup field for an entity, the database ID will be shown for lookup purposes.
At last, create three other fields, all of type String with default options. Name them "Address", "City" and "Phone":
Now we only have to set the user permissions, and then we have completed the customer entity. Set the selections of the Authorization Matrix as shown in the following screen:
Now create the "Vehicle" entity and add the following fields to it:
| Name | Type | Required | Length | Show in Table | Is lookup field |
|---|---|---|---|---|---|
| License Plate | String | yes | 20 | yes | yes |
| Manufacturer | String | no | 50 | yes | no |
| Model | String | no | 50 | yes | no |
| Year of Manufacture | Number | no | 4 | yes |
Copy the permissions for Vehicle exactly from the Customer entity.
Now create the entity "Service Order" and don't change it, yet. We will come back to it later.
Then create the "Service Task" entity and add these fields:
| Name | Type | Required | Length | Show in Table | Is lookup field |
|---|---|---|---|---|---|
| Name | String | yes | 20 | yes | yes |
| Description | String | no | 250 | yes | no |
Set the following permission values for the Service Task entity. Note that we allow the Service Task entries to be read by public users.
For the last entity, add "Order Status". It has only one field named "Status". Mark this field as required, show-in-table, and this-is-the-lookup-field. Leave the field length at the default value. Also, leave the authorization matrix at its default values (only the Administrator has the permissions).
Now the excitement builds. We want to create relationships between our entities. Open the Service Order entity, add a field and name it "Vehicle". The type of this field is "Reference". Check the field details and set the Target entity to "Vehicle" and the Reference type to "n:1". That means, each order can have one vehicle assigned to it, but a certain vehicle can be used in multiple orders. Keep the other options as they are.
The next step is to create a relationship to the Customer entity. Follow the same steps as for Vehicle. The field name and the target entity must both be "Customer".
Then create a reference to Service Task. Name the field "Task" and set a n:m reference to the target entity Service Task.
Next add the field "Repair Date" (Type Date) and "Price" (Type Decimal). Keep the other options of these two fields at the default values.
Now we need another n:1 reference to the entity Order Status. Just enter "Status" for the entity name.
As the last step, we will set the authorization. Please select these permissions:
