posit-dev / posit-dev/py-shiny

Add include_* for static content

Open
#483 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
1.8k
Forks
135
Avg merge
2d 18h
Merged PRs (30d)
21

Description

We took include_html out of https://github.com/rstudio/py-shiny/pull/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)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the old include_html implementation in the issue and compare it with the listed include_javascript and include_css entry points. Review the four proposed use cases and determine the supported scope and API shape; done means the project has a decided strategy for static HTML, inline HTML, Markdown, and any Quarto support.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
frontend, web-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.