How do I include a .js script across a website without format-resources? #10654

andrewpbray · 2024-08-29T22:48:41Z

andrewpbray
Aug 29, 2024

Description

Hello! I've been experimenting with the best way to deploy a .js script that modifies the sidebar across part of a website that uses hybrid navigation. After trying (and failing) to pass it via _quarto.yml, I've made a custom html format for those pages that have the sidebar. _extension.yml looks like this:

contributes:
  formats:
    html:
      include-in-header:
        - text: |
            <script src="mysidebar.js"></script>
      format-resources:
        - "mysidebar.js"

This works, but the downside is that format-resources has copied that .js file across the repo any place that format is being used.

I believe I could do this with a filter that uses quarto.doc.add_html_dependency() but this seems like the sort of functionality that wouldn't require a filter.

Answered by cderv

Aug 30, 2024

Oh I know ! 🤦

include-in-header has text and file option. The file option is just a convenient way to do text by letting Quarto read from a file.

This means the content is expected to be HTML. Here you are passing directly the .js so it will read your JS file and put the content inside the HTML header, and somehow this gets inserted after body. Probably because the content is not valid HTML anyway.

Dealing with path resolution for extension is not simple. Quarto does the right thing when file are passed in extension. But it does not catch and modify a path in text like <script src="mysidebar.js"></script>.

So it would do the right thing for something like this

      include-in-header:
   …

View full answer

mcanouil · 2024-08-30T02:39:41Z

mcanouil
Aug 30, 2024
Collaborator

Did you try using file instead of text (with the same
Content)?

4 replies

andrewpbray Aug 30, 2024
Author

Here are two branches with different attempts:

Method 1

contributes:
  formats:
    html:
      include-in-header:
        - text: |
            <script src="mysidebar.js"></script>
      format-resources:
        - "mysidebar.js"

https://github.com/stat20/stat20notes/tree/try-format-resources

If you run template.qmd you'll see it copies the script into that directory.

Method 2

contributes:
  formats:
    html:
      include-in-header:
        - file: "mysidebar.js"

https://github.com/stat20/stat20notes/tree/try-file

If you run template.qmd, you'll see it puts the content of the file at the top of the <body>, which is unexpected.

Is this the syntax you had in mind for file?

cderv Aug 30, 2024
Maintainer

If you run template.qmd, you'll see it puts the content of the file at the top of the , which is unexpected.

This seems like a bad issue !! 😿

mcanouil Aug 30, 2024
Collaborator

file should be an HTML one for HTML based formats, maybe it is that that causes the issue, but include-in-header should not insert content as if it was include-before-body anyway.

cderv Aug 30, 2024
Maintainer

Oh I know ! 🤦

include-in-header has text and file option. The file option is just a convenient way to do text by letting Quarto read from a file.

This means the content is expected to be HTML. Here you are passing directly the .js so it will read your JS file and put the content inside the HTML header, and somehow this gets inserted after body. Probably because the content is not valid HTML anyway.

Dealing with path resolution for extension is not simple. Quarto does the right thing when file are passed in extension. But it does not catch and modify a path in text like <script src="mysidebar.js"></script>.

So it would do the right thing for something like this

      include-in-header:
        - file: "collapsing-sidebar-sections.html"

Where you would make your JS script, inlined in an HTML

collapsing-sidebar-sections.js would become collapsing-sidebar-sections.html with wrapping <script></script>

collapsing-sidebar-sections.js

<script>
document.addEventListener("DOMContentLoaded", function () {
  
  //// Set the default sidebar state ////
  
  // Get all sidebar sections
  const sidebarSections = document.querySelectorAll('.sidebar-item-section');

  // Collapse all sections initially
  sidebarSections.forEach(section => {
    const collapseElement = section.querySelector('.collapse');
    collapseElement.classList.remove('show');
  });

  // Find the active link
  const activeLink = document.querySelector('.sidebar-item-text.active');

  if (activeLink) {
    // Get the closest section that contains this link
    const activeSection = activeLink.closest('.sidebar-item-section');

    if (activeSection) {
      // Expand this section
      const collapseElement = activeSection.querySelector('.collapse');
      collapseElement.classList.add('show');
    }
  }
  
  //// Update the sidebar state on click ////
  const topLevelItems = document.querySelectorAll('.sidebar-item.sidebar-item-section');

  topLevelItems.forEach(item => {
    const toggleLink = item.querySelector('.sidebar-item-text');

    toggleLink.addEventListener('click', function(e) {
      e.preventDefault();
      const targetId = toggleLink.getAttribute('data-bs-target');
      const targetSection = document.querySelector(targetId);

      // Collapse all other sections
      topLevelItems.forEach(otherItem => {
        if (otherItem !== item) {
          const otherTargetId = otherItem.querySelector('.sidebar-item-text').getAttribute('data-bs-target');
          const otherTargetSection = document.querySelector(otherTargetId);
          if (otherTargetSection.classList.contains('show')) {
            bootstrap.Collapse.getOrCreateInstance(otherTargetSection).hide();
          }
        }
      });

      // Expand or collapse the clicked section
      const targetCollapse = bootstrap.Collapse.getOrCreateInstance(targetSection);
      if (targetSection.classList.contains('show')) {
        targetCollapse.hide();
      } else {
        targetCollapse.show();
      }
    });
  });
});
</script>

Using this syntax, file is correctly resolved to the file inside the extension, and Quarto does include the right thing.

I believe I could do this with a filter that uses quarto.doc.add_html_dependency() but this seems like the sort of functionality that wouldn't require a filter.

BTW, for an extension I think using a Lua filter is perfectly fine and good because user won't have to know it happens. This LUA filter is a good way in Quarto to load your dependencies as HTML dependencies, and have the file path to be resolved correctly.

If we want something specific for JS script that does the path resolution and put the file inside <script>, we would probably need, new configuration.

Or we could have a templating syntax for text in extension, to tell Quarto that the resolved extension path should be appended. Something like

      include-in-header:
        - text: |
            <script src="$ext-root$/mysidebar.js"></script>

or another mechanism to declare resources part of the extension for which path should be fixed. format-resources is meant to copy resources. So we need maybe a extension-resources where

File would be declare relative to extension folder
```
 extension-resources: mysidebar.js
```
Then we would replace in text any occurence. But text replacement like this is not really safe. We could do it only for script src with DOM parsing and replacing 🤔

I don't know what is the more robust solution, that brings value to user experience, if the LUA solution with quarto.doc.add_html_dependency() is not enough. This is the one with full control though !

Answer selected by andrewpbray

andrewpbray · 2024-08-30T13:26:23Z

andrewpbray
Aug 30, 2024
Author

This seems like a bad issue !! 😿

Haha, thank you for the validation!

Everything you said make sense. The path resolution does seem tricky. I'm not sure about the tradeoffs here, but admitting .js files under file: seems like the clearest fix given the name of that argument (when I think of files that I could include in the header of an html file, css and js are at the top of the list).

In the meantime, though, I'm happy for any excuse to write a filter 😎 . That works perfectly. It also provides an open door for other functionality that I'd like to add to this format in the future.

Thanks @cderv !

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

How do I include a .js script across a website without format-resources? #10654

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 2 comments 4 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

How do I include a .js script across a website without format-resources? #10654

Uh oh!

Uh oh!

andrewpbray Aug 29, 2024

Description

Replies: 2 comments · 4 replies

Uh oh!

mcanouil Aug 30, 2024 Collaborator

Uh oh!

Uh oh!

andrewpbray Aug 30, 2024 Author

Method 1

Method 2

Uh oh!

cderv Aug 30, 2024 Maintainer

Uh oh!

mcanouil Aug 30, 2024 Collaborator

Uh oh!

cderv Aug 30, 2024 Maintainer

Uh oh!

andrewpbray Aug 30, 2024 Author

andrewpbray
Aug 29, 2024

Replies: 2 comments 4 replies

mcanouil
Aug 30, 2024
Collaborator

andrewpbray Aug 30, 2024
Author

cderv Aug 30, 2024
Maintainer

mcanouil Aug 30, 2024
Collaborator

cderv Aug 30, 2024
Maintainer

andrewpbray
Aug 30, 2024
Author