jupyter-ijavascript-utils 1.58.0 → 1.59.0

package/DOCS.md

@@ -74,6 +74,9 @@ 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.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.59.0

package/README.md

@@ -54,6 +54,9 @@ 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.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.59.0",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",

package/src/ijs.js

@@ -29,6 +29,11 @@ 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.generatePageBreakStylesHTML} - 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
  * * 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 +240,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 +253,33 @@ 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 (!shouldRender) {
+    IJSUtils.clearOutput();
+  } else {
+    IJSUtils.markdown(markdownText, display);
+  }
+};
+
 /**
  * List the globals currently defined.
  * 
@@ -604,6 +638,36 @@ module.exports.clearOutput = function clearOutput(outputText = '') {
 };
 module.exports.noOutputNeeded = module.exports.clearOutput;
 
+/**
+ * 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 +698,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 +725,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 +776,9 @@ module.exports.printPageBreak = function printPageBreak() {
     return;
   }
 
-  context.$$.html('<div class="pagebreak"></div>');
+  const htmlToRender = IJSUtils.generatePageBreakHTML();
+
+  context.$$.html(`${htmlToInjectBefore || ''}${htmlToRender}${htmlToInjectAfter || ''}`);
 };
 
 /**