Specific topics

In this section you will learn some specific guidelines regarding important topics like naming variables, table structures, translations tags, configurable variables and template updates.

Naming variables

The names of your variables are from the utmost importance to make your code comprehensible for others. The below recommendations are some best practices that you can use:

• Make the variable names 'descriptive'. E.g. 'tax_calculation' instead of 'var_x2'.
• Use underscores between words to make variables more readable e.g. year_start_date
• Variables cannot start with a number nor with an underscore (_)
• Only use small letters, numbers and underscores (_), never use special symbols when naming variables like i.e. “@£$%&”
• All code should be written in English, this includes variable names
• Never use key words such as ‘assign’, ‘result’, ‘variable’,.... to name your variables
• Don’t use abbreviated names (that only you understand). When variables names are too short, it will be hard to search for them in the code since you will have too many hits when searching for it.
• When naming variables which contain “range” or “options”, it could be useful to add collection or option, into the the variable’s name.

{% assign range_personnel_costs = "62" %}
{% assign options_cities = "Ghent|Antwerp|Brussel" %}

Naming custom drops

When we are creating a new custom drop, which would be conditioned by (and named after) another drop, we should never use the text inputted by the user as the name of the key or the namespace of the new drop. Because this could lead to multiples issues, for example duplicated custom drops or "Liquid errors" generated by unsupported characters used in the originating Text field.
In any case, we should use the "key" attribute linked to the iteration to generate a unique string that we can use to name our new drop.

For example, if we have the next iteration:

{% fori varia in custom.varia_titles %}
  {% input varia.title %}  
{% endfori %}

We shouldn't do:

{% for varia in custom.varia_titles %}
  **{{ varia.title }}**
  {% capture title %}{{ varia.title }}{% endcapture %}
  
  {% fori item in custom[title] %}
    {% input item.description %}
  {% endfori %}
{% endfor %}

We should do:

{% for varia in custom.varia_titles %}
	**{{ varia.title }}**
  {% capture title %}title_{{ varia.key }}{% endcapture %}
  
  {% fori item in custom[title] %}
    {% input item.description %}
  {% endfori %}
{% endfor %}

Tables

In almost all templates we make use of tables. Always put a table within stripnewlines tags, it will make your code structured and more readable, but do not forget to add {% newline %} before every new row you want to start.

When developing a large table, make sure to structure your code properly in order to improve the readability.

• E.g. every cell starts on a new line in the code
• Show/hide logic for cells and rows should be easy to read, e.g. by using smart indenting

Tables can be structured like the following two examples. The most preferable example depends on the code per cell (the more code you have, the more convenient it is to use the second example).

Example 1:

{% stripnewlines %}
  | Header 1| Header 2{% newline %}
  |-------- |-------- {% newline %}
  | content | content {% newline %}
  | content | content
{% endstripnewlines %}


Example 2:

{% stripnewlines %}
  | Header 1
  | Header 2
  {% newline %}
  |--------
  |--------
  {% newline %}
  | content
  | content
  {% newline %}
  | content
  | content
{% endstripnewlines %}

Configuration

Every template made available via the Market Place could foresee some configurable variables (note: this section does not apply for custom templates).

As a general rule, following items can be set via configuration:

• Account ranges (account_collection)
• Account defaults (account_collection)
• Firm data of the accountant
• Default text (see note below)

Furthermore, we believe that some items should not be configurable because this would increase the complexity and may lead to the necessity of more support and/or fixes.

• Variables that impact the lay-out of the template
• Variables that impact the flow and/or outcome of a template

Also a template that contains a lot of configurable text input boxes should be considered to be a custom template rather than a configurable one. Try to limit the use of configurable default text (especially when your template mostly contains text boxes).

As a final note, and also mentioned above, for the readability and maintainability of your code consider setting your configuration variables on top of your code (or in separate part if necessary)

Template update

When updating a template always consider the changes you have made to that template. Are the changes purely related to layout or translations? Or have you created, changed or deleted custom variables? Always bear in mind what the impact of you change might be on client data. We define a significant change as an alteration of the liquid code which affects the outcome or result of a reconciliation/account template historically.

If you do updates that affects numbers in your template, you should make your code year dependent. This way your change will not impact client’s data of previous bookyears. How do we do this in practice? You can create a new part for each year.

❗️

We sincerely recommend to only update the most recent part, and not the parts linked to previous years, since that might affect bookyears that should already have been closed but are not.

{% if period.fiscal_year == 2018 %}
  {% include "parts/2018_calculation" %}
{% elsif period.fiscal_year >= 2019 %}
  {% include "parts/2019_calculation" %}
{% else %}
  {% include "parts/prior_2018_calculation" %}
{% else %}