be-literate (📖)

Enhance the input element so it can declaratively read contents from a local file (or files).

be-literate turns this code snippet into an attribute-based HTML Enhancement / Decorator / Behavior / Directive / Custom Attribute.

Syntax:

Example 1

<input type=file be-literate onload="
    const {fileContents} = event;
    console.log({fileContents});
" onprogress="console.log(event)">

It causes the input element to emit event "load", and the contents are provided in the event's fileContents. In case other fellow enhancements are "overloading" the onload event in this way, check that the event's "enh" value is set to the name of the enhancement within the Shadow Realm ('beLiterate' or '📖', for example) before proceeding.

Alternative names

In a closed environment, where the chances of clashes with other custom attributes can be controlled, consider using a smaller name, like 📖, by referencing an alternate EMC file:

<input type=file 📖 onload="
    const {fileContents} = event;
    console.log({fileContents});
">

(On Windows, for the 📖 emoji, type 🪟 + . + open book, and it will remain in recent memory for future lookups).

The file contents can be read via path: inputEl.beEnhanced.beLiterate.fileContents (or inputEl.beEnhanced.📖.fileContents).

Security

Unfortunately, the platform provides no support for being able to confirm the integrity of the markup shown above.

So in fact when you run the code above with "minimal" CSP rules in place, it won't work. You would instead need to attach the onload/onprogress event handlers via a script that knows how to locate the element, or via a framework or a web component host.

So what are the ways we can attach these event listeners onto the input element?

There are traditional ways, i.e. via a framework or web component or rendering helper library.

For example:

<input id=myFileInput type=file 📖>
<script>
myFileInput.addEventListener('load', e => {
    const {fileContents} = e;
    console.log({fileContents});
});
myFileInput.addEventListener('progress', e => {
    console.log(e);
});

</script>

But be-literate itself provides the following support:

<script type=module>
    (await import('be-literate/📖.js'))
    .w('#TQBxgJRkCJBoDO9cANgA')
    .a({
        load: e => console.log(e.fileContents),
        progress: e => console.log(e)
    });
</script>
<input  id=TQBxgJRkCJBoDO9cANgA type=file 📖>

"w" stands for "where" and it allows for css match expressions.

"a" stands for "addEventListener" or "actions".

Specifying Read Option

To specify which of the file read options to apply to the file(s), set the attribute:

<input type=file 📖='{"readVerb": "readAsDataURL"}' >

If not specified, as above, the default is readAsText.

Where to store and read the file contents?

As mentioned previously, by default, the contents of the file are stored, and can be retried from:

inputEl.beEnhanced.beLiterate.fileContents

or

inputEl.beEnhanced.📖.fileContents

matching the name of the enhKey specified in the registration file.

However, being that:

1. The contents of the file could be quite large, so using RAM may not be ideal for long term storage, and
2. The file contents may be applicable to a large "audience" of components within the application
3. Accessing something like inputEl.beEnhanced.📖.fileContents is a bit cumbersome (and there are timing considerations to grapple with as well)

... it seems worthwhile to provide for more "strategic" locations to store/retrieve the contents.

For that we make use of the Uniform Storage Path protocol:

<input type=file 📖='{
    "writeTo": "indexedDB://myDB/myFiles/{file.name}"
}'>

<script>
        window.addEventListener('message', e => {
            if(e.data instanceof Set && e.data.has('indexedDB://myDB/myFiles')){
                ...
            }
        });
</script>

Running locally

Any web server than can serve static files will do, but...

1. Install git.
2. Do a git clone or a git fork of repository https://github.com/bahrus/be-literate
3. Install node.js
4. Open command window to folder where you cloned this repo.

5. npm install

6. npm run serve

7. Open http://localhost:3030/demo/dev in a modern browser.

Using from ESM Module:

import 'be-literate/behivior.js';

Using from CDN:

<script type=module crossorigin=anonymous>
    import 'https://esm.run/be-literate';
</script>