Walkthrough - Auto Code Designers
This walkthrough guide explains how to create the following simple entities in the system using our auto-code designers:
- Country: A simple entity holding the following properties:
- ISO Code
- Description
- Policy: A simple entity holding references to existing entities, and a country (to show how custom entities are the same as system ones), along with a property validation
- Name
- Description
- CurrencyID
- CountryID
- Price
You can follow along to this walkthrough with our video too:
Designers
For this walkthrough we will be using our auto-code designers which allow you to design entities, and views, in the system without writing any code. Everything you design is a real part of the system, indistinguishable from system entities such as Users.
The designers use our API to create your entities in the same way we do when designing anything for the platform. Thus they don't have the traditional problems associated with "configured user-data", or other "hack" type approaches; poor performance, not audited, hard to report on, different restrictions, no security, etc.
Instead they use our API which mean everything you design automatically integrates with our security, reporting, canvas technology, auditing, etc. The system creates real tables in the database for your entities including auditing, and security tables, and upgrades the web service to allow your entity to be queried the same as any other.
Most configuration tools, or designers, in other products are essentially black boxes preventing your configuration from being truly portable, understanding how they work, or being able to enhance their functionality beyond what the tool allows. Because our designer actually uses our API to create everything you design, in the same way a developer would, it can always export what you've designed into actual .net code for you to use with our API. With this you gain visibility, portability, and remove all restrictions preventing you from achieving 100% of what you require.
Tip
You can always take the code from the designer, tweak it to what you desire, and drop it back into the product as an AddIn. As such you can also follow along with this walkthrough via our API Developer Documentation - Designing Entities In The LemonEdge Platform, which steps through building the above entities from scratch using code, and shows how you arrive with the same code from our designers, and then illustrates how to extend that.
Designing Entities
To design our entities we start by opening our Custom Entities Designer.
Countries
To create our Country entity, we are going to create a New Custom Object, and provide it the following properties:
| Property | Value | Note |
|---|---|---|
| Name | Country | This should be unique throughout your application |
| Collection Name | Countries | This should be unique throughout your application. The system also auto-populates this value from the Name you provide initially |
| Table Name | CE_Countries | This should be unique throughout your application. The system prefixes every table created by a custom entity with CE_. All system entities are prefixed with LT_. This is to ensure you do not have clashes with tables names when designing your own entities. |
| Load Dynamically | True | This indicates we want this entity to be loaded into the system all the time. If we just want the designer to provide us code, we can set this to false and the system will not load this design. You can take the code, tweak it, drop it back into the product as an AddIn and it will load it then. |
| Is Standing Data | True | Indicates this should be loaded into the client side cache |
| Is Inheritable | False | We don't want other entities to inherit from this |
| Is Root Of Entity Set | False | We Don't need this to be exportable as an xml config file |
| Has Permissions | False | We don't care about anyone editing this entity type for just now |
| Inherits Type | None | |
| Extends Type | None | |
| Description |
This defines our actually entity, but what we really need to describe is the properties we are going to store against our entity. We can do that by creating a new Custom Object Property for each of the properties on our Country; ISO Code and Description.
As you're creating these properties you'll notice the selections basically mirror the definition of the type of data you're storing in a way it can be created in sql correctly. So for these properties we're defining the actual column name that will store the data in the database table, the sql column type, the property name (which is the name to access this data on our class and in the system, typically mirrors the column name but doesn't have to), along with column length, precision and scale.
For both ISO Code, and Description we're saying they have a Column Type of nvarchar sql types, the system automatically selects a Property Type of string to represent that on the entity, and that they have a Column Max Length of 500 and 2500 respectively.
Note
This means the system knows precisely how to create these columns in the back end sql database table as nvarchar(500) and nvarchar(2500) columns. If we leave the Column Max Length as empty then that would create a column of nvarchar(max). From here you can see that however you actually want to store data in the database you can configure that here along with the Property Type it will map to as a .net core type on our entity in the system (in this case a string).
In order for the system to correctly be able to import data you need to make sure that at least one property you define is marked with [Is Part Of Key] as being true. All columns marked with this are used as the key to identify a record during imports, and are verified as being unique in the system. As such we mark the ISOCode as being part of the key.
An entity can be referred to in multiple places throughout the system, such as in the tab when opened/editing an entity, in a control when being selected as a relationship, or in trees/grids and other areas. By selecting a property as being used for the label of this control the user will always see that when this entity is being referred to. For this entity we're selecting the Description as the label so the user sees the user friendly description of the entity, instead of the code.
That's it. Saving that will provide a popup prompting if you want to "Commit The Changes To The Database".
This will upgrade the database, and web service (if you're connected through one), with the tables to support your new entity. We don't need to do that just yet, we can do it once we've finished the Policy entity.
Policies
To create our Policy entity, we are going to create a New Custom Object, similar to the country one. This time we're going to give it a Name of Policy, Collection Name of Policies, and a Table Name of CE_Policies (both done automatically for you), and mark it as Load Dynamically as well.
Again, that's all that's required to define the entity, now we need to describe all the properties for our policy by creating a new Custom Object Property for each of the properties on our Policy; Price, CountryID, CurrencyID, Description, and Name, like so:
| Property | Attributes |
|---|---|
| Price | Column Name: Price Column Type: Decimal Property Name: Price Property Type: Decimal Precision: 12 Scale: 3 |
| CountryID | Column Name: CountryID Column Type: UniqueIdentifier Property Name: CountryID Property Type: Guid Link To Type: Countries Link To Type Property Name: ID |
| Currency ID | Column Name: CurrencyID Column Type: UniqueIdentifier Property Name: CurrencyID Property Type: Guid Link To Type: Currencies Link To Type Property Name: ID |
| Description | Column Name: Description Column Type: nvarchar Property Name: Description Property Type: String Max Length: 2500 |
| Name | Column Name: Name Column Type: nvarchar Property Name: Name Property Type: String Max Length: 500 Is Part Of Key: True Is Label: True |
Important
The key additions here are we used Custom Entity Property Link View to define the relationships for the Country and Currency properties, where we indicated they link to the Countries (which we just created prior), and Currencies entities respectively.
This highlights how Countries are now an integral part of the system just like everything else. Because they are created through the API, all the capabilities the platform provides to entities are available automatically to Countries and Policies.
This includes being linked to in relationships, being fully audited, security, reporting, canvases, etc.
Next we want to add some custom validation to the price. We can do that by highlighting that property and selecting the Validation Formula command. We can then enter a formula of:
MyItem.Price > 1000
Likewise we can select the command Validation Message and enter a user friendly message of:
Must be greater than 1k.
Tip
This will ensure that a policy with a price less than or equal to 1000 will be invalid and the user will be presented with our "Must be greater than 1k." message through whichever means they are trying to commit this save (popup box in client applications, importing, api, etc. The validation can not be bypassed).
Obviously this is a very simple validation, but the formula engine is capable of any functionality even running custom queries to interrogate the data in the system. The editor provides available functions depending on the context, and you can even add multi-line c# script for advanced configuration.
That's it.
In the space of minutes we've created two entirely new entities in the platform that have a relationship to each other and system entities.
Tip
When you save your policy you can select "Commit The Changes To The Database" and the system will automatically upgrade your database to manage countries and policies.
Caution
Note: You will see the progress of this task appear in the top right of your application. If it is not being processed you may not have the Task Service running. If you are directly connected to the database (instead of via a webservice), you can launch it locally by clicking on your login name on the top right to bring the user menu drop down and select Launch Task Service. This will prompt for a log file location and then run the service and process your task.
Designing Views
To design our entities we start by opening our Custom Grids Designer.
Countries
To create our Country entity, we are going to create a New Custom Grid, and provide it the following properties:
| Property | Value | Note |
|---|---|---|
| Entity Type | Countries | This is the type of entity we are creating a grid for. Here we can select from all the entities, including our custom and any AddIn loaded ones, as they are all the same part of the product. |
| Load Dynamically | True | This indicates we want this grid to be loaded into the system all the time. If we just want the designer to provide us code, we can set this to false and the system will not load this design. You can take the code, tweak it, drop it back into the product as an AddIn and it will load it then. |
| Name | Countries | This should be unique throughout your application |
| Replace System View | This we are leaving blank, but this is also where we have the ability to override the standard system views with our own ones. | |
| Description |
This defines our actually grid for countries, but what we really need to describe is the columns we are going to have in the grid. We can do that by creating a new Custom Grid Column for each of the properties on our Country; ISO Code and Description.
Tip
It's as simple as selecting the property we want as a column (in this case ISO Code and Description) along with stating if we want them to be visible and editable by default. In this case true for both.
That's it. The system will automatically handle creating the columns with the appropriate controls/etc.
We now have a grid of countries we can easily interact with allowing full sorting, grouping, filtering, paging, searching, exporting/importing, editing and of course it functioning across all the LemonEdge applications on Windows, Macs, Linux, and Tablet/Mobile too.
Note
You'll notice you can select the system columns for the grid as well such as LastUpdated, Canvas and ModifiedBy. You don't need to add these columns, though you can if you wish, as they are automatically added to every grid by the system anyway, but are just initially hidden. This way the user can easily select those columns to be visible to see who last modified any data, and so forth.
Policies
Grid
To create our Policy grid, we are going to create a New Custom Grid, similar to the country one. This time we're going to give it an Entity Type of Policies, Name of Policies, and mark it as Load Dynamically as well.
Again, that's all that's required to define the grid itself, now we need to describe all the columns for our policy by creating a new Custom Grid Column for two of the properties on our Policy; Name and Price. We do that in the same way we did with Countries by simply selecting them as columns.
We're not adding all the columns to the grid (although you can if you want), as we're going to create an actual view for editing a policy when a user opens a policy from the grid itself.
Note
By default the Countries grid does not automatically open the country when creating a new one, as we marked the entity as being Standing Data. By default standing data is just viewed in grid form, as it's supposed to be simple data for caching. We can override this, and create a single view for editing countries, but there is little point as it can be done from the grid. In contrast an entity that isn't standing data by default will open in a new tab when we create a new item in the grid. Again we can override and suppress this behavior, but for our purposes here we're going to create a single policy view instead.
Policy View
To create our Policy single view, we are going to create a new Custom View, and select an Entity Type of Policies, a Name of Policy, and mark it as Load Dynamically as well.
Tip
Similar to the grid we can also replace standard system views for entities with any we can custom design here by using the Replace System View property.
In order to create the controls in this view we are going to create a new Custom View Control for every property we want to see/edit on this view. In our case we're going to add all 5 properties of our Policy as controls on the view; Name, Description, CurrencyID, CountryID, and Price.
We can do this in the same way for adding columns to a grid, by simply selecting the properties we want to appear as controls, and whether they are initially visible/editable. The system takes care of creating the appropriate controls and ensuring it displays correctly across our applications, console, web browser app, or however it is viewed.
Note
We also have extra options here specifying the height, width of the view and controls to further tailor how the view appears in the UI. By default controls wrap horizontally, but we can override this making them appear stacked, or even in a custom grid layout. Leaving Width/Height as 0 will ensure they are automatically handled by the system to have the default correct size.
Lastly we can give the Price control a format of "n3" so it can be displayed correctly in the UI. You can see here for more information around formatting.
Role Menu Items
Now we have created our country and policy entities, along with country/policy grids and a policy view, we need a way to open a grid of countries/policies in the application.
We can do that by adding a button to a role we want to give that functionality to, which we can find by going to Roles.
Important
By default the system has two "System" roles; Standard User, and Admin. You don't want to change these roles as your changes are just automatically overwritten by the system on every upgrade anyway. These hold the default system functionality for an Admin and User.
If you have a role you can edit you can use that, if not you can just select the "Standard User" and select the command "Copy Role" which will create a copy of the standard role that we can modify instead.
With our role we want to go to the menu edit view and select the command "Add Item" in the place we want to add our command button to. Then we want to select an Item Command of Entities Grid and update its Item Name to Countries.
Note
If you have been following the Designing UIs Developer API Walkthrough there is a section on how to easily create your own menu command buttons. If you've done that you can just select that type of button as the Item Command instead of the Entities Grid. It will then of course execute whatever your command is.
We can use the command Alter Image to alter the graphic used for the menu command to any image we like.
Lastly we want to use the Custom Properties command and select a Collection Type of Countries. Depending on the command you choose some have custom properties and others do not.
This creates a button which will load a collection of Countries for us. As we've only defined one Countries grid the system will just use that automatically as the layout to present to the user to view all the countries. If we had multiple grids, or other graphs/charts/views/etc we wanted to show as well we can create a custom layout (here) that would be used instead.
Likewise we can do the same for Policies by adding a new command button again with an Item Command of Entities Grid, Name of Policies, and a Custom Property for Collection Type of Policies.
You can save that and hit refresh all to load in your new role. Once reloaded you can switch your current role to the modified role and you should see your new Countries and Policies button on the main menu and be able to completely interact with your created countries and policies.
Tip
It's that simple!
You can now create, edit, view countries and policies from the main menu on your role. All the filtering, grouping, sorting, searching, etc is all working for you out of the box. Likewise these entities seamlessly work with canvases, auditing, security, reporting, and importing as you can see in the walkthrough video above.
Of course being a platform you can now export the entities/views you've built into actual c# code, further tweak it to 100% of what you require with custom algorithms/etc, and import that back into the product as a full AddIn. Never again are you hitting the limits of the configuration tools your legacy product provides.