Entities

Entities, in Evoke, are the data structures (data objects) used by the User Interface that you define in your App. A description of how Entities relate to your physical database and also data sources is available in the basics of Evoke.
New Entities can be added using the ellipsis ("...") menu at the top of the entities list and new Entity definitions can be automatically imported if required. Entities, once created, can also be exported to automatically create the same structure in your physical database (Repository).
Each entity is sub-divided into Properties and Entities and Properties may be linked to data/fields in your backend database or used only in the App UI.
There are four tabs of information, that relate to each Entity, in this section:
Reserved Entities
Each Evoke App has three (3) reserved Entities that cannot be deleted and must be mapped to a database. These are the AppUser, AppUserGroup and Classification Entities. Details of these reserved Entities and how they are mapped may be found in the Reserved Entities section of this User Guide.

General
The General Tab of a new Entity, imported Entity or existing Entity contains the following information and options regarding each Entity:
  • Singular Name - Required Field - used in the generation of the App and when custom code is required to be added to the Visual Studio project by the developer. Usually this contains a singular version of the Entity name

  • Collective Name - Required Field - used in the generation of the App and when custom code is required to be added to the Visual Studio project by the developer. Usually this contains a plural version of the Entity name or the Entity name with list on the end of it

  • Description - a free format description of the Entity (recommended but not required)

  • Notes - a free format field for notes and further descriptions of the Entity (not required)

  • UI-Only Usage - Is the Entity mapped to a physical database table/file in the backend database or is it just an Entity that will be used solely in the UI of the App for data presentation or data manipulation?

  • Initialized Remotely - If ticked then when a new instance of the entity is created then a round trip to the middle tier is invoked to populate some initial values into the new instance.

  • Partial offline enabled - Used with native apps. If Partial Offline is enabled in the generator settings then ticking is option will ensure that this entity is included in the entities that can be held offline.


Properties
Each Entity is made up of Properties.
These Properties relate to either the physical fields in your database table/file/object (linked in Data Mappings) or are defined as "UI only" Properties and therefore only used in the app UI and not mapped to a physical database field.

UI only properties may be Calculated Properties, temporary UI only fields or a translation of physical database field. Properties can also hold a key or list of keys into another file (Entity) to link/Join reocrds together.

The Properties Tab contains the following information and options regarding each Property:
  • Name - Required Field - contains the chosen name for the Property

  • Description - a free format description of the Property (recommended but not required)

  • Notes - a free format field for notes and further descriptions of the Entity (not required)

  • Data Type - a required field specifying the data type of the property from the following list of drop down options:

  • AlphaNumeric

  • Boolean

  • Currency

  • Date

  • DateTime

  • Decimal

 

 

 

 

 

 








  • Cascade Deletes - If the parent record then the child records associated with it are deleted e.g. sub entities.

  • Holds a list of Values - Is the property a list of multiple values/other entities or a single value.

  • Value is calculated - The property is an Evoke Calculated Property

  • UI-Only Usage - Is the Entity mapped to a physical database table/file in the backend database or is it just an Entity that will be used solely in the UI of the App for data presentation or data manipulation?

  • Validated Remotely - If ticked then when the property is amended a round trip to the middle tier is invoked to validate (in custom code) the new value in the property.

  • Is required - when an instance of the entity is saved if this field is ticked then an automatic check is made to ensure the field id populated and an error displayed if it is not.

  • Two further options are available for "AlphaNumeric" Properties: Mask and Mask Type. These provide UI reformating of alphnumeric values and are explained further here.

As a property can have a data type of Entity you can create inter-related or associated entities. A Related Entity is a list or singular version of another entity related to this entity.
If you specify a data type of "Entity" for a property then two further property details are displayed and required:
  • Relationship type - Non Required Field - used ito identify that the relationship with the sub entity is a) owner of b) owned by c) is associated with

  • Related Entity - Required Field - select from the drop down list the Entity that you would like included as a related entity to this property

When you have related Entities then the Evoke Entity Browser can be useful in visualising all the inter-relationships of Entities.

Calculated Properties
Entity Properties can also be set to be "Calculated" and when this checkbox is checked you are given the option of defining the calculation for the property. The Example App/App Design provide multiple examples of the use of Calculated properties. A very common use for this would be a database that has a first name field and a surname field, these would be properties in Evoke (linked to the database fields in data mappings) and then a further "User Interface Only" Property would be defined that is "calculated" as Firstname + Space + Surname
However, there are many other uses for Calculated Properties and Properties can can be calculated using one or more of the following types:
  • Arithmetic Expression - calculates a numeric value based on 2 or more Properties using "sum", "divide", "multiply" or calculate the "difference" of all the values in the Properties provided. Evoke will offer all the possible numeric Properties available e.g. Currency, Integer, Decimal, etc. You can select two values for the divide option; as many of the values as required for the sum or multiplication options; and add a sequence for the "difference" option by either selecting the options in a certain order or changing the sequence number.

  • Casing Conversion - this alters the case of a specified Alpha property value e.g. a name could be set to a) all lower case, b) First Letter Of All Words Is Uppercased or c) All Upper Case.

  • Collection Expression - this allows for a collection (multiple) properties to be a) averaged b) concatinated c) counted to return the number of values d) return the Highest of all the values e) return the lowest of all the values or f) summed. Evoke will ask you to select a source property , this will be a list of Entities (e.g. sales), then you select the related property, for example the sales price, which can be any property designated as a Currency, Integer, Decimal, etc numeric property.

  • Concatinate Properties - this allows multiple values to be concatinated (joined), in any order you specify, with or without a) separators (as for the Full Name giving in the example above) b) changing the the case (as above) and c) being trimmed (removing initial, trailing or intermediate spaces).

  • Custom Code - this will add software "hooks" to allow you to simply and easily add some specific custom code into your Visual Studio project to calculate the value of the Property

  • Javascript - this allows a Javascript expression to be entered into Evoke that calculates the value of the Property

  • String Expression - formats the string based on the expression specified. Allows you to join together several property values. The "Add to String expression" adds the selected property to the string expression being built e.g. {propertyname1}*in*({propertyCountry1}) could result in Paul*in*(USA).

  • Value Conversion

    This will convert a value. The conversion options are based on the property type e.g a date can be converted to a) the day of the specified date b) the day of the week c) the full date d) the full year e) the ISO date f) the long date g) the month h) the month name i) a short date or j) just the year. Time can similarly be converted to various time formats.
    An Alphanumeric property can be converted with "field extract" - this allows you to extract the first part of a property, up to a field separator, into one property and the second part of a field into another (the field index is 0 for the first part and 1 for the second, etc). There is an example of this in the image on the right.
    Numeric - this allows zeros to be converted to blanks and blanks to be converted to zeros.

Calculated entity property
An entity property that is flagged as being calculated has its own dedicated builder page. This allows the you to identify which property values are required to identify the related entity instance(s). If only one property is included in the "to be used" list and the entity property is not a list then a checkbox at the foot of the list allows you to specify if the specified property supplies the complete primary key/item ID of the related data item. The key feature of a calculated entity property is that if any of its dependency property values change, the appropriate data retrieval action will be triggered automatically. Further information regarding use of this feature and how to manage your database structures should be reviewed at Calculated Entity Builder.

There is additional user information regarding The Calculated Properties Builder that should be reviewed.


Entity Selections
When the Entities are used to structure Data Sources, these Data Sources will often need to be populated with data from the back end databases. In order to do this the App (created by Evoke) will, depending on the database selected, invoke "Selections" or call some Stored Procedures.
Against each Entity you can identify the different Selections that you may want to use within your App (in the Page Series Section) and define any parameters that you might want to pass to these.
The selections are further defined in Data Mappings and a description of using selections to populate data sources is described here.


Data Validation
You are able to specify any data validation that you wish to be performed on the Entity property. For example, if an entry field is mandatory then you simply check the "is required" checkbox for the property. You can also select "remote validation" that will add software "hooks" to allow you to simply and easily add some specific validation into your Visual Studio project if you wish.

Classifications
It is probable that you will want some of your Properties to be populated by the App User selecting from a drop-down list of options. In Evoke these are "Classifications". Classifications are defined in the Evoke Classifications menu option and each Classification group is populated either from a) a Classification table in your backend database b) via a selection from multiple tables in your backend database or c) a fixed list that you define in your database.


Entity Browser
When you have a property in an entity that is itself an entity (a related entity) then properties can cascade through entities. To help visualise these inter-relationships Evoke has an Entity browser.

As shown in the image on the right, the Evoke entity browser allows you to click on a property and see up to 3 entities and their respective inter-relationships.

In addition to related entities you are also able to see the classifications and and single properties of the entities browsed.

the top of each column shows the entity name and if it is the parent of child to the related entity.



Importing Entities
You can manually create you Entity definitions or alternatively you can import the Entity Definitions from the physical object/file structure in the Repositories area.

AlphaNumeric Properties Masking
Two Additional options on AlphaNumeric Properties only provide for display field masking/reformating of the display of an AlphaNumeric property (field) in an Entity:
  • Mask type
    A property can be assigned a display/input mask (pick from drop down menu on option) which will be used to format the display of the property's data value. There are 2 options at present: None - No mask will be applied; Display - the supplied mask will be used to format the display of the property's value but this formatting will be temporarily suspended when the user is editing the value.

  • Mask
    This allows a mask definition to be supplied. A mask definition comprises a series of space-separated character group patterns, each of which describes either a literal string to be inserted into the property value or the definition of what format a series of characters within the property value should be.
    For example, to format a phone number of 01234123456 into (01234) 123 456 you would enter a mask definition of ( 5n ) s 3n s 3n - note spaces between formatting are important and MUST be included.
    In the above mask, the open and close brackets represent literal data to be inserted before and after the first 5 digits within the phone number; the "5n" means "5 numeric characters". The 2 "s" group patterns indicate that a space needs to be inserted after the close round bracket and after the next group of 3 digits.
    The full range of options available in a mask are:

    • s = insert a space character

    • z n = insert z numeric characters from the current position within the property value

    • z a = insert z alphabetic characters from the current position within the property value

    • z l = insert z lower cased alphabetic characters from the current position within the property value

    • z u = insert z upper cased alphabetic characters from the current position within the property value

    • z x = insert z characters (any type) from the current position within the property value

    • any other value is assumed to be a literal string to into the property value at the specified position