Simple promise chain for sending a console message

Simple promise chain for waiting N seconds.

Allow for asynchronous programming within iJavaScript nodes.

• see iJavaScript Async option docs
• see iJavaScript issue #73
• see iJavaScript issue #173

Clears the output.

(This is useful to put after importing libraries, or defining a list of functions)

Determines the current global display and console from iJavaScript (or null if not within iJavaScript)

Determines if we are currently within the iJavaScript context

Generates the html used for creating a page break used by the library.

This gives you options about when and how to render it.

utils.ijs.generatePageBreakHTML();
//-- uses the style defined in initializePageBreaks
// <div class="pagebreak"></div>

For example, you can use this so you automatically have a page break after generating the styles

utils.ijs.initializePageBreaks(null, utils.ijs.generatePageBreakHTML());

Returns the HTML used for generating pageBreaks within the library.

This gives you control over rendering the text together

utils.ijs.generatePageBreakStylesHTML();
// <style>

//-- an identifier that can be used to find if this script exists on the page
\/\* ID:___InitializePageBreaks___ \*\/

// @media print {
// .pagebreak { page-break-before: always; }
// }

// </style>

Generates and renders an html block that loads external css and javascript.

For example, allows running browser side d3js in a Jupyter cell, Leaflet, etc.

Remember, your cells in Jupyter are running in NodeJS.

Once all the files have loaded, then onReady will execute in JavaScript.

Note that only the function in onReady is executed in JavaScript (i.e. Data from other cells in Jupyter would normally not be available).

If data is needed from jupyter, pass them through options.data. (ex: airportData example below)

For More - See the htmlScript tutorial.

Example

For example using a cdn library for qr codes

utils.ijs.htmlScript({
    scripts: ['https://cdnjs.cloudflare.com/ajax/libs/qrcodejs/1.0.0/qrcode.min.js'],
    height: '100%',
    onReady: ({rootEl}) => {
        new QRCode(rootEl, "https://jupyter-ijavascript-utils.onrender.com/");
    }
});

Or working with Leaflet - to show maps

//-- nodeJS Variable
airportData = { ohareORD: { lat: 41.975813, lon: -87.909428, title: "O'Hare Intl Airport" } };
//-- render out html
utils.ijs.htmlScript({
    scripts: ['https://unpkg.com/leaflet@1.6.0/dist/leaflet.js',
              'https://unpkg.com/leaflet-providers@1.13.0/leaflet-providers.js'],
    css: ['https://unpkg.com/leaflet@1.6.0/dist/leaflet.css'],
    data: airportData,
    height: 150,
    //-- function will be executed in javaScript
    onReady: ({rootEl, data}) => {
        // L is globally available from the leaflet.js script.
        
        //-- capture the nodeJS data and use in JavaScript. Neat!
        ohareORD = data.ohareORD;

        map = L.map(rootEl);
        map.setView([ohareORD.lat, ohareORD.lon], 14);
        
        new L.marker([ohareORD.lat, ohareORD.lon]).bindPopup(ohareORD.title).addTo(map);
        
        L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
           attribution: '© <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
        }).addTo(map);
    }
});

Required to be called first - in order to write page-breaks in the html results.

(For Example:)

Assume you have the following cells:

* Some Text
* utils.ijs.initializePageBreaks()
* some other text
* utils.ijs.printPageBreak();
* end of document

When you print to HTML and then render to PDF, you'll see the following:

* Some Text
* utils.ijs.initializePageBreaks()

//-- page break

* some other text
* utils.ijs.printPageBreak();

//-- page break

* end of document

Note, sometimes you want to include a text prior to the page break, like mentioning that a page is left intentionally blank - or to identify this is the cell that has the style - so it shouldn't be removed prior to printing.

utils.ijs.initializePageBreaks('<h1>This page left intentionally blank</h1>');

Or, perhaps you always want a page break after defining the styles

utils.ijs.initializePageBreaks(null, utils.ijs.generatePageBreakHTML());

Capture internal comments that can render as markdown (including images) but be turned off - so they are not rendered in the final output

utils.ijs.internalComment(true, `![Screenshot](localhost://path-to-file)`);

and then when preparing to ship, you don't include it

printable=true
utils.ijs.internalComment(!printable, `![Screenshot](localhost://path-to-file)`);

List the globals currently defined.

This can be very useful when keeping track of values after a few cells.

For example:

cars = utils.datasets.fetch('cars.json').then(data => global.cars = data);

then later

utils.ijs.listGlobals();
// cars

List the static members and functions of a class.

Renders HTML that can be easily found in the HTML of an exported document.

This allows for simpler and consistent post-processing (such as which cells to remove prior to rendering to PDF)

For example, within a Jupyter / Jupyter Lab Notebook:

utils.ijs.markDocumentPosition('ijsutils-start-of-content', 'Remove this and everything above', '<h1>Start of content</h1>');

//-- this will render a cell with the following:
// <!-- ##start of stuff## -->
// <span id="ijsutils-start-of-content"><h1>Start of content</h1></span>

We can then look for that id within the output of the notebook.
(Like within a bookmarklet)

parentCell = document.querySelector('#ijsutils-start-of-content').closest('.jp-Cell');

and then remove it - and any cells before it

cellsToRemove = [];
while(parentCell) {
    cellsToRemove.push(parentCell);
    parentCell = parentCell.previousElementSibling;
}

//-- to remove them
cellsToRemove.forEach((el) => el.remove())

Marks the end of content.

This could be useful for removing all cells and content after this point from printing when reviewing the html output.

Marks the start of content.

This could be useful for removing all cells and content prior from printing when reviewing the html output.

Prints markdown if in the context of iJavaScript.

This can be deceptively helpful, as it allows your text to be data driven:

After the {@see module:ijs.initializePageBreaks|utils.ijs.initializePageBreaks} is called, this will create another page break.

For very long or time-intensive executions, sometimes it is better to cache the results than to execute them every single time.

Note that this supports promises, and can be a bit harder to understand.

As opposed to file.useCache - which works synchronously

shouldWrite = true; /// we will write to the cache with the results from the execution
utils.file.useCache(shouldWrite, './cache', 'expensive.json', () => {
  //-- all the items to cache 
  return Promise.resolve()
     .then(() => ajax.retrieve(...))
     .then((results) => {
         const data = results
           .map(obj => ({ ...obj, date: Date.parse(obj.epoch) }));
         .. other things to do
         return data;
      });
})
  //-- using the information AFTER the expensive function or retrieval from cache
  //-- this can ALSO be run in a subsequence cell
  .then((results) => {
     expensiveresults = results;
     conosole.log(`expensiveResults.length: ${results.length}`);
   });

but sometimes I would rather just skip to the end

shouldWrite = false; /// we will read from the cache instead,
// everything else remains the same

utils.file.useCache(shouldWrite, './cache', 'expensive.json', () => {
  //-- all the items to cache 
  return Promise.resolve()
    ... blah blah - none of this will get executed
})
  //-- using the information AFTER the expensive function or retrieval from cache
  //-- this can ALSO be run in a subsequence cell
  .then((results) => {
     expensiveresults = results;
     conosole.log(`expensiveResults.length: ${results.length}`);
   });

//-- completely transparent to the runner
expensiveresults.length = 1023424;