Projects with merging - Best Practices

The following best practices are intended to improve application maintenance and upgrades. Initially we will discuss the setup of project files and dependencies and then development best-practices for component naming, etc.

Beyond just the project and metadata structure, Developers should strive to use consistent design patterns. For example, when creating a new Filter and Grid form, it should be consistent with existing Filter/Grid implementations. If it was implemented differently, even though it is functionally the same as other implementations, it has a higher risk of not being supported in future upgrades because Framework would not be aware of that specific usage. When designing a feature, a developer should:

Search the current application UI to find a similar functionality/paradigm. 90% of Project work will be similar to an existing feature. It is critical to maintain this level of consistency in both technical implementation and functionality. Please raise to the Business Analyst when there are functional inconsistencies.
Document new design patterns when a Feature does not match an existing pattern, the new design should be documented and reviewed by the NexJ Architecture group

Project Structure

The best practice for a new project is to set it's base to Finance and mix in <fill in the blanks - also what should the upgrade flag be set to for each mixin?>. If you are creating a functional module, either do the work right in your project and use namespace folders and discussed in Guidelines for Development, or create a new project, set it's module property to an appropriate namespace, and mix it in to your main project.

Guidelines for Development

The amount of customization on a project directly influences the amount of effort need to upgrade the project to a new Service Pack, Hotfix or Platform. While we cannot avoid customization completely, developers can follow certain guidelines to avoid common issues that occur during a merging.

The overall strategy is to build "on top of existing code" as opposed to "in line". The less core code you touch directly will lead to less conflicts and easier merges.

- Limit the amount of customization (e.g. new functions should be added to new library files as opposed to customizing an existing one). - avoid “high-traffic” areas in Components (e.g. adding new attributes to the top of the XML collection)

Use a Project Namespace

A new project namespace should be used for new Components on the project level to isolate custom files. This will avoid colliding with any new Components in an Upgrade. This is can be done by either:

When creating a component via Studio, append “namespaceName:” to the name
Creating a namespace folder in each component folder. (e.g. meta/class/namespaceName)

Parallel Files

For Library files, creating a parallel version of file is a good way to avoid conflicts. A commonly customized library is "client.scm". Instead of adding a new function to that file, create an 'enbd:client.scm' file which will avoid conflicts. This works best for net new functions.

Presentation Layer Components

Forms

- Use the same form for Create and Edit popups.

UIEvents

- New events should be placed in a new file in the project namespace (e.g.meta/uievents/ PROJECT/newFile)

StyleSheets and Rebranding

Each of the below areas are compatible with AFLwith little/no upgrade effort:

Updating of application splash screen and Company Icon.
Color scheme including background color, text, button, row highlighting/selection. Note: Row selection should have similar contrast with NexJ core icons as the default color schemes.
Stylesheets for Mobile/Tablet are independent of Contact application and need to be customized as well.
may need to recommend some additional colors to ENBD's style sheet for purposes of charts, secondary buttons(save vs cancel and dock).
Optional: Report branding, not currently in scope, limited value for report style changes.
AFL Upgrade: afl adopts a color pallet of around 6 colors which will be used within the application.

We Recommend that we do not update the following :

white space and vertical spacing, this will be superseded by future AFL responsive design work.
controls such as calender, date pickers etc. should remain core. These are largely governed by framework.
Font Changes, this will not be something that is easy to modify in classic or AFL. All items straightforward to test, however this item will incur a large amount of testing overhead and may find small issues with captions being truncated and other sizing tweeks as a result.

Business Model Components

Classes

New Attributes and new Events should be added to the top of the collection in the Project. Product will continue to add to the bottom of the collection to avoid conflict.
Add a description to the Class, Attribute or Event. Ensure to prefix the description (e.g. projPrefix:newAttribute).
Append project prefix before the name of new actions of an Events.
If a required attribute is implemented, update the resulting helper function in unittesthelper.scm to ensure un-related test cases still pass. For example, if new attribute “companySize” is mandatory on the Company class, then update the unittest-create-company function so that it populates to a default value.
If a new Class is created, create a related create function in ns:unittesthelper.scm. For example, if a new object AddressGroup is added, then create a function named unittest-create-addressGroup that will retrieve an existing instance or return a new committed instance. Also create a Test Case in the UnitTestHelper.utest for the new function.
In general, do not add new columns to core database tables as we want to encapsulate the core behaviour to minimize conflicts. New attributes to a class should be put together in one extension table.

Enumerations

The typeCode value should include the project prefix. (e.g. SNSNewEnum)

UnitTests

Core Unit Tests should be resilient to any project-level configuration and should not need updating to overcome failures. If it is necessary to customize a Unit Test to correct a failure, please ensure that the issue is logged with the NexJ Product team.
New Test Cases are not to be added to Core Unit Tests. New Unit Test files are to be created based on functional or technical areas. (e.g. ns:Entity, ns:DirectQuery)
Direct creation of objects should be avoided and instead use helper functions found in unittesthelper.scm. This would make the test less volatile for future model changes. For example, don't use Entity'new to create a contact for your test case, instead use unittest-create-contact

For new classes/attributes that are user facing (i.e. appear in the UI or in a Report), always specify a Facet.

Persistence Components

Upgrades

UICompononetSeeder is an XML document that lists all components visible to the UI (as indicated by the “f_ui_component_field” facet. The purpose of the file is to provide a centralized location to indicate the new (and modified) attributes that Product has been introduced in an Upgrade.

Resource Components

Strings

New strings should be placed in a new file in the project namespace (e.g.meta/strings/ PROJECT/newFile)

Libraries

New functions should be placed in a new library file in the project namespace (e.g.meta/libraries/PROJECT/newFile).
All new functions will still need to be namespaced: Therefore, the function name should start with "enbd:"

AFL Upgradability

The AFL framework will introduce a completely new API and implementation for UI-related components (e.g. Forms, Screens). This is targeted for H2 2018. A Classic NexJ Framework to AFL Framework converter will be used to convert the core UI components. This converter tool will support existing core UI patterns, therefore to eliminate AFL upgrade issues, UI customizations should follow Core functionality.

If upgrading to the AFL framework, here are some
- All HTMLLabel code will require a manual conversion
  - Adding new HTML Label should be avoided
- User Defined Filters (UDF) will require a manual conversion
  - Any new UDF being added or UDF's created on a new work-space would require re-work [Same amount of re-work in AFL as the effort required to add one pre-AFL]
- Filter controls (such as Advanced Search on the EntitySearch.form) will not be easily converted
- SchedulePortlet[calendar] changes should be avoided. This work space has been combined into a new control which will not support individual customization's.
- Avoid usage of Optionblocks
- Client side scripting will be more difficult to upgrade. Therefore avoid adding code to the “Script” section of Forms and Screens.

To minimize the amount of upgrade work:
- I) All functional UI decisions and designs to be reviewed by a NexJ BA
- II) All updates to items in the Presentation Layer to be reviewed by a NexJ Developer

All changes to forms/screens should follow current NexJ pattern, if new portlet/forms/screens are created minimize or avoid adding scripts or any of the above mentioned functionalities.

For example,

- If a new work-space is created all the List or Search forms should be on the left side and the Detail information should be on the right pane[Similar to Companies work-space EntityList, EntitySearch and detail design]
- Avoid adding group layout and logic to switch between the layouts
- New grids inside screen portlets should follow NexJ design [Avoid adding filter, UDF's to the Grid. ex., Communication Grid in Companies work space]