<commit_before># Persoo Templates Developer Guide
Here we present coding standards, best practices and guides for creating Persoo templates.

 * [Introduction](#introduction)
   * [HTML template](#html-template)
   * [Styles](#styles)
   * [Scripts](#scripts)
 * [Best practices](#best-practices)
 * [Templates project structure - basic widgets](#templates-project-structure---basic-widgets)
   * [Template source files](#template-source-files)
   * [Using template parts (widget templates preprocessor)](#using-template-parts-widget-templates-preprocessor)

See [TEMPLATE RENDERING] to learn more about persoo templates format and rendering.

## Introduction
Let us look, how to create simple template. Template consist of

* HTML code, which includes Styles and Scripts
* Fields definition (what you allow to be modifiable by your users)

To have templates, which simply "works", you should follow basic rules. Otherwise there may be collision with other CSS rules in page or there cannot be 2 instances of the same widget in the page with different styles, etc.
### HTML template
* Wrap your widget into `#persoo--<%= offerID %>.persoo--widget` container
  Just one element is needed for Persoo working.
* Do not render unnecessary elements with display none.
  Handle them with condition written in [EJS] instead.

> **Example:** In the following examples, we create template for widget with widgetID `mywidget`.
```html
    <div
        id="persoo--<%= offerID %>"
        class="persoo--widget persoo--mywidget"
    >
        <div class="persoo--mywidget__content">
            <% if (headline) { %>
                <h2><%= headline %></h2>
            <% } %>
        </div>

        <style></style>
        <script></script>
    </div>
```

> _**Note** (for advanced users):_ Content from templateParts may define some style variables, which are used in `<style>` section. That is the reason, we place content first, followed by style and scripts.

### Styles
* We are using [BEM naming standarts] in all classNames and IDs, which are used in CSS selectors.
* Avoid using global selectors (without offerID), when the CSS property comes from user fields.
    Otherwise your "public" CSS rule in the page may redefine style also for other widgets of the same template.

> **example:**
```html
...
<style>
    /* Global styles for All instances on the page */
    .persoo--mywidget,
    .persoo--mywidget * {
        box-sizing: border-box;
    }
    .persoo--mywidget__content {
        display: 'flex'
    }

    /* Styles for just a one customized instance */
    #persoo--<%= offerID %> .persoo--mywidget {
        background-color: <%= backgroundColor %>
    }
    #persoo--<%= offerID %> .persoo--mywidget__content {
        flex-direction: <%= flexDirection %>
    }

</style>
...
```

### Scripts
* Avoid using of global functions and selectors (without offerID)
  Otherwise your scripts will affect (or be triggered by) other widgets with same template.

> **example:**
```html
<div id="persoo--<%= offerID %>">
    ...
    <button onclick="persoo_<%= offerID %>_close()">
        Close
    </button>
</div>

<script>
    var persoo_<%= offerID %> = document.getElementById("persoo--<%= offerID %>");

    function persoo_<%= offerID %>_close() {
        persoo_<%= offerID %>.style.display = "none";
        window.persoo("send", "close", {offerID: "<%= offerID %>"});<commit_msg>BUGFIX - github markdown flavour.<commit_after># Persoo Templates Developer Guide
Here we present coding standards, best practices and guides for creating Persoo templates.

 * [Introduction](#introduction)
   * [HTML template](#html-template)
   * [Styles](#styles)
   * [Scripts](#scripts)
 * [Best practices](#best-practices)
 * [Templates project structure - basic widgets](#templates-project-structure---basic-widgets)
   * [Template source files](#template-source-files)
   * [Using template parts (widget templates preprocessor)](#using-template-parts-widget-templates-preprocessor)

See [TEMPLATE RENDERING] to learn more about persoo templates format and rendering.

## Introduction
Let us look, how to create simple template. Template consist of

* HTML code, which includes Styles and Scripts
* Fields definition (what you allow to be modifiable by your users)

To have templates, which simply "works", you should follow basic rules. Otherwise there may be collision with other CSS rules in page or there cannot be 2 instances of the same widget in the page with different styles, etc.
### HTML template
* Wrap your widget into `#persoo--<%= offerID %>.persoo--widget` container
  Just one element is needed for Persoo working.
* Do not render unnecessary elements with display none.
  Handle them with condition written in [EJS] instead.

**Example:** In the following examples, we create template for widget with widgetID `mywidget`.

```html
<div
    id="persoo--<%= offerID %>"
    class="persoo--widget persoo--mywidget"
>
    <div class="persoo--mywidget__content">
        <% if (headline) { %>
            <h2><%= headline %></h2>
        <% } %>
    </div>

    <style></style>
    <script></script>
</div>
```

> _**Note** (for advanced users):_ Content from templateParts may define some style variables, which are used in `<style>` section. That is the reason, we place content first, followed by style and scripts.

### Styles
* We are using [BEM naming standarts] in all classNames and IDs, which are used in CSS selectors.
* Avoid using global selectors (without offerID), when the CSS property comes from user fields.
    Otherwise your "public" CSS rule in the page may redefine style also for other widgets of the same template.

**example:**

```html
...
<style>
    /* Global styles for All instances on the page */
    .persoo--mywidget,
    .persoo--mywidget * {
        box-sizing: border-box;
    }
    .persoo--mywidget__content {
        display: 'flex'
    }

    /* Styles for just a one customized instance */
    #persoo--<%= offerID %> .persoo--mywidget {
        background-color: <%= backgroundColor %>
    }
    #persoo--<%= offerID %> .persoo--mywidget__content {
        flex-direction: <%= flexDirection %>
    }

</style>
...
```

### Scripts

* Avoid using of global functions and selectors (without offerID)
  Otherwise your scripts will affect (or be triggered by) other widgets with same template.

**example:**

```html
<div id="persoo--<%= offerID %>">
    ...
    <button onclick="persoo_<%= offerID %>_close()">
        Close
    </button>
</div>

<script>
    var persoo_<%= offerID %> = document.getElementById("persoo--<%= offerID %>");

    function persoo_<%= offerID %>_close() {
        persoo_<%= offerID %>.style.display = "none";
        window.persoo("send", "close", {offerID: "<%= offerID %>"});
{'fraction_non_alphanumeric': 0.12736686390532545, 'fraction_numerical': 0.0008875739644970414, 'mean_word_length': 3.453886693017128, 'pattern_counts': {'":': 0, '<': 71, '<?xml version=': 0, '>': 76, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2438722', 'n_tokens_mistral': 1978, 'n_tokens_neox': 1857, 'n_words': 717}