<commit_before>Embedding
=========

Adhocracy 3 is designed to be "embed first". This means that it will
usually not be used on its own, but embedded in some website, e.g. a
content management system (CMS).  But it should also be possible to
embed individual widgets.

Terms
-----

The following terms are used in the context of embedding:

Host
    The website where adhocracy is embedded.

Widget
    A piece of adhocracy that can be embedded on its own.  Some
    functionality (e.g. registration) will require the user to switch
    to the *platform*.  See also :doc:`css_guidelines`.

Frontend URL
    This is where the actual adhocracy frontend is available.  Users are
    not supposed to interact with this directly.  Instead, the frontend
    should be embedded somewhere.

Platform URL
    This is where the full adhocracy is available (as opposed to a
    widget).  The term *platform* also refers to the complete set of
    functionality and navigation that sets it apart from a mere widget.

Canonical URL
    Content can show up in different places (i.e. with different URLs),
    namely at the frontend URL, the platform URL and embedded in many
    more places.  The canonical URL is the *default* URL. In most cases
    (but not in all!), it will point to the platform.  See also `RFC6596
    <https://tools.ietf.org/html/rfc6596>`_.


Embed-API
---------

The general idea consists of two parts: the SDK javascript code, which has to
be loaded once, and widget markers in the DOM. On initialization, the widget
markers are replaced by iframes, which show the actual content.


SDK snippet
+++++++++++

This is our JavaScript code that runs in the host page.  It was
carefully written to not interfere with the hosts own JavaScript code.

- Bootstraps everything, initializes widgets
- Selects Adhocracy version to be used
- Opens `adhocracy` namespace
- Resizes widgets on the fly

Example::

    <script type="text/javascript" src="https://adhocracy.lan/static/js/AdhocracySDK.js"></script>
    <script type="text/javascript">
        adhocracy.init('http://adhocracy.lan', function(adhocracy) {
            adhocracy.embed('.adhocracy_marker');
        });
    </script>

One or more markers can appear anywhere in the document::

    <div class="adhocracy_marker"
         data-widget="document-workbench">
    </div>
    <div class="adhocracy_marker"
         data-widget="paragraph-version-detail"
         data-locale="en"
         data-ref="..." data-viewmode="display">
    </div>


Widget markers
++++++++++++++

A widget is defined by

- One embeddable angular directive (presentation)
- Optionally a locale
- Multiple directive parameters

Constraints:

- Syntax should exist for both HTML5 (`data`- parameters) and HTML4


Example (current HTML5 syntax)::

    <div class="adhocracy_marker" data-widget="proposal-workbench" data-content="/proposal"></div>


Special parameters
~~~~~~~~~~~~~~~~~~

-   the special widget ``"plain"`` will embed the full platform instead
    of a single widget::

        <div class="adhocracy_marker" data-widget="plain"></div>

-   ``autoresize`` will control whether the iframe will automatically be
    resized to fit its contents.  Defaults to ``true``.  It is
    recommended to set this to ``false`` if the embedded widget contains
    moving columns::

        <div class="adhocracy_marker" data-widget="plain" data-autoresize="false"></div>

-   ``locale`` can be used to set a locale.

-   ``autourl``: If set to ``true``, the URL of the embedded adhocracy
    will be appended (and constantly updated) to the host URL via ``#!``.
    This is only possible once per host page for obvious reasons.

-   ``initial-url`` will set the initial URL (i.e. path, query and
    anchor) for the embedded platform if widget is ``"plain"``.
<commit_msg>use explicit height with autoresize=false<commit_after>Embedding
=========

Adhocracy 3 is designed to be "embed first". This means that it will
usually not be used on its own, but embedded in some website, e.g. a
content management system (CMS).  But it should also be possible to
embed individual widgets.

Terms
-----

The following terms are used in the context of embedding:

Host
    The website where adhocracy is embedded.

Widget
    A piece of adhocracy that can be embedded on its own.  Some
    functionality (e.g. registration) will require the user to switch
    to the *platform*.  See also :doc:`css_guidelines`.

Frontend URL
    This is where the actual adhocracy frontend is available.  Users are
    not supposed to interact with this directly.  Instead, the frontend
    should be embedded somewhere.

Platform URL
    This is where the full adhocracy is available (as opposed to a
    widget).  The term *platform* also refers to the complete set of
    functionality and navigation that sets it apart from a mere widget.

Canonical URL
    Content can show up in different places (i.e. with different URLs),
    namely at the frontend URL, the platform URL and embedded in many
    more places.  The canonical URL is the *default* URL. In most cases
    (but not in all!), it will point to the platform.  See also `RFC6596
    <https://tools.ietf.org/html/rfc6596>`_.


Embed-API
---------

The general idea consists of two parts: the SDK javascript code, which has to
be loaded once, and widget markers in the DOM. On initialization, the widget
markers are replaced by iframes, which show the actual content.


SDK snippet
+++++++++++

This is our JavaScript code that runs in the host page.  It was
carefully written to not interfere with the hosts own JavaScript code.

- Bootstraps everything, initializes widgets
- Selects Adhocracy version to be used
- Opens `adhocracy` namespace
- Resizes widgets on the fly

Example::

    <script type="text/javascript" src="https://adhocracy.lan/static/js/AdhocracySDK.js"></script>
    <script type="text/javascript">
        adhocracy.init('http://adhocracy.lan', function(adhocracy) {
            adhocracy.embed('.adhocracy_marker');
        });
    </script>

One or more markers can appear anywhere in the document::

    <div class="adhocracy_marker"
         data-widget="document-workbench">
    </div>
    <div class="adhocracy_marker"
         data-widget="paragraph-version-detail"
         data-locale="en"
         data-ref="..." data-viewmode="display">
    </div>


Widget markers
++++++++++++++

A widget is defined by

- One embeddable angular directive (presentation)
- Optionally a locale
- Multiple directive parameters

Constraints:

- Syntax should exist for both HTML5 (`data`- parameters) and HTML4


Example (current HTML5 syntax)::

    <div class="adhocracy_marker" data-widget="proposal-workbench" data-content="/proposal"></div>


Special parameters
~~~~~~~~~~~~~~~~~~

-   the special widget ``"plain"`` will embed the full platform instead
    of a single widget::

        <div class="adhocracy_marker" data-widget="plain"></div>

-   ``autoresize`` will control whether the iframe will automatically be
    resized to fit its contents.  Defaults to ``true``.  It is
    recommended to set this to ``false`` if the embedded widget contains
    moving columns.  In that case, an explicit height may be provided
    instead::

        <div class="adhocracy_marker" data-widget="plain" data-autoresize="false" style="height: 400px"></div>

-   ``locale`` can be used to set a locale.

-   ``autourl``: If set to ``true``, the URL of the embedded adhocracy
    will be appended (and constantly updated) to the host URL via ``#!``.
    This is only possible once per host page for obvious reasons.

-   ``initial-url`` will set the initial URL (i.e. path, query and
    anchor) for the embedded platform if widget is ``"plain"``.

{'fraction_non_alphanumeric': 0.09887553315238465, 'fraction_numerical': 0.0034897246994959287, 'mean_word_length': 3.4548071387449624, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3269443', 'n_tokens_mistral': 2236, 'n_tokens_neox': 2086, 'n_words': 950}