.. index:: pair: page; HTML Compatibility Layer
.. _doxid-ui_html_compatibility:
HTML Compatibility Layer
========================
eepp includes an HTML/CSS compatibility layer for rendering document-like content inside the UI system.
This layer is used primarily by:
* ``UIWebView``;
* ``UIMarkdownView``;
* HTML-derived widgets such as ``UIRichText``, ``UITextSpan``, HTML tables, forms, images, and inputs.
It is intentionally distinct from normal eepp application UI authoring.
For ordinary application UI, use native eepp layouts such as ``vbox``, ``hbox``, ``UIRelativeLayout``, ``UIGridLayout``, ``UIFlowLayout``, ``UISplitter``, and ``UITabWidget``. See ```ui_authoring.md```, ```ui_layout_reference.md```, and ```ui_css_for_applications.md```.
This document describes the **HTML compatibility model**, the browser-style layout concepts it implements, and the important places where it differs from a full browser engine.
.. _doxid-ui_html_compatibility_1autotoc_md969:
1. The most important boundary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
eepp has two related but different layout worlds.
.. _doxid-ui_html_compatibility_1autotoc_md970:
Native application UI
---------------------
Normal eepp application interfaces use:
.. ref-code-block:: cpp
UILinearLayout / vbox / hbox
UIRelativeLayout
UIGridLayout
UIFlowLayout
UISplitter
UITabWidget
UIScrollView
layout-width
layout-height
layout-weight
layout-gravity
CSS can configure those widgets, but CSS does not replace their native layout algorithms.
.. _doxid-ui_html_compatibility_1autotoc_md971:
HTML compatibility UI
---------------------
HTML-derived widgets can instead participate in browser-style formatting contexts:
.. ref-code-block:: cpp
block
inline
inline-block
list-item
flex
inline-flex
grid
inline-grid
table
float / clear
absolute / fixed / sticky positioning
The same CSS parser and property system are shared by both worlds, but the **layout semantics depend on the widget type and formatting context**.
Do not use browser layout properties merely because the stylesheet parser accepts them.
.. _doxid-ui_html_compatibility_1autotoc_md973:
2. UIWebView is the full document host
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``UIWebView`` is the main host for HTML documents.
It is implemented as a ``UIScrollView`` containing an embedded ``UISceneNode`` dedicated to the loaded document.
Conceptually:
.. ref-code-block:: cpp
UIWebView
scroll viewport
embedded UISceneNode
document container
html
head
body
The embedded scene gives the document its own:
* widget tree;
* stylesheet state;
* document URI;
* resource loading context;
* font-face registrations;
* navigation handling;
* text-selection context.
Use:
.. ref-code-block:: cpp
auto* webView = UIWebView::New();
webView->loadURI( URI( "file:///path/document.html" ) );
or an HTTP/HTTPS URI.
Native XML layouts can also embed a document directly:
.. ref-code-block:: cpp
Embedded HTML document
The containing layout must be well-formed XML. The WebView consumes its ```` child and loads it through the normal HTML document pipeline in its isolated scene. Document CSS does not affect the host or sibling WebViews. Relative stylesheets, images, and links use the containing scene's URI; set that URI to the layout's file URI when loading layouts from memory. Embedded loading emits the normal navigation and title events without adding the containing layout to URL history.
``UIWebView`` supports navigation history through:
.. ref-code-block:: cpp
goHistoryBack();
goHistoryForward();
refresh();
reload();
canGoBack();
canGoForward();
It also exposes navigation events for started, completed, and failed loads.
.. _doxid-ui_html_compatibility_1autotoc_md975:
3. UIMarkdownView uses the HTML compatibility layer too
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``UIMarkdownView`` converts Markdown to XHTML and then loads the resulting body children as eepp HTML widgets.
Its pipeline is approximately:
.. ref-code-block:: cpp
Markdown
-> Markdown::toXHTML()
-> HTMLFormatter::HTMLBodyToXML()
-> eepp HTML widgets
Unlike ``UIWebView``, ``UIMarkdownView`` shares its enclosing scene and does not create a dedicated embedded scene. It can follow local Markdown links without changing the shared scene's URI.
It is a native vertical layout hosting HTML-derived content and loads the **basic HTML default styles** needed for Markdown rendering.
Use ``UIMarkdownView`` for rendered Markdown content, not as a general browser replacement.
.. _doxid-ui_html_compatibility_1autotoc_md977:
4. HTML is parsed before eepp widgets are created
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``UIWebView`` does not feed arbitrary HTML directly into the normal XML layout parser.
HTML is first parsed with Gumbo, then serialized into strict XML through ``Tools::HTMLFormatter``.
This stage handles browser-style HTML parsing details such as:
* malformed/non-XML HTML syntax;
* omitted closing syntax where HTML permits it;
* HTML void elements;
* boolean attributes;
* normalized tag names.
The resulting strict XML is then loaded through eepp's widget creation system.
This architecture is important:
.. ref-code-block:: cpp
HTML source
-> Gumbo HTML tree
-> strict XML representation
-> UIWidgetCreator
-> eepp widget tree
The final rendered document is therefore still made of eepp widgets.
.. _doxid-ui_html_compatibility_1autotoc_md979:
5. Only registered HTML elements are materialized
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
HTML compatibility is not based on a generic DOM element class that accepts every possible tag.
HTML tags are mapped through ``UIWidgetCreator``.
Currently registered HTML elements include the major supported groups:
.. ref-code-block:: cpp
document:
html
head
body
text and inline:
a
label
span
em
b
strong
small
i
cite
kbd
sub
sup
time
u
ins
s
strike
del
font
code
abbr
tt
mark
blocks:
div
p
blockquote
h1 ... h6
br
hr
pre
lists:
ul
ol
dl
dt
dd
li
semantic containers:
header
article
figure
figcaption
footer
main
section
nav
aside
center
interactive/details:
details
summary
media/replaced content:
picture
img
svg
forms:
form
input
textarea
button
tables:
table
thead
tbody
tfoot
tr
th
td
The exact set is defined in:
.. ref-code-block:: cpp
src/eepp/ui/uiwidgetcreator.cpp
An unregistered tag does not automatically become a transparent generic HTML container.
Applications can register additional widget creators if they need custom tags.
.. _doxid-ui_html_compatibility_1autotoc_md981:
6. This is not a JavaScript browser runtime
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``