Making Files Customizable

Files That You Can Make Customizable

This applies to any generated file. That includes standard, custom and dynamic files.

Note Any file must be matched by the format.customFileFilter glob in your template config file. E.g. *.{js,jsx,md}. See Custom File Filter for more information.

Make a File Customizable

In every hbs file, you can specify sections and custom areas that you want to produce. As stated above, you should become familiar with safe custom code.

Creating Custom Locations

Anywhere you think that custom code is likely to be added, you should insert custom code locations. To do so, simply insert

{{custom <locationName>}}

into the template.

It's always better that your users be able to use custom code than to simply replace a section, because custom code sections are unlikely to be affected as much as section replacements when the ns file or the template change in the future. See the format in safe custom code. The name of each custom section must be unique in any given .hbs file.

Default Code

ns-flip does not have a separate delimiter for a default section, because you can achieve the same effect by placing a custom delimiter around the default text.

For instance, if you want the following to be a default styling:

 margin: 2em;
 padding: 1.5em;
 border: none;
 border-radius: 5px;
 background-color: #f5f5f5;

You can simply turn it into a custom region <location> by inserting {{customStart <location> before and customEnd <location> afterward:

  {{customStart styling}}
  // change your styling here!
  margin: 2em;
  padding: 1.5em;
  border: none;
  border-radius: 5px;
  background-color: #f5f5f5;
  {{customEnd styling}}

You can name the location whatever you want, but it must be unique for that file. If you ever decide to remove the default, you can reduce the whole section to a standard custom location section:

{{custom styling}}

Sections

To create a section, you must place delimiters at the beginning and the end, like this:

{{start <section>}}
...
{{end <section>}}

For instance, to create a section imports, you would insert {{start imports}} before the imports and {{end imports}} after them.

You are allowed to embed as many levels of nested sections as you'd like.

The ideal is in fact several layers of nesting, so that your users will be able to replace one the finest granularity possible. See the format in safe custom code. The name of each section must be unique in any given .hbs file.

As a general rule, you should try to have most or all of the code inside of sections, so that someone can always modify parts of the code and still use the app.

Of course, some parts of the code would be dangerous to expose to replacement. Common sense is the best guide.

Languages with Different Comment Delimiters

If you use a language with delimiters other than /*...*/ you should insert opening and closing delimiters for the language into the format value in the config file.

In this example, *.md (Markdown) files will be matched, so openComment and closeComment both contain entries for md.

format:
  customFileFilter: '*.{ts,tsx,md}'
  defaultOpenComment: "/*"
  defaultCloseComment: "*/"
  openComment:
    .md: "\n[//]: # ("
  closeComment:
    .md: ")"