Generator - Generate Web App

The purpose of the Evoke app generator is to convert the easily created application designs (created by the Evoke Designer) into hard IDE content in order to allow custom content to be added to the app, if required, as well as final deployment of the app.
This content may then be generated and deployed as Web Apps, Hybrid Apps or Native Apps. The complete Visual Studio and/or VS-Xamarin projects enable onward development in a native environment using all the power and versatility of Visual Studio (and VS-Xamarin) as required. In doing so, the developer is given the best of both worlds - quick and easy application construction along with unrestricted enhancement and customization capabilities.

The Generator Profile allows you to select from different profiles that define which database which respoitory objects (files) are associated with. You can add as many generator profiles as you need to define different options for your app.
New Evoke apps have a default generator profile provided for you as standard (or a starting point), this is called Profile1 and the name can be changed or more profiles added if you wish to map other databases to Entities or files in Evoke.


You can generate your App Design into a Visual Studio project simply by clicking the big green "Start Code Generation" button, but first you must ensure you have set up the Visual Studio settings and the Entity mappings.

Web Apps
Code Generation
In the Code Generation section you are able to select the .NET environment for the app that you are generating:
  • .Net Classic - allows the resultant web app can be hosted in a Windows enviroment.

  • .Net Core - allows the resultant web app can be hosted in a Linux enviroment.

There is also the checkbox option Supress backup. When Evoke generates the app Visual Studio code from your app design it overwrites the previous Visual Studio generated code except for the special customisation files previously generated.
As part of this process Evoke creates a backup copy of the entire Visual Studio solution before beginning to overwrite any files, this is so that if the generation fails to complete for any reason then the Visual Studio solution is reverted back to the state it was in prior to the generation starting and the backup copy removed.

There are several reasons that you may not want this backup copy taken such as a) disk space restrictions b) not having full read/write/delete permissions on that file folder in Windows Explorer, etc. in this case you can select the "Supress backup" option before a code generation and the backup copy will not be take. Consequently, if the generation fails for any reason then the Visual Studio solution will not be restored to its previous state.



Visual Studio settings
Before generating a Web App, you will need to set the Visual Studio settings in Evoke. Default values are provided, however, you can set:
  • Root NameSpace - the name that you wish to give your Visual Studio solution

  • Target Folder - the location, on your computer, where the actual folders containing the Visual Studio solution and projects will be created/stored. Web and repository Folders will be created in this location.

  • Clear Target Folder - Evoke preserves any customisation that you have added to Visual Studio each time you generate the App. However, there may be times that you wish to clear all customisation automatically when you generate the app.

  • launch VS on Completion - Evoke can automatically open and load up the App project in Visual Studio so that no Visual Studio actions (other than the build) are required.




Entity Mappings

The Entity Mapping section of the Evoke generate web apps area lists all the Entities that you have included in your app design. It then allows you to select a repository (database) against each of these to all Evoke to "map" to the correct file in the correct database.

Generate Repository CRUD

Repository CRUD (Create, Read, Update, Delete) code is only required to be generated for MultiValue Datbases. If you are using a SQL database that this selection can be ignored.

One of the main purposes of the generated .NET code is to invoke the relevant DataBASIC subroutines residing on your MultiValue database server. The specific server-side routine that is called and the data that is passed to it depends entirely upon the type of repository related action that has occurred within the UI. The app generator can create the initial content of these server-side routines (known as CRUD routines - Create, Read, Update and Delete) and you are then able to add your own code as necessary in order to implement the required database file access logic. The app generator, when instructed, will install the CRUD routines into a file called EVOKE.CRUD.BP, please also review the instructions for creating this program file. The naming and content of these CRUD routines is based on the data entities created within the app designer. Each data entity will be represented by 2 routines called EV.CRUD.xxx and EV.CRUD.xxx.CUSTOM, where xxx represents the name of the data entity. The EV.CRUD.xxx routine is "owned" by the app generator, that is, you should not amend its content. Conversely, the EV.CRUD.xxx.CUSTOM routine (referred to hereafter as the "custom CRUD routine" is "owned" by you, and will only be modified by the generator once - i.e. when it is first created by the generator. The structure of each custom CRUD routine is covered in the following section.
The generated DataBASIC CRUD routine

When you ask the app generator to install the CRUD routines, as mentioned previously, it will create 2 subroutines per data entity. The routine named EV.CRUD.xxx (where xxx represents the name of the data entity) contains code which can be viewed as the default implementation of each of the possible CRUD actions. The second routine installed by the generator, EV.CRUD.xxx.CUSTOM, allows you to, where relevant/necessary, override these default implementations by incorporating your own DataBASIC code. The default implementation of each CRUD action within the EV.CRUD.xxx subroutine is based on the data entity mapping definition set up within the app generator. Please refer to the App Generator User Guide document for more details on this topic. This mapping data, in essence, defines a logical structure for the "blob" of entity data that passes between .NET and DataBASIC. The knowledge of this structure by both .NET and DataBASIC is obviously crucial because it is the only way in which these 2 environments can successfully synchronize their individual elements of data exchange logic. Thus, the default implementation of each CRUD action within DataBASIC is based on the assumption that each entity maps onto a single database file, and that the structure of this file is exactly the same as the app generator's mapping definition blob described above. This may be true for some entities, but probably not true for many others. In this latter case you will need to override the default implementation of CRUD actions with your own code within the CUSTOM version of the CRUD routines. Sometimes it is useful to look at the generated CRUD routine in order to look at an example of how some of the calling signature arguments can/should be used.
A simple example of customising the Evoke generated CRUD code is provided here however, the BlueFinity support team will be happy to assist further.




Generate App

In the Web App section of Evoke you can click the "Start Code Generation" and Evoke will validate your entire App project, displaying both warnings and hard errors that it finds, and then generate an entire Visual Studio Solution.




Visual Studio

When generating your app you have created two folders (Repository and Web) on your local computer at the path entered in the "target folder" in your visual studio setting section.
Open Visual Studio and selection the open solution option (or if you have selected "launch VS on completion" in the Visual Studio settings section then it will have automatically opened Visual Studio and your Evove App solution).
When you have opened the app solution (the *.sln file in the Web Folder that you have just generated) you will need to "rebuild" under the Build menu (see image right) and you can then run your app (see image below).