Evoke Data Sources

Data Sources are the areas in your app (app design) that are used by the User Interface of your app to hold and manipulate data items/records.

Other sections of this user help have identified how Evoke assists with connecting your physical database, where your Tables/Objects are, to your app in Repositories.

We also reviewed how data structures (similar to record/item definitions) are set up in Entities to identify which fields in your data items/records you will use in your app and any other fields, that may not be in your database items/records, you wish to use in the app.

The Data Mappings section identified how the "fields" identified in your app design Entity that are also in your physical database (Repository) are linked (Mapped) so that records/items can read, created, updated, etc.

Data Sources are areas, held within the UI of the app, that can be populated with data, from your database (Repository) using Selections and then displayed, updated or manipulated in the app UI.

Data Sources

Data Sources in Evoke are used by the app UI, as such they are generally defined in the Page Series area of Evoke and are local to the Pages in the Page Series. However, there are two types of Data Source:

Data Sources that are local to a Page Series and are most commonly used in app designs.
Global Data Sources that are available throughout the App not just in the Page Series that they are defined in. Global Data Sources are defined and described in the App Settings General DataSource section.

Data Sources are usually defined in the Page Series main page (please see image below right). However, you can also review and define Data Sources by accessing the same area from the Data Sources tab in each Page Design screen.

You can create as many separate Data Sources (also referred to as root datasources) within each Page Series as you would like or need.

As can be seen on the image on the right you define each Data Source as follows:

Name - Give your data Source a free format descriptive name to use within the App Design, within the Pages of the App.
Entity Type - The structure of the Data Source (sometimes referred to as the shape of the adat area). Pick one of the Entities that you have previously set up.
Collection - Will this Data Source contain one singular data item/record or will it be a collection of multiple (one or more) data items/records. You do not need to define how many records, just tick this box if it will be a multi-entity (multi record/item) Data Source e.g. to hold data to display in a datagrid/table, etc. Data Sources can be singular (a single instance of the Entity structure or a single record) or a Collection (multiple instances of the Entity structure or a group of records) as defined by this checkbox.
Auto Save - The Auto Saved checkbox option defines if a Data Source is connected to the automatic save/cancel buttons in the App. If this is ticked then when the Data Source is changed the tick (commit/save to physical database) and cross (reject/discard changes) options automatically are displayed. So, you need to decide, for this data Source, do you want this Data Source to participate in the Evoke automatic save (back to database) or cancel changes functions that display the tick/cross (save/cancel) options when any data changes in the Data Source.
Initialize - The initialize option sets the datasource to be a "blank version" or "proper instance" of the object, making it able to hold data, have data assigned to it, etc. As opposed to a "structure only" version or "Empty instance" that cannot hold or manipulate any data. An "Empty instance" is overwritten with a "proper instance" when a selection or read is used to populate the datasource.
Data Paging - providing the ability to deliver data to desktop and mobile devices in one roundtrip or as a series of pages.

So Data Sources are defined and set up by you in your app design. You can have as many as you would like and they are structured by the Entities. They are used by the App Pages and Evoke Click Actions in the App.
Data (records/items) from your database (respoitory)is populated in the Data Source, via a selection, and can then be read, changed/manipulated, deleted, new records created, etc. prior to Evoke writing it back to the physical database when the Data Source is saved.

Using Root Data Sources

Data Sources are the means by which in memory data (in the App) is bound onto visible data (within the UI). Data Sources are the place where Repository (database) Data is retrieved and stored for use by the App and the returned (saved) to the Repository (database).

Data Sources are populated by Selections or UI widgets that trigger Data Retrieval from the repository (database). Data is returned to the repository from the Data Source by the functions of the App Save/Cancel buttons or UI widgets that trigger Data Saving.

Use the DataSource Build button to populate the name of a DataSource and the path to any Related Data whenever this is required when working on your app design.

Refined Data Sources

Refined Data Sources are an automatic mirror of the Data Source that they are linked to. Linking is achieved by setting a Data Source as a Refined Data Source's Root Data Source.

There are two main purposes of Refined Data Sources, 1) to provide the data populated in the Root Data Source in a different view i.e. Sorted (by setting the Initial Sort Properties to a space separated list of Property names to sort the data by or for reverse order add a minus sign before the property name) or Filtered using the build button and 2) to provide the App user with the option of sorting, searching and filtering data displayed in the App. The options can be turned on, when a refined datasource is used, in the Template General settings section.

If you do not wish to or need to include Evoke search/sort/filter options on a datasource/datagrid in your app then you will not need to create a refined datasource and can leave that section blank.

Use the DataSource Build button to populate the name of a Refined DataSource and the path to any Related Data whenever this is required when working on your app design.

Global Data Sources

Global Data Sources are Data Sources that are available throughout the App not just in the Page Series that they are defined in. Global Data Sources are defined and described in the App Settings General DataSource section.

Use the DataSource Build button to populate the name of a Global DataSource whenever this is required when working on your app design.