Skip to content

Add include_* for static contentΒ #483

@gshotwell

Description

@gshotwell

We took include_html out of #127 because it seems like this needs a different strategy. There are a few use cases that we want to consider:

  • Include HTML in iframe (which is what's implemented below)
  • Include inline HTML
  • Include Markdown like (shiny::includeMarkdown())
  • Maybe include_qmd to render a quarto document and include it as an HTML file?

The old implementation for reference.

@add_example()
def include_html(
    path: str,
    *,
    method: Literal["link", "link_files"] = "link",
    attrs: TagAttrs = {},
) -> Tag:
    """
    Include an HTML file

    Parameters
    ----------
    path
        A path to an HTML file.
    method
        One of the following:
          * ``"link"``: Link to the CSS file via a :func:`~ui.tags.link` tag.
          * ``"link_files"``: Same as ``"link"``, but also allow for the HTML file to
            request other files within ``path``'s immediate parent directory (e.g.,
            include an HTML ``<img>`` that points to another local file). This isn't the
            default behavior because you should **be careful not to include files in the
            same directory as ``path`` that contain sensitive information**. A good
            general rule of thumb to follow is to have ``path`` be located in a
            subdirectory of the app directory. For example, if the app's source is
            located at ``/app/app.py``, then ``path`` should be somewhere like
            ``/app/html/index.html`` (and all the other relevant accompanying 'safe'
            files should be located under ``/app/html/``).
    attrs
        Additional attributes to add to the :func:`~ui.tags.iframe` tag.

    Returns
    -------
    A :func:`~ui.tags.iframe` tag.

    Note
    ----
    For safety reasons, this function includes the HTML file as a
    :func:`~ui.tags.iframe`, which means it's 'isolated' from the rest of the parent
    document. If instead, you don't want to isolate (meaning, among other things, you
    want the HTML inherit CSS styles from the parent document), you can do something
    like this:

    .. code-block:: python
        from shiny import ui

        with open("custom.html", "r", encoding="utf-8") as f:
            custom_html = ui.HTML(f.read())

        app_ui = ui.page_fluid(..., custom_html, ...)

    See also
    --------
    ~ui.tags.iframe
    ~ui.HTML
    ~include_javascript
    ~include_css
    """

    include_files = method == "link_files"
    path_dest, hash = maybe_copy_files(path, include_files)

    dep, src = create_include_dependency(
        "include-html-" + hash, path_dest, include_files
    )

    default_attrs: TagAttrs = {
        "src": src,
        "scrolling": "no",
        "seamless": "seamless",
        "frameBorder": "0",
    }

    return tags.iframe(default_attrs, dep, **attrs)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions