Safe Custom Code
Your changes need to follow the guidelines below for your modifications to be preserved permanently. You need to understand them, and to test your code regularly using
ns check $CODE.
The following types of changes are preserved:
- Code in designated custom Locations
- Replacement of designated sections
- Designated "ignored" files or files in "ignored" folders, including the
Custom Added Code
You may insert any code that your app requires within pre-designated locations. Please note that you cannot add one yourself that wasn't generated from the template! A custom code location is currently specified with commented out delimiters at the beginning and end, as follows:
// ns__custom_start <location name> … custom code inserted here… // ns__custom_end unit: <location name>
That code should be replaced completely after a generation, and is ideal. If you feel a need to add custom code somewhere else in a file, contact your template maintainer and explain why you think that a custom section should be designated in the precise file and location.
Please understand that code outside of the custom locations will not persevere through a regeneration of the code.
The files contain several sections which can be replaced by your own code. They are currently designated as follows:
// ns__start_section <location name> … replaceable here… // ns__end_section <location name>
Please note that, even though your replacement will be preserved, that doesn't mean that the code might not be broken when regenerated. For instance, if in the future the ns file changes and there's a different hierarchy in a unit, a query might change as well on the back end, breaking your replaced code. So it’s always preferred to used custom code sections rather than to replace code. And in general, it's better to replace a subsection than a larger section.
But, often replacement code will be necessary somewhere in a code base. To replace a section, change the commented out delimiters as follows, and then your changes to the code within will persist:
// ns__start_replacement <location name> … replaceable here… // ns__end_replacement <location name>
Note that removing code is also possible, by simply creating an empty replacement section:
// ns__start_replacement <location name> // ns__end_replacement <location name>
There is a designated folder, usually
src/custom, for your own code. The folder is specified in a template. If you're not sure where it is, you can ask the one who built your code base.
You can put whatever you’d like in the custom folder. Just realize that the more you change from generated code the more fragile the changes will be, so the general rule is that it’s better to stick to the generated components as much as you can.
Also, a template can specify that any list of files or folders are ignored. Their contents will be preserved through a code generation.