search

qcode-software / qcode-ui

Qcode UI
BSD 3-Clause "New" or "Revised" License
3 stars 0 forks source link

Create Dialog Plugin #209

Open PeterChaplin opened 2 years ago

PeterChaplin commented 2 years ago

Qcode-ui currently relies on the dialog plugin of jQuery-ui. We want to move away from jQuery.

Create a plugin using pure JavaScript, that will provide all the dialog functionality we currently require.

Requirements:

PeterChaplin commented 2 years ago

We have a jQuery modal dialog plugin in mla-www-templates that may be worth referencing.

PeterChaplin commented 2 years ago

After some research, I believe that the html <dialog> element is worth considering: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog

The api is considered "experimental", but has been supported in Chrome and Opera since 2014, Edge since 2020, and Firefox since 2017 but only if enable by the user. I get the impression that it can be considered fairly stable at this point. There's also a polyfill, though I suppose future changes could break that.

PeterChaplin commented 2 years ago

We also have a few options for getting the required html into the page.

  1. Include a "template" element with the base dialog html on every page as standard.
  2. Include a template element with the required html only when a plugin is used by the page.
  3. Generate the required html in JavaScript as a large multi-line string, then parse into DOM elements.
  4. Generate the required html in JavaScript using methods such as document.createElement
  5. Store the required html fragments in separate files, load these via AJAX as required.

I'm inclined toward option 5.

PeterChaplin commented 2 years ago

Dialogs require a combination of html and JavaScript. Our current approach on mla-www is to make each page responsible for generating the html of any dialog used on the page, the JavaScript we have is only responsible for opening/closing the dialog, but the expected html structure is documented in the comments. Our current approach in qcode-ui is to use the jQueryUI plugin, which generates the html within the JavaScript.

If we want the html to be generated server-side in the tcl code, we would need to audit each project for each place where dialogs are used, and migrate to a tcl/html based implementation. We would probably want some centralised procs to generate the html, which could be added to qcode-tcl.

If we want the html to be generated from JavaScript only, template literals would be fairly easy to read & maintain, and are widely supported, but not available in IE or Opera Mini.

Regarding the use of <dialog> elements, it depends on whether we need Firefox support in qcode-ui, or if we can focus on Chrome only.

achisholm commented 2 years ago

I'm not sure how much help I've been but here is a few of my thoughts following on from our discussion earlier.

Discussing the various options for getting a dialog's HTML onto a page, I think my preference would be to go the route of when required, adding a Tcl-generated hidden HTML element at the end of the <body>.

Having the HTML for dialogs in the JavaScript might a nice one to avoid maintainability issues, but some Tcl code for the contents of each dialog would still be needed.

Going by usage of my jQuery dialog plugin, the HTML scaffolding for each dialog has stayed stable and there's not been an issue with having multiple instances of the dialog HTML scattered across different templates .

To make some of the decisions it would be good to know whether our aim is to to use the plugin exclusively on the ERP or also to be used on the TLC & ML websites.

On the ERP side of things, most dialogs seem to follow a pattern of including:

If the ERP is all the plugin is required for, then your plugin might be designed to accept arguments for these 3 elements. Although if the plugin should support more complex HTML structures inside the dialog, for example some of the dialogs included on the websites, then the plugin's job should be reduced and the Tcl would best to provide all of the HTML.

Examples of web pages that include a modal dialog:

Regarding the decision to use a the <dialog> element, trying this demo it appears both latest Firefox and latest Safari still don't support it, so if our goal is to use the plugin on customer facing websites we'd need the polyfill, or opt to go the route of DIY.

In terms of customisations, I don't think we would ever need to allow user to resize, and similarly don't think that a draggable feature would be that useful in practice.

Some usability features that would be nice:

PeterChaplin commented 2 years ago

@bvw are we worried about Firefox & Safari support in qcode-ui, or only Chrome?

bvw commented 2 years ago

Usage of qcode-ui is mainly ERP. For public facing websites we will need wider support but that could come through another library.

Advantages of only supporting Chrome are simplicity of implementation and test framework.

On balance I think it would be okay to just support Chrome for qcode-ui and we can discuss with Alistair another library for public facing websites.

PeterChaplin commented 2 years ago

Migration to qcode.dialog plugin:

qcode ui plugins:

mla erp template:

mla erp:

PeterChaplin commented 2 years ago

Migrating to the qcode.Dialog plugin has broken some of the automated tests for qcode-ui, due to jsdom not supporting the dialog api. I believe that migrating these tests to the headless browser test setup should fix them.

Test files to be migrated: