One of the most powerful things about designing Apps using Evoke is that you are not limited to the extensive range of functions in Evoke. If you have a specific unique requirement, some existing code in your application that you want to re-use or wish to write something unique to add to your app that is not part of the standard Evoke Low-Code App design product - you can!

It is really easy to customise your app design and the customisation is preserved through each re-generation of your app design. So you can design using Evoke, add some unique custom code, continue to design in Evoke and the custom code is not only preserved but will be in your regenerated app.

This section addresses the basics of app design customisation. It is separated into different sections, for ease of reading, and covers how you write or re-use code in different scenarios. For all (SQL and MutliValue database based) apps customisation can be performed in the Generated Visual Studio solution and for MultiValue DataBase based apps customisation can also be performed in the MultiValue DataBasic CRUD layer.
This section can only provide a summary of the cusomtisation options available to you and additional details may be found in the Working with Evoke Generated Visual Studio projects manual.

The Evoke app generator will always create a Visual Studio project called "xxx Web", where xxx is the name of your app. This project contains generated code relating to the implementation of a RESTful web service. This project, in turn, references the RepositoryAccess project in order to interact with back-end repositories.

Customisation in the UI

Customising in the User Interface of your app is done in JavaScript. this can involve anything from changing how something looks to performing additional functions when a widget is accessed (button clicked, item displayed, etc).

In the Visual Studio solution, generated by Evoke, you will find two projects (Repository Access and Web).

The Web project also contains all content relating to the app's UI for HTML based platforms. This content is organized under 3 top-level folders, collectively termed the main content folders:

• CSS Holds all CSS code files used within the app
• Scripts Holds all JavaScript code files used within the app
• Views Holds all HTML files used within the app
• These is also an Images folder which holds all of the images used within the app

In the Web projects (see image right) in each the of "top level" folders (lets take the Scripts folder as an example) - each folder has a "_Generated" folder. This is regenerated each time you generate your app design, so do not add any customisation to the files in this folder as it will be overwritten/removed the next time you generate your app.

You will also find a folder with code hooks that can be customised, in the Scripts folder this is called Pages. In here you can find a file for each Evoke Page Series in your app.

As the image on the right shows, in each Page file, you can find the custom code entry points for each Page Series object (a full explaination of this can be found in the manual at the top of this page) - for example:

• initialize: function (self) { } - This function is called when the page series is first loaded into memory at the start of app execution. At the point when this function is called the DOM will be fully loaded and the internal JavaScript structure of the page will exist.
• activated: function (self) { } - This function is called when the page series is made the currently displayed series (usually when the end-user selects a menu option).
• generalLogic: container/namespace object { } - This object acts as a container for you to place logic which applies to the page series as a whole.

You can add custom javascript code into any of these areas to be executed at that time i.e.:
You might add to the General Logic code hook as follows:
generalLogic: {
ExampleCustom: function () { alert("Custom Code Here"); }
},

Customisation in the Database (Middle Tier)

This section is currently under construction. Until it is completed shortly please refer to the manual reference in the header above

Integrating Library Components

There are literally thousands of third party library components you can link into your app. The manual at the top of this page describes this process in more detail. Lets take for example sending an email. You can use the Evoke Click actions to launch the default email client on a device and let the user type in there email, but there are times when you will want to automatically create an email and send it regardless of if the user has and email client on their device or not. In this case you would use a third party emailer, i.e. MailJet (but others are available for you to review and select - this is just an example that we are using).

In this case you would need to first signup to and create a MailJet Account (or whatever other emailer you choose to use). Link in the Mailjet API and call it.
.... This section is currently under construction. Until it is completed shortly please refer to the manual reference in the header above

Custom Code via the Click Action "Custom Code"

This click action raises event for custom JavaScript to hook into. In the Click Action definition choose the Custom Code Location from a) Page Series - The Routine is held within the custom.generalLogic object of the parent Page Series and b) App - The Routine is held in the App.custom object (in App.js).
Custom Code Routine Name - the name of the custom code routine to be executed.
Please see the Click Action Custom Code description help page.

MultiValue Databases - Calling or integrating existing/new subroutines or Custom Code in Data Basic

DataBasic Repository CRUD (Create, Read, Update, Delete) code is used by MultiValue Databases to provide access to the database and create the Selections that you set up against your Entities.

The Evoke app generator will create the initial content of these server-side routines CRUD routines and install the CRUD routines into a file called EVOKE.CRUD.BP, please also review the instructions for creating this program file.

New CRUD code will be generated by Evoke whenever you check the "Generate Repository CRUD" check box, against any or each Entity in the Generate Web App area.

The naming and content of these CRUD routines is based on the Entities you have created in your App Design. 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.

Whenever you regenerate a CRUD routine you must also compile and catalogue the routine in your database. If you are using a .NET data connector to your database, such as mv.NET, that uses connection pooling then you must remember to STOP any active sessions to your database, in the .NET data connector, whenever you have compiled and catalogued the new CRUD code so the the new BYTE code is re-read into the data connector.



Using new or existing MultiValue DataBasic with your CRUD code
One of the 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.

As described above the Evoke app generator will create the initial content of these server-side CRUD routines and you are then able to add your own code as necessary in order to implement the required database file access logic.

The EV.CRUD.xxx.CUSTOM item, for each Entity, allows you to, where relevant/necessary, override the code, in the EV.CRUD.xxx, which can be viewed as the default implementation of each of the possible CRUD actions, 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. 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.

You can customise the Data Basic (database) Create, Read, Update, Delete, Custom (CRUD) database code easily within an app design. Examples of the customisation you can perform and how may be found in the CRUD custom code help page

MultiValue Databases - CRUD Remote Key Custom Code Example

This is an explanation and example of customisation of the CRUD code required to support Remote Keys for MultiValue Databases in Evoke.

Some other customisation examples - ChatBots

The custom code required for adding Chatbots to an Evoke app design may be found in the Chatbot custom code help page

Some other customisation examples - PayPal

The PayPal payment button raises an event for custom JavaScript to hook into. This section of the Evoke User Guide help system will guide you through including your custom code.

First you must identify the location, in your Visual Studio solution to put the PayPal code. This is in the Web project and is the Scripts folder and then the Pages folder. Here you will find a file called "Pages.YourPageSeriesName" - where YourPageSeriesName is the Page Series, in your app design, that holds the Page with the PayPal button. Note: this is the PageSeries that holds the Page not the Page. Please see Visual Sudio solutions explorer example on the left.

Within this file you need to identify the exact place to put your custom code.
The Routine is held within the custom.generalLogic object of the file (search generalLogic in the file if you cannot find it).

The Evoke "Example" app has an example of the Code that must be added (as described in the document above), while this is just an example the code we added to the Pages.Shopping.js in the Web/Scripts/Pages folder may be usefule for you to re-use. The Exact code we used is shown on the right.

A text file of this code may be downloaded from this link.