posit-dev / posit-dev/py-shiny
Add include_* for static content
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_qmdto 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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