Helium DevClient Generate Feature

Introduction

The Helium DevClient includes a generate feature aimed at creating the scaffolding structures when developing new features. Currently it is focused on established projects and generates the framework for new views, CRUD elements or controllers. There are two features which are likely more applicable to new projects and plans for adding features that will generate an entire folder structure for a brand new project.

The premise of the generate features are to quickly generate a structure for development, but to do this in a way that does not clutter the project while also leaving the responsibility and final say in the hands of the developer. While the features will generate views/presenters/controllers that will build and deploy without issue, it is strongly advised that developers review the generated code to ensure it is suited to their specific case and requirements. Importantly the reviewed and improved version of the generate features will only be available in release version 1.28. There are several things that developers should note and be aware of when using the generate features.

Project Backup

The DevClient creates a backup of the entire project once any generate feature is used and before any new code is generated. This is stored under the same parent directory as the project and is there if developers need to revert to an older version of the code. This is not used for anything else, so it can be removed without implications to the project.

Generated Folders

All of the generate features will create a 'generated' folder in the applicable project tree folder and add the newly generated files to this folder. This makes it easy to find these generated files and update them accordingly. To keep the project uncluttered, every use of any generate feature clears this folder completely before creating the corresponding new files. This means that after generating some code, the developer is responsible for reviewing that code and then move the file out of the 'generated' folder once they are happy and intend to keep the file. While the DevClient ensures presenters/controllers aren't overwritten and a unit name isn't used twice, developers should also take care to review the code and files generated for duplication or similar issues.

Lang Translations

When generating a new view or a CRUD module (which includes a new view) generic 'en.lang' entries are made for the generated view elements. These should obviously be reviewed by the developer and update them to more applicable translations. Keeping the translations uncluttered however, is more challenging as the project can only contain one 'en.lang' file. To handle this, the DevClient creates an 'add.input' file alongside the 'en.lang' file. This file is used as a reference for the DevClient to check which translations can be removed when clearing the project of generated code. This means that once a developer is satisfied with their translations, they have to add it to the 'add.input' file to ensure it is not removed when using any generate feature again. Unfortunately this extends to all translations in the 'en.lang' file and not only the generated entries, so be sure to copy review the translations before and after using a generate feature.

Generate Default

he-dev> generate default

This method is used to create several general features that can be used throughout the application, but will likely only be used with new projects. It creates:

1. A non-persistent 'MenuItem' object as follows -

   object MenuItem{
   	int sortnum;
   	string description;
   	int val;
   	datetime tstamp;
   	DSL_VIEWS navigationDestination;
   }

   This object can be used in tables to create summary tables, or navigation menu's within a Helium menu item.

   A controller is also created for this 'MenuItem' object in the 'utilities/generated' directory.
2. A 'Logger' unit under 'utilities/generated/logging' which contains a generic logging function and can be used throughout the app.
3. An 'Alert' unit under 'utilities/generated' which contains a few useful functions to easily create simple alerts that can be used throughout the app.
4. A 'PrimitiveValidation' unit under 'utilities/generated' which contains a single string validation that ensures the parameter isn't null or empty. This unit can obviously also house any app specific validations creating a centralised unit for logic-based validations.

5. A persistent 'ScheduledEventLog' object as follows -

   persistent object ScheduledEventLog{
   	string functionName;
   	string outcome;
   	datetime startDatetime;
   	datetime endDatetime;
   }

   This object makes an in-app log that can be used to monitor scheduled functions with app-specific logic. Along with this object, a controller is created under 'utilities/generated/logging' as well as a view and presenter to monitor these logs. Importantly the view created here does not assign a role to the Helium 'menuitem' element so developers will have to update this after running this command.

NOTE: Considering the default Helium '__scheduled_function_result__' table as well as DSL native SQL functionality, this last object is likely unnecessary but it is ultimately up to developer discretion on the use and inclusion of any of the generated files and code.

Generate Invite

he-dev> generate invite

This method creates an 'InviteUsers' unit in the 'services/generated/invite_users' directory and adds an '@InviteUser' annotated function for every model object in the project with an '@Role' annotation. It uses the generic number '27000000000' for what it estimates/guesses is the mobile number attribute.

unit InviteUsers;

@InviteUser
SystemAdmin inviteSystemAdmin(){
	SystemAdmin systemadmin_var = SystemAdmin:new();
	systemadmin_var.firstName = "firstName";
	systemadmin_var.lastName = "lastName";
	systemadmin_var.mobileNumber = "27000000000";
	systemadmin_var.emailAddress = "default.emailaddress@mezzanineware.com";
	systemadmin_var.save();
	return systemadmin_var;
}

Therefore it is important for developers to review this unit after generating it to ensure the mobile number is updated to the correct one in order for the '@InviteUser' annotation to work correctly.

Generate New View

he-dev> generate new-view <view name>

As this feature will likely be used fairly often, it was updated to be independent from other features and provide an effective structure for developers to work from. It takes a 'view name' as a parameter included in the command and creates a view and presenter for that name. Ideally this provides the structure of these files in order to save developers from mistyping the view tags or having to copy and paste entire views. After running the command, the DevClient will ask whether a 'menuitem' element should be created. If 'yes' it will follow up with asking which role should be used for the 'menuitem'. This is used as entered by the developer so it should reflect the '@Role' annotation exactly. Navigation to and from the view is not included and developers are responsible for ensuring these views are accessible in the application.

Generate Controller

he-dev> generate controller <model name>

This method takes a model object and creates a controller with several general functions, including CRUD functions, in the 'utilities/generated' directory. If the parameter model name isn't found in the project's model, the controller isn't created.

NOTE: no validation is added to these CRUD functions and developers are therefore responsible for adding their own validation to these controllers.

Generate CRUD

he-dev> generate crud <model name>

This method uses a combination of both the new view and controller methods. It creates a controller for the model with the same code as with the controller method, but it also creates a CRUD view and presenter that has corresponding input elements to the model object's attributes. It can be used as generated to create/update/delete objects for the corresponding model. Similarly it doesn't create anything if the model parameter doesn't exist.

NOTE: no validation is added to these CRUD functions and developers are therefore responsible for adding their own validation to these controllers.

Generate Clear

he-dev> generate clear

This method just clears the generated files and folders as with any other generate method, but without creating any other file or folder. This also affects the translation entries.

Upcoming work

The following tickets are planned maintenance to add and improve the generate feature.

HE-7423: Generate Improvements