Basic Usage
===========

Use the following imports (the exact aliases ``dcc`` and ``html`` are
default values in the htexpr configuration)::

    import dash
    from dash import dcc, html
    from dash import table as dash_table
    import htexpr

When building your Dash app, instead of instantiating objects like
``html.Div`` you can now write HTML in a string that is compiled and
evaluated by htexpr::

    app = dash.Dash()
    app.layout = htexpr.compile("""
      <div class="c">
        <Input id="i" type="number" />
      </div>
    """).run()

This has the same effect as instantiating the objects directly::

    app.layout = html.Div(
        className="c",
        children=[
	    dcc.Input(id="i", type="number", children=[])
	]
    )

In addition to compiling HTML, you can embed Python code, which itself
can include HTML in parentheses::

    from pathlib import Path
    name = "A Fine Dashboard"
    h1_class = "heading"
    app.layout = htexpr.compile("""
      <div>
        <header>
          <h1 class={ h1_class }
              style={"font-size": "x-large", "background": "#8899aa"}
             >{ name }</h1>
        </header>
        <h2>Files</h2>
        <ul>
          <li>. (the current directory)</li>
          <li>.. (the parent directory)</li>
          [ (<li>{ str(file) }</li>)
            for file in Path('.').glob('*')
            if file.is_file() ]
        </ul>
      </div>
    """).run()

Several substitutions of Python code occur:

* In ``<h1 class={ h1_class }>``, the ``class`` attribute gets the
  value of the ``id`` variable. Because ``class`` is not a legal
  Python identifier, the `H1 component`_ actually takes an argument
  named ``className``, so htexpr translates the HTML ``class``
  attribute to the ``className`` argument.
* In ``<h1 style={...}>``, the ``style`` attribute has a value
  that is a Python dictionary. The `H1 component`_ (and all others)
  accept a dictionary for the ``style`` argument.
* In ``<h1>{ name }</h1>``, the element contains the value of the
  ``name`` variable.
* In ``<ul>[ (<li>...</li>) for file in Path('.').glob('*') ]</ul>``,
  the list items are generated from a list comprehension. Note that
  the list item element must be placed in parentheses to allow the
  htexpr parser to detect it.
* Each list item ``(<li>{ str(file) }</li>)`` is generated by calling
  the Python function ``str`` on the comprehension variable ``file``.

.. _`H1 component`: https://dash.plotly.com/dash-html-components/h1

The rules are:

* Use any of Dash's `HTML`_ or `core components`_, or `DataTable`_.
  HTML elements may be typed in any case (``<H1>`` or ``<h1>``), other
  components must be in the exact case defined by Dash
  (``<Dropdown>``, not any other spelling).
* Close all elements with either a closing tag or a self-closing
  tag: ``<ul>...</ul>`` or ``<input />`` are both fine.
* Enclose literal attribute values in single or double quotes:
  ``<span id='foo' class="bar" />``.
* Enclose Python code in braces in either attribute values or inside
  elements. For attributes such as ``style`` that take a dictionary,
  it is enough to use one layer of braces.
* You can also write list comprehensions in square brackets, and the
  results are spliced at the same level as neighboring elements. Thus
  the file list in the preceding example has the static items for
  ``.`` and ``..`` at the same level as the dynamically generated
  items.
* Some attribute names are transformed, because they are either
  invalid identifiers or React developers prefer camel case:

  =================   ================
  HTML                React
  =================   ================
  class               className
  accesskey           accessKey
  hreflang            hrefLang
  contenteditable     contentEditable
  tabindex            tabIndex
  colspan             colSpan
  rowspan             rowSpan
  spellcheck          spellCheck
  for                 htmlFor
  =================   ================

  In all cases, htexpr translates the HTML spelling to the React spelling,
  which is understood by Dash components.
* The HTML elements ``Map`` and ``Object`` are translated to ``MapEl`` and
  ``ObjectEl``, respectively.




.. _`HTML`: https://dash.plotly.com/dash-html-components
.. _`core components`: https://dash.plotly.com/dash-core-components
.. _`DataTable`: https://dash.plotly.com/datatable