Skip to content

adding a jinja2 example to the interactive HTML export #4472

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 3 commits into from
Jan 9, 2024
Merged

adding a jinja2 example to the interactive HTML export #4472

merged 3 commits into from
Jan 9, 2024

Conversation

rl-utility-man
Copy link
Contributor

I often need to write one program that inserts Plotly graphics and customized text into an HTML file. Jinja2 is an obvious way to do so. Here I add an example to the documentation.

If your PR modifies code of the plotly package, we have a different checklist
below :-).

Documentation PR

  • I've seen the doc/README.md file

  • This change runs in the current version of Plotly on PyPI and targets the doc-prod branch OR it targets the master branch

  • If this PR modifies the first example in a page or adds a new one, it is a px example if at all possible

  • Every new/modified example has a descriptive title and motivating sentence or paragraph

  • Every new/modified example is independently runnable

  • Every new/modified example is optimized for short line count and focuses on the Plotly/visualization-related aspects of the example rather than the computation required to produce the data being visualized

  • Meaningful/relatable datasets are used for all new examples instead of randomly-generated data where possible

  • [Not applicable] The random seed is set if using randomly-generated data in new/modified examples

  • New/modified remote datasets are loaded from https://plotly.github.io/datasets and added to https://github.com/plotly/datasets

I welcome a conversation about how to deal with disk files. It's hard to create a realistic example without a read/write file system -- so I left place holders for paths.

  • Large computations are avoided in the new/modified examples in favour of loading remote datasets that represent the output of such computations

  • Imports are plotly.graph_objects as go / plotly.express as px / plotly.io as pio

  • [Not applicable] Data frames are always called df

  • fig = <something> call is high up in each new/modified example (either px.<something> or make_subplots or go.Figure)

  • [ Not applicable] Liberal use is made of fig.add_* and fig.update_* rather than go.Figure(data=..., layout=...) in every new/modified example

  • [ Not applicable ] Specific adders and updaters like fig.add_shape and fig.update_xaxes are used instead of big fig.update_layout calls in every new/modified example

  • fig.show() is at the end of each new/modified example

I did not see value to doing so. If this is relevant, please add it.

  • plotly.plot() and plotly.iplot() are not used in any new/modified example
  • Hex codes for colors are not used in any new/modified example in favour of these nice ones

Code PR

  • I have read through the contributing notes and understand the structure of the package. In particular, if my PR modifies code of plotly.graph_objects, my modifications concern the codegen files and not generated files.
  • I have added tests (if submitting a new feature or correcting a bug) or
    modified existing tests.
  • For a new feature, I have added documentation examples in an existing or
    new tutorial notebook (please see the doc checklist as well).
  • I have added a CHANGELOG entry if fixing/changing/adding anything substantial.
  • For a new feature or a change in behaviour, I have updated the relevant docstrings in the code to describe the feature or behaviour (please see the doc checklist as well).

-->

@rl-utility-man
adding a jinja2 example to the interactive HTML export
8cdc5ab 
Jinja2 is a standard, safe, and powerful way to insert content into HTML in Python.  I add an example to the documentation
@Coding-with-Adam
Copy link
Contributor

Thank you for this PR @rl-utility-man . We'll look it over and get back to you promptly.

@alexcjohnson
Copy link
Collaborator

@rl-utility-man this looks great! I'd like @LiamConnors to review as well, but there are two changes I'd like to see. First, you're using to_html but this page otherwise just references write_html. We should add something simple up top about the distinction between these two. And second, just to make the example a little more concrete, is a simple example.html so it's clear exactly what role {{ fig }} plays in the file - so the full section would look something like:

You can insert Plotly output and text related to your data into HTML templates using Jinja2. First create an HTML template file containing a variable like {{ fig }}:

<!DOCTYPE html>
<html>
<body>
<h1>Here's a Plotly graph!</h1>
{{ fig }}
<p>And here's some text after the graph.</p>
</body>
</html>

Then use the following Python to replace {{ fig }} in the template with HTML that will display the Plotly figure "fig":

import plotly.express as px
from jinja2 import Template
... and so on ...

@rl-utility-man
Copy link
Contributor Author

Glad to help! Thanks for the good suggestions @alexcjohnson! I just committed a new version than implements them. I welcome further feedback and input from you, @LiamConnors and the Plotly community.

LiamConnors
LiamConnors reviewed Jan 8, 2024
View reviewed changes
Copy link
Member

@LiamConnors LiamConnors left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @rl-utility-man.
Really nice example! I was able to get it running by following the steps. I just added a few suggestions to the copy for clarity

@rl-utility-man
Copy link
Contributor Author

rl-utility-man commented Jan 8, 2024 •
edited
Loading

@LiamConnors Your edit looks great. Many thanks! I think this is all in a good place, so defer to you and your colleagues about whether we're ready to accept the pull request.

LiamConnors
LiamConnors approved these changes Jan 9, 2024
View reviewed changes
Copy link
Member

@LiamConnors LiamConnors left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💃 Looks good to me.
Thanks!

@alexcjohnson alexcjohnson merged commit e285e63 into plotly:doc-prod Jan 9, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@LiamConnors LiamConnors LiamConnors approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@rl-utility-man @Coding-with-Adam @alexcjohnson @LiamConnors