jupyter-ijavascript-utils 1.58.0 → 1.60.0

package/DOCS.md

@@ -74,6 +74,10 @@ Give it a try here:
 [![Binder:what can I do with this](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/paulroth3d/jupyter-ijavascript-utils/main?labpath=example.ipynb)
 
 ## What's New
+* 1.60 - Make post-processing of documents easier with {@link module:ijs.markDocumentPosition|ijs.markDocumentPosition}
+* 1.59 - 
+    * #95 - give control with page breaks. So we can render text before the page break (like for headers) - or even get the html used and render it how we want. (ex: {@link module:ijs.generatePageBreakStylesHTML|ijs.printPageBreak})
+    * #96 - Support {@link module:ijs.internalComment|ijs.internalComment} in notebooks (meaning it can render in markdown, but can be disabled when preparing to print)
 * 1.58 - 
     * #91 - add {@link module:object.splitIntoDatums|splitIntoDatums(collection, fieldsToSplitBy)} - to make working with datum libraries - like vega-lite - easier
     * #92 - make using the cache easier for {@link module:file.useCache|file.useCache()} - as you can say to use the cache, and it will still work if the cache file does not exist yet.

package/Dockerfile

@@ -1,3 +1,3 @@
 # syntax=docker/dockerfile:1
 
-FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.58.0
+FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.60.0

package/README.md

@@ -54,6 +54,10 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 ![Screenshot of example notebook](docResources/img/mainExampleNotebook.png)
 
 # What's New 
+* 1.60 - Make post-processing of documents easier with ijs.utils.markDocumentPosition
+* 1.59 - 
+    * #95 - give control with page breaks. So we can render text before the page break (like for headers) - or even get the html used and render it how we want.
+    * #96 - Support internal comments in notebooks (meaning it can render in markdown, but can be disabled when preparing to print)
 * 1.58 - 
     * #91 - add object.splitIntoDatums - to make working with datum libraries - like vega-lite - easier
     * #92 - make using the cache easier - as you can say to use the cache, and it will still work if the cache file does not exist yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.58.0",
+  "version": "1.60.0",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",
@@ -23,7 +23,8 @@
     "doc": "npm run prep:docdash && node_modules/.bin/jsdoc -c ./jsdoc.json -u ./tutorials ./DOCS.md",
     "prep:docdash": "cp docResources/docdash/layout.tmpl node_modules/docdash/tmpl/layout.tmpl && rm -rf docResources/notebooks/node_modules",
     "open:coverage": "open ./coverage/lcov-report/index.html",
-    "open:docs": "open ./docs/index.html"
+    "open:docs": "open ./docs/index.html",
+    "open:binder": "open https://mybinder.org/v2/gh/paulroth3d/jupyter-ijavascript-utils/main"
   },
   "repository": {
     "type": "git",

package/src/ijs.js

@@ -29,6 +29,15 @@ require('./_types/global');
  *   * {@link module:ijs.clearOutput|ijs.clearOutput} - clears the output to declutter results (like importing libraries, or functions)
  *   * {@link module:ijs.initializePageBreaks|ijs.initializePageBreaks} - call at least once to allow pageBreaks when rendering PDFs
  *   * {@link module:ijs.printPageBreak|ijs.printPageBreak} - call to print a page break when rendering PDFs
+ *   * {@link module:ijs.generatePageBreakStylesHTML|ijs.printPageBreak} - generates the html used in to allow for pagebreaks
+ *          (so you can render them as you'd like)
+ *   * {@link module:ijs.generatePageBreakHTML|ijs.generatePageBreakHTML} - generates the html that uses the styles to render pagebreaks
+ *          (so you can render them as you'd like)
+ *   * {@link module:ijs.internalComment|ijs.internalComment} - render markdown, but be able to turn it off, prior to printing
+ *   * {@link module:ijs.markDocumentPosition|ijs.markDocumentPosition} - render something in html for post processing
+ *          (such as identifying the start of document and removing everything prior)
+ *   * {@link module:ijs.markStartOfContent|ijs.markStartOfContent} - most comment mark - the start of content
+ *   * {@link module:ijs.markEndOfContent|ijs.markEndOfContent} - most comment mark - the end of content
  * * using a cache for long running executions
  *   * {@link module:ijs.useCache|ijs.useCache()} - perform an expensive calculation and write to a cache, or read from the cache transparently
  * 
@@ -235,6 +244,8 @@ module.exports.detectIJS = function detectIJS() {
  * ![Screenshot of markdown](img/ijsMarkdown.png)
  * 
  * @param {String} markdownText - The markdown to be rendered
+ * @param {*} markdownText - the markdown text to render
+ * @param {Jupyter$$} [display] - the display to render the output to.
  * @example
  * 
  * utils.ijs.markdown(`# Overview
@@ -246,6 +257,35 @@ module.exports.markdown = function markdown(markdownText, display) {
   displayToUse.mime({ 'text/markdown': markdownText });
 };
 
+/**
+ * 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)`);
+ * ```
+ * 
+ * @param {Boolean} shouldRender - whether the comment should be rendered to the output
+ * @param {String} markdownText - the markdown text to render
+ * @param {Jupyter$$} [display] - the display to render the output to.
+ */
+module.exports.internalComment = function internalComment(shouldRender, markdownText, display) {
+  if (!IJSUtils.detectIJS()) return;
+  const displayToUse = display || global.$$;
+  if (shouldRender) {
+    displayToUse.markdown(markdownText, display);
+  } else {
+    displayToUse.html('<span class="output-to-be-removed-from-printing">&nbsp;</span>');
+  }
+};
+
 /**
  * List the globals currently defined.
  * 
@@ -592,7 +632,7 @@ module.exports.htmlScript = function htmlScripts(
  * (This is useful to put after importing libraries,
  * or defining a list of functions)
  */
-module.exports.clearOutput = function clearOutput(outputText = '') {
+module.exports.clearOutput = function clearOutput(outputText = '', outputHTML = '') {
   //-- you must be in iJavaScript container to rendeer
   const context = IJSUtils.detectContext();
   
@@ -600,10 +640,149 @@ module.exports.clearOutput = function clearOutput(outputText = '') {
     return;
   }
 
-  context.$$.text(outputText);
+  if (!outputHTML) {
+    context.$$.text(outputText);
+  } else {
+    context.$$.html(outputHTML);
+  }
 };
 module.exports.noOutputNeeded = module.exports.clearOutput;
 
+/**
+ * Marks the start of content.
+ * 
+ * This could be useful for removing all cells and content prior from printing
+ * when reviewing the html output.
+ * 
+ * @see {@link module:ijs.markDocumentPosition|ijs.markDocumentPosition}
+ * @example
+ * utils.ijs.markStartOfContent();
+ * 
+ * //-- will render the following in the cell
+ * // <!-- ##Start of content. This could be used to remove everything prior from printing.## -->
+ * // <span id="ijsutils-start-of-content">&nbsp;</span>
+ */
+module.exports.markStartOfContent = function markStartOfContent() {
+  IJSUtils.markDocumentPosition('ijsutils-start-of-content', 'Start of content. This could be used to remove everything prior from printing.');
+};
+
+/**
+ * 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.
+ * 
+ * @see {@link module:ijs.markDocumentPosition|ijs.markDocumentPosition}
+ * @example
+ * utils.ijs.markEndOfContent();
+ * 
+ * //-- will render the following in the cell
+ * // <!-- ##End of content. This could be used to remove everything after from printing.## -->
+ * // <span id="ijsutils-end-of-content">&nbsp;</span>
+ */
+module.exports.markEndOfContent = function markEndOfContent() {
+  IJSUtils.markDocumentPosition('ijsutils-end-of-content', 'End of content. This could be used to remove everything after from printing.');
+};
+
+/**
+ * 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)
+ * 
+ * @param {String} elementId - id of the element that could be found through document.querySelector
+ * @param {String} [markerComment] - Any additional text to put in an html comment
+ * @param {String} [innerHTML] - Optional text to be shown in the span (useful for making it easier to find)
+ * @returns {String} the html
+ * @private
+ */
+module.exports.generatePositionMarkerHTML = function generatePositionMarkerHTML(elementId, markerComment, innerHTML) {
+  const cleanInnerHTML = innerHTML || '&nbsp;';
+  const html = `
+${!markerComment ? '' : `<!-- ##${markerComment}## -->`}
+<span id="${elementId}">${cleanInnerHTML}</span>
+`;
+  return html;
+};
+
+/**
+ * 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.<br />
+ * (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())
+ * ```
+ * 
+ * @param {String} elementId - id of the element that could be found through document.querySelector
+ * @param {String} [markerComment] - Any additional text to put in an html comment
+ * @param {String} [innerHTML] - Optional text to be shown in the span (useful for making it easier to find)
+ * @see {@link module:ijs.markStartOfContent|ijs.markStartOfContent} 
+ * @see {@link module:ijs.markEndOfContent|ijs.markEndOfContent} 
+ */
+module.exports.markDocumentPosition = function markDocumentPosition(elementId, markerComment, innerHTML) {
+  const resultHTML = IJSUtils.generatePositionMarkerHTML(elementId, markerComment, innerHTML);
+
+  IJSUtils.clearOutput(null, resultHTML);
+};
+
+/**
+ * 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>
+ * ```
+ * 
+ * @returns {String} - the html styles tag used to allow for page breaks to be generated
+ */
+module.exports.generatePageBreakStylesHTML = function generatePageBreakStylesHTML() {
+  return `<style>
+/* ID:___InitializePageBreaks___ */
+@media print {
+.pagebreak { page-break-before: always; } /* page-break-after works, as well */
+}
+</style>`;
+};
+
 /**
  * Required to be called first - in order to write page-breaks in the html results.
  * 
@@ -634,8 +813,26 @@ module.exports.noOutputNeeded = module.exports.clearOutput;
  * 
  * * 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());
+ * ```
+ * 
+ * @param {String} [htmlToInjectBefore] - optional html text to include prior to the pageBreak
+ *      (This can be helpful like - page left intentionally blank)
+ * @param {String} [htmlToInjectAfter] - optional html text to include prior to the pageBreak
  */
-module.exports.initializePageBreaks = function initializePageBreaks() {
+module.exports.initializePageBreaks = function initializePageBreaks(htmlToInjectBefore, htmlToInjectAfter) {
   //-- you must be in iJavaScript container to rendeer
   const context = IJSUtils.detectContext();
     
@@ -643,20 +840,50 @@ module.exports.initializePageBreaks = function initializePageBreaks() {
     return;
   }
 
-  context.$$.html(`<style>
-    @media print {
-    .pagebreak { page-break-before: always; } /* page-break-after works, as well */
-    }
-    </style>
-    <div class="pagebreak"></div>
-    `);
+  const cleanInjectionPrior = htmlToInjectBefore || '';
+  const htmlToRender = IJSUtils.generatePageBreakStylesHTML();
+  const cleanInjectionAfter = htmlToInjectAfter || '';
+
+  context.$$.html(`
+${cleanInjectionPrior}
+${htmlToRender}
+${cleanInjectionAfter}`);
+};
+
+/**
+ * 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 {String}
+ * @see {@link module:ijs.printPageBreak|ijs.printPageBreak}
+ * @see {@link module:ijs.initializePageBreaks|ijs.initializePageBreaks}
+ */
+module.exports.generatePageBreakHTML = function generatePageBreakHTML() {
+  return '<div class="pagebreak"></div>';
 };
 
 /**
  * After the {@see module:ijs.initializePageBreaks|utils.ijs.initializePageBreaks} is called,
  * this will create another page break.
+ * 
+ * @param {String} [htmlToInjectBefore] - optional html text to include prior to the pageBreak
+ *      (This can be helpful like - page left intentionally blank)
+ * @param {String} [htmlToInjectAfter] - optional html text to include prior to the pageBreak
  */
-module.exports.printPageBreak = function printPageBreak() {
+module.exports.printPageBreak = function printPageBreak(htmlToInjectBefore, htmlToInjectAfter) {
   //-- you must be in iJavaScript container to rendeer
   const context = IJSUtils.detectContext();
   
@@ -664,7 +891,9 @@ module.exports.printPageBreak = function printPageBreak() {
     return;
   }
 
-  context.$$.html('<div class="pagebreak"></div>');
+  const htmlToRender = IJSUtils.generatePageBreakHTML();
+
+  context.$$.html(`${htmlToInjectBefore || ''}${htmlToRender}${htmlToInjectAfter || ''}`);
 };
 
 /**