********
Overview
********

Snippet Dynamic Applications on the SL1 platform are extremely powerful and
flexible. A snippet developer has the full Python ecosystem available to them
to solve the common problems of monitoring. Some common tasks of monitoring
are:

* specifying what to collect
* communicating with an endpoint or device
* transforming device responses into useful data
* handling device errors
* handling code errors
* managing internal events, metrics, and logs

The power and flexibility of Snippet Dynamic Applications mean that nearly any
collection problem can be solved with enough time and code, but most
developers do not have unlimited time and code. The Snippet Framework builds
on top of the Snippet Dynamic Application and aims to make the common problems
of monitoring simple to solve, while still allowing for customization to solve
more complex problems.

.. image:: ../_static/lc_pie.png

The goal of the Snippet Framework is to handle the routine and difficult parts
of data collection, so that you can focus only on the specific problem you
need to solve. Many problems will be solved with no code. A smaller set of
problems can be solved with small amounts of code. Finally, the most complex
and unusual problems can be solved by plugging in custom libraries and
functions.

The Snippet Framework philosophy is that common collection tasks should not
require a mountain of complex code. Common collection tasks should be easy
while complex tasks should be possible.

===============
Default Snippet
===============

All Snippet Framework Dynamic Applications use the **Default Snippet**
as its basis. The Snippet is essentially a wrapper and contains a section for
specifying custom information such as custom substitution, custom steps, and
imports. When writing your own Dynamic Applications, you should begin with the
`Default Snippet` and place all custom information in between the `User Editable`
comment blocks. To get started, it is recommended to use a Dynamic Application
included in the Low-code Tools PowerPack and customize it to your needs.

You can find the `Default Snippet` below:

.. code-block:: python

    from silo.apps.errors import error_manager
    with error_manager(self):

        from silo.low_code import *
        from silo.apps.collection import create_collections, save_collections

        # =====================================
        # =========== User Editable ===========
        # =====================================

        # List any custom substitutions that need to occur within the snippet arguments
        custom_substitution = {}

        # =====================================
        # ========= End User Editable =========
        # =====================================


        collections = create_collections(self)
        snippet_framework(collections, custom_substitution, snippet_id, app=self)
        save_collections(collections, self)

===============
Result Handling
===============

The Snippet Framework provides out-of-the-box unicode normalization(NFKD) to ASCII for all results.
To understand how your data is normalized and displayed in SL1 use the provided box below.

.. raw:: html

    <div class="input-output-box">
        <label for="input-text">Enter your text:</label>
        <textarea id="input-text" rows="4" cols="50"></textarea>
        <button id="normalize">Normalize</button>
        <br><br>
        <label for="output-text">Normalized text:</label>
        <textarea id="output-text" rows="4" cols="50" readonly></textarea>
    </div>

    <script>
        function normalizeText() {
            const input = document.getElementById('input-text').value;
            // let output = input.normalize('NFKD').replace(/[^\x00-\x7F]/g, '');
            let output = '';
            for (let i = 0; i < input.length; i++) {
                const ch = input[i].normalize('NFKD').replace(/[^\x00-\x7F]/g, '');
                if (ch === '') {
                    const codePoint = input[i].codePointAt(0).toString(16);
                    output += `[\\x${codePoint}]`;
                } else {
                    output += ch;
                }
            }

            document.getElementById('output-text').value = output;
        }

        const input_button = document.getElementById('normalize');
        input_button.addEventListener('click', normalizeText);
    </script>


.. note::
    While the Snippet Framework **does** support Bulk Dynamic Applications, it **does not**
    support the use of the `self` object in said applications, with the exception being the
    `Default Snippet` itself.