Add include_javascript(), include_css(), and include_html()

[cpsievert]

Currently requires posit-dev/py-htmltools#32 (since, if we want to return a Tag, we need to know the final src/href).

TODO:

• Add a include_markdown() that utilizes markdown()?
• Probably split up include_html() into include_html() and include_html_frame()?
• Finish include_html()/include_html_frame() examples

[Polkas]

linked to posit-dev/py-htmltools#42
Please remember there is no htmltools::singleton now in the python version. In my opinion we need such especially when connected with this PR functions will be introduced.

[wch]

I had some more thoughts about path handling and the user experience. What happens if someone writes this reasonable-looking code?

app_ui = ui.page_fluid(
    ui.include_css("css/my_styles.css"),
    ...
)

It's a relative path, but we can make any assumptions about which directory is the current working directory. This could result in a not-very-clear error that will leave the user scratching their head.

So we may want to test that the path is an absolute path at the top of include_js and include_css, with something roughly like:

path = Path(path)
if not path.is_absolute():
    raise RuntimeError('include_js() requires an absolute path. Please use
  include_js(Path(__file__)).parent / "myfile.css"') 

(But with a better error message)

The other comments I have about Path are related to this. When the PR was originally created, we mostly used os.path, but since then we generally switched to pathlib.Path.

[gshotwell]

@wch It seems like Path("css/my_css.css").absolute() will always return the absolute path if it can find the file. Do we really need that check?

[wch]

The issue is that if you start the app from a different directory, then the path will be relative to that directory. For example:

[winston@MBP16:~]$ tree temp
temp
├── app.py
├── css
    └── my_css.css

[winston@MBP16:~]$ pwd
/Users/winston

[winston@MBP16:~]$ cat temp/app.py
from pathlib import Path
print(Path("css/my_css.css").absolute())
...

[winston@MBP16:~]$ shiny run temp/app.py
/Users/winston/css/my_css.css

We would want it the printed path to be /Users/winston/temp/css/my_css.css, not /Users/winston/css/my_css.css.

As far as I know, the only reasonable way to do that is to have the user provide __file__ somwhere.

[gshotwell]

Oh I see, so we really want to be checking if the file exists? I'm not sure we want to enforce the __file__ pattern because they might be using css which is hosted outside of the app folder right? Like if you had a single css file which was used by multiple apps. This isn't a great pattern but I don't think it should provoke an error.

What about this:

def check_path(path: Path) -> Path:
    path = Path(path)
    if not path.exists():
        err = f'{path.name} does not exist. Typically you should refer to this file with 'Path(__file__) / {path.name}'")'
        raise RuntimeError(err)
    return path
    ```

[wch]

Oh I see, so we really want to be checking if the file exists?

Yes, that makes sense.

I'm not sure we want to enforce the __file__ pattern because they might be using css which is hosted outside of the app folder right? Like if you had a single css file which was used by multiple apps. This isn't a great pattern but I don't think it should provoke an error.

Good point. I think we should use the __file__ pattern in our examples, though.

What about this:

def check_path(path: Path) -> Path:
    path = Path(path)
    if not path.exists():
        err = f'{path.name} does not exist. Typically you should refer to this file with 'Path(__file__) / {path.name}'")'
        raise RuntimeError(err)
    return path
    ```

That sounds good to me.