Enhanced diagrams.net export functionality

[cody0704]

Description

This Pull Request introduces the editor-drawio::export event to the BookStack platform, following the discussion in issue #4156. The primary goal of this enhancement is to provide additional flexibility and customization for the export settings of the diagrams.net integration within BookStack.

New Public Event - editor-drawio::export

• This event allows for dynamic modification of the diagrams.net export parameters. It is triggered during the export action in the diagrams.net editor embedded within BookStack.
• Users can now customize export settings based on their specific requirements, such as adjusting the scale, format, or any other diagrams.net supported parameters.

Testing and Validation:

• The functionality has been tested by implementing custom scripts in the 'Custom HTML Head Content' section of BookStack.
• Specifically, I verified that adjusting the scale parameter of the export configuration through the new event works as expected, without any issues.

How to Test:

To test this feature, you can add the following script to the 'Custom HTML Head Content' section in BookStack:

window.addEventListener('editor-drawio::export', event => {
    const config = event.detail.config;
    config.scale = 2; // Adjust the scale as needed
});

This script will dynamically adjust the export scale of diagrams.net drawings.

[ssddanbrown]

Thanks for offering this @cody0704. Do you have an active use for this added public event? I just want to make sure we're only adding and maintaining added events that are useful.

I ask because I'm not sure how altering any of the export options would be useful, without needing to make further changes to the BookStack source to alter how the exports are then managed. You indicate adjusting the scale, and reference #4156, but as far as I know that alone won't achieve #4156 without issue (unless the drawing was already at page-container-width) since drawings will just be presented 2x (or the scale ratio) bigger.

If it is for scaling, then I'm also not 100% sure if we should add specific events as workarounds (with side affects) for issues that are open (#3743) as something we'd probably want to address in the future.

[cody0704]

I'm delighted to have the opportunity to discuss this with @ssddanbrown

Thanks for offering this @cody0704. Do you have an active use for this added public event? I just want to make sure we're only adding and maintaining added events that are useful.

I indeed utilize this feature to resolve the issue of blurriness in diagrams saved in BookStack, specifically when created with draw.io. The default scale often results in unclear images, particularly for text-rich diagrams. Allowing the export parameters to be adjustable can significantly enhance the clarity of saved images. This enhancement is particularly beneficial for intricate diagrams where zooming into specific sections is common, potentially leading to blurriness. Hence, I recommend enabling user-defined adjustments, as the necessity for clarity varies based on the complexity and content of the diagrams drawn.

I ask because I'm not sure how altering any of the export options would be useful, without needing to make further changes to the BookStack source to alter how the exports are then managed. You indicate adjusting the scale, and reference #4156, but as far as I know that alone won't achieve #4156 without issue (unless the drawing was already at page-container-width) since drawings will just be presented 2x (or the scale ratio) bigger.

After implementing this functionality, I have been actively using it, setting the scale to 3. My primary use case involves creating flowcharts, which can become quite intricate. When zoomed in, the content tends to get blurry. Adjusting the scale to 3 significantly enhances the clarity of the content. Below is an example for your reference.

Drawio - AWS18

scale: default value (1) - chrome zoom 500%

scale: 3 - chrome zoom 500%

This might not be a great example, but what I want to convey is that after saving in drawio, there will be more pixels, resulting in clearer images. This also relates to whether the patterns in the drawio libraries support scaling. However, at the very least, the text does support scaling

[cody0704]

Should I respond to this question here or would it be better to reply in #3743?

If it is for scaling, then I'm also not 100% sure if we should add specific events as workarounds (with side affects) for issues that are open (#3743) as something we'd probably want to address in the future.

I'm not certain about the exact problems users are facing. However, in my setup, which includes a MacBook Pro 13" 2019 with a Retina display, I addressed the issue using the viewerjs library. This JS library enables image scaling, which, when used in conjunction with the increased export scale of draw.io images(resulting in higher pixel clarity as per the official draw.io documentation at https://www.drawio.com/doc/faq/export-higher-resolution which states that a higher scale results in higher DPI), significantly improves the display quality. The effectiveness of this approach is evident in the attached image.

• Custom HTML Head Content

<!-- viewerjs -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/viewerjs/1.11.3/viewer.min.css" integrity="sha512-zdX1vpRJc7+VHCUJcExqoI7yuYbSFAbSWxscAoLF0KoUPvMSAK09BaOZ47UFdP4ABSXpevKfcD0MTVxvh0jLHQ==" crossorigin="anonymous" referrerpolicy="no-referrer" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/viewerjs/1.11.3/viewer.min.js" integrity="sha512-f8kZwYACKF8unHuRV7j/5ILZfflRncxHp1f6y/PKuuRpCVgpORNZMne1jrghNzTVlXabUXIg1iJ5PvhuAaau6Q==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
<script>
window.onload = () => {
  document.querySelectorAll("div#main-content a").forEach((element) => {
    if (/\.(jpg|png|gif)$/.test(element.href)) {
  element.removeAttribute("href");
    }
  })
  
  document.querySelectorAll('div#main-content img').forEach((element) => {
    new Viewer(element, {
      title: false,
      navbar: false,
      zoomRatio: 0.3,
      toolbar: {
        rotateLeft: {
          size: 'large',
        },
        zoomIn: {
          size: 'large',
        },
        reset: {
          size: 'large',
        },
        zoomOut: {
          size: 'large',
        },
        rotateRight: {
          size: 'large',
        },
      }
    });
  })
}
</script>

The first image appears quite small. Clicking on it allows for enlargement to focus on specific sections.