For your consideration: Extending org-info-js with additional hooks

For your consideration: Extending org-info-js with additional hooks

[David O'Toole]

[-- Attachment #1.1: Type: text/plain, Size: 783 bytes --]

Greetings, Orgmoders.

After some discussion with Yantar on IRC, I humbly submit the attached diff
for your consideration.

It adds new hooks to org-info-js to allow the following: 1. inserting
page-specific HTML into each OrgInfo header, and 2. calling a custom
JavaScript function to run after any page navigation button/link is
clicked. I have used these hooks to implement Org-fleuron, a custom config
with nice navigation buttons, a greeting balloon, and embedded theme/fonts.
You can find out more about org-fleuron here:
https://davidotoole.info/fleuron.html?#org5dc18bc and the page was made
with the setup.

I also corrected some of the English messages displayed by org-info-js.

I hope you will find this useful.

Please let me know if you have any questions or comments!

[-- Attachment #1.2: Type: text/html, Size: 1008 bytes --]

[-- Attachment #2: org-info-src.js.diff --]
[-- Type: text/x-patch, Size: 7951 bytes --]

diff -u /home/dto/Downloads/org-info-src.js /home/dto/notebook/org-info-src.js
--- /home/dto/Downloads/org-info-src.js	2022-12-10 11:47:20.086746072 -0500
+++ /home/dto/notebook/org-info-src.js	2022-12-12 11:48:20.471441625 -0500
@@ -28,30 +28,57 @@
  * </script>
  *
  *
- * The script is now roughly devided in sections by form-feeds. Editors can
- * move section wise using the common emacs commands for this purpos ('C-x ]'
- * and  'C-x ]').
+ * The script is now roughly divided into sections by
+ * form-feeds. Editors can move section-wise using the common emacs
+ * commands for this purpose ('C-x ]' and 'C-x ]').
  *
  * The sections are:
  *    1. This comment block.
- *    2. Everything around =OrgNodes=.
- *    3. =org_html_manager= constructor and setup.
- *    4. =org_html_manager= folding and view related stuff.
- *    5. =org_html_manager= history related methods.
- *    6. =org_html_manager= minibuffer handling.
- *    7. =org_html_manager= user input.
- *    8. =org_html_manager= search functonality.
- *    9. =org_html_manager= misc.
- *    10. Global functions.
+ *    2. Content hooks
+ *    3. Everything around =OrgNodes=.
+ *    4. =org_html_manager= constructor and setup.
+ *    5. =org_html_manager= folding and view related stuff.
+ *    6. =org_html_manager= history related methods.
+ *    7. =org_html_manager= minibuffer handling.
+ *    8. =org_html_manager= user input.
+ *    9. =org_html_manager= search functonality.
+ *    10. =org_html_manager= misc.
+ *    11. Global functions.
  */
 
+/**
+ * This program has been modified from its original version to add
+ * hooks for per-page HTML injection and per-click navigation event
+ * response. A patch is being submitted to upstream. 
+ *  - David T. O'Toole <deeteeoh1138@gmail.com>
+ */
+
+\f
+
+
+/**
+ * The following variable should hold a function which accepts an
+ * integer pageNumber and should return HTML to be inserted in the
+ * OrgInfo header of each page.
+ */
+var OrgInfoPageInsertFunction = function(pageNumber) {return '';};
+
+
+/**
+ * The following variable should hold a function which accepts an
+ * integer pageNumber and performs a user-defined action after the
+ * page has flipped.
+ *
+ */
+var OrgInfoAfterNavigateFunction = function(pageNumber) {};
+
 
 \f
 
 
 /**
  * Creates a new OrgNode.
- * An OrgOutline stores some refs to its assoziated node in the document tree
+ * An OrgOutline stores some refs to its associated node in the document tree
  * along with some additional properties.
  */
 function OrgNode ( _div, _heading, _link, _depth, _parent, _base_id, _toc_anchor)
@@ -904,14 +931,16 @@
     for(var i = 0; i < this.SECS.length; ++i)
     {
       this.SECS[i].IDX = i;
-      var html = '<table class="org-info-js_info-navigation" width="100%" border="0" style="border-bottom:1px solid black;">'
-        +'<tr><td colspan="3" style="text-align:left;border-style:none;vertical-align:bottom;">'
-        +'<span style="float:left;display:inline;text-align:left;">'
-        +'Top: <a accesskey="t" href="javascript:org_html_manager.navigateTo(0);">'+index_name+'</a></span>'
-        +'<span style="float:right;display:inline;text-align:right;font-size:70%;">'
-        + this.LINKS
-        +'<a accesskey="m" href="javascript:org_html_manager.toggleView('+i+');">toggle view</a></span>'
-        +'</td></tr><tr><td style="text-align:left;border-style:none;vertical-align:bottom;width:22%">';
+        var html =
+            OrgInfoPageInsertFunction(i)
+            + '<table class="org-info-js_info-navigation" width="100%" border="0" style="border-bottom:1px solid black;">'
+            +'<tr><td colspan="3" style="text-align:left;border-style:none;vertical-align:bottom;">'
+            + '<span style="float:left;display:inline;text-align:left;">'
+            + 'Top: <a accesskey="t" href="javascript:org_html_manager.navigateTo(0);">'+index_name+'</a></span>'
+            + '<span style="float:right;display:inline;text-align:right;font-size:70%;">'
+            +  this.LINKS
+            + '<a accesskey="m" href="javascript:org_html_manager.toggleView('+i+');">toggle view</a></span>'
+            + '</td></tr><tr><td style="text-align:left;border-style:none;vertical-align:bottom;width:22%">';
 
       if(i>0)
         html += '<a accesskey="p" href="'+this.SECS[i-1].L
@@ -930,10 +959,10 @@
       if(i>0 && this.SECS[i].PARENT.PARENT) // != this.ROOT)
         html += '<a href="'+this.SECS[i].PARENT.L
         +'" title="Go to: '+this.removeTags(this.SECS[i].PARENT.HEADING.innerHTML)+'">'
-        +'<span style="font-variant:small-caps;font-style:italic;">'
+        +'<span class="org-info-js_parent-heading" style="font-variant:small-caps;font-style:italic;">'
         +this.SECS[i].PARENT.HEADING.innerHTML+'</span></a>';
       else
-        html += '<span style="font-variant:small-caps;font-style:italic;">'+this.SECS[i].HEADING.innerHTML+'</span>';
+        html += '<span class="org-info-js_parent-heading" style="font-variant:small-caps;font-style:italic;">'+this.SECS[i].HEADING.innerHTML+'</span>';
 
       // Right:
       html += '</td><td style="text-align:right;vertical-align:bottom;border-style:none;width:22%">';
@@ -1321,7 +1350,7 @@
     var T = this;
     var i = T.NODE.IDX + 1;
     if(i<T.SECS.length) T.navigateTo(i);
-    else T.warn("Already last section.");
+    else T.warn("This is already the last section.");
   },
 
   previousSection: function()
@@ -1329,7 +1358,7 @@
     var t = this;
     var i = t.NODE.IDX;
     if(i>0) t.navigateTo(i-1);
-    else t.warn("Already first section.");
+    else t.warn("This is already the first section.");
   },
 
 
@@ -1345,6 +1374,8 @@
     if(t.VIEW == t.SLIDE_VIEW) t.adjustSlide(sec);
     t.pushHistory(sec, t.NODE.IDX);
     t.showSection(sec);
+
+    OrgInfoAfterNavigateFunction();
   },
 
 
@@ -1386,7 +1417,7 @@
       else if(t.HFO && history.length) history.forward();
       else {
         t.HFO=1;
-        t.warn("History: No where to foreward go from here. Any key and `B' to move to next file in history.");
+        t.warn("History: There is nowhere to go forward to from here. Press `B' to move to the next page in your browser history.");
       }
     } else {
       if(t.HISTORY[t.HIST_INDEX - 1]) {
@@ -1406,7 +1437,7 @@
       else if(t.HBO && history.length) history.back();
       else {
         t.HBO=1;
-        t.warn("History: No where to back go from here. Any key and `b' to move to previous file in history.");
+        t.warn("History: Nowhere to go back to from here. Press `b' to move to the previous page in your browser history.");
       }
     }
   },
@@ -1584,7 +1615,7 @@
           else if(t.NODE.IDX < t.SECS.length - 1) {
             t.navigateTo(t.NODE.IDX + 1);
           } else {
-            t.warn("Already last section.");
+            t.warn("This is already the last section.");
             return;                          // rely on what happends if messaging
           }
         }
@@ -1600,14 +1631,14 @@
               ++idx;
             }
           }
-          t.warn("No next sibling.");
+          t.warn("There is no next sibling.");
           return;                          // rely on what happends if messaging
         }
         else if ('p' == s) {
           if(t.NODE.IDX > 0) {
             t.navigateTo(t.NODE.IDX - 1);
           } else {
-            t.warn("Already first section.");
+            t.warn("This is already the first section.");
             return;                          // rely on what happends if messaging
           }
         }
@@ -1623,7 +1654,7 @@
               --idx;
             }
           }
-          t.warn("No previous sibling.");
+          t.warn("There is no previous sibling.");
         }
         else if ('q' == s) {
           if(window.confirm("Really close this file?")) {
@@ -2291,3 +2322,4 @@
 {
   org_html_manager.init();
 }
+

Diff finished.  Mon Dec 12 11:51:26 2022

Re: For your consideration: Extending org-info-js with additional hooks

[Ihor Radchenko]

"David O'Toole" <deeteeoh1138@gmail.com> writes:

> After some discussion with Yantar on IRC, I humbly submit the attached diff
> for your consideration.
>
> It adds new hooks to org-info-js to allow the following: 1. inserting
> page-specific HTML into each OrgInfo header, and 2. calling a custom
> JavaScript function to run after any page navigation button/link is
> clicked. I have used these hooks to implement Org-fleuron, a custom config
> with nice navigation buttons, a greeting balloon, and embedded theme/fonts.
> You can find out more about org-fleuron here:
> https://davidotoole.info/fleuron.html?#org5dc18bc and the page was made
> with the setup.
>
> I also corrected some of the English messages displayed by org-info-js.

This addition does sound useful.
However, in addition to changes in the code, it would be helpful to
provide appropriate news entry and manual changes.

See
https://git.sr.ht/~bzg/worg/tree/master/item/code/org-info-js/changes.org
and
https://git.sr.ht/~bzg/worg/tree/master/item/code/org-info-js/index.org

Bastien, since the activity around org-info-js revived after a long
delay, should we move the code out of worg into a separate repo?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: For your consideration: Extending org-info-js with additional hooks

[David O'Toole]

[-- Attachment #1: Type: text/plain, Size: 1824 bytes --]

Sure, I would be happy to help out with the news and manual.
I will draft some changes and get back to you.


> This addition does sound useful.
> However, in addition to changes in the code, it would be helpful to
> provide appropriate news entry and manual changes.
>

On Tue, Dec 13, 2022 at 5:00 AM Ihor Radchenko <yantar92@posteo.net> wrote:

> "David O'Toole" <deeteeoh1138@gmail.com> writes:
>
> > After some discussion with Yantar on IRC, I humbly submit the attached
> diff
> > for your consideration.
> >
> > It adds new hooks to org-info-js to allow the following: 1. inserting
> > page-specific HTML into each OrgInfo header, and 2. calling a custom
> > JavaScript function to run after any page navigation button/link is
> > clicked. I have used these hooks to implement Org-fleuron, a custom
> config
> > with nice navigation buttons, a greeting balloon, and embedded
> theme/fonts.
> > You can find out more about org-fleuron here:
> > https://davidotoole.info/fleuron.html?#org5dc18bc and the page was made
> > with the setup.
> >
> > I also corrected some of the English messages displayed by org-info-js.
>
> This addition does sound useful.
> However, in addition to changes in the code, it would be helpful to
> provide appropriate news entry and manual changes.
>
> See
> https://git.sr.ht/~bzg/worg/tree/master/item/code/org-info-js/changes.org
> and
> https://git.sr.ht/~bzg/worg/tree/master/item/code/org-info-js/index.org
>
> Bastien, since the activity around org-info-js revived after a long
> delay, should we move the code out of worg into a separate repo?
>
> --
> Ihor Radchenko // yantar92,
> Org mode contributor,
> Learn more about Org mode at <https://orgmode.org/>.
> Support Org development at <https://liberapay.com/org-mode>,
> or support my work at <https://liberapay.com/yantar92>
>

[-- Attachment #2: Type: text/html, Size: 3114 bytes --]

Re: For your consideration: Extending org-info-js with additional hooks

[David O'Toole]

[-- Attachment #1.1: Type: text/plain, Size: 2021 bytes --]

Here are my suggested changes to the manual and change log.

On Tue, Dec 13, 2022 at 11:32 AM David O'Toole <deeteeoh1138@gmail.com>
wrote:

> Sure, I would be happy to help out with the news and manual.
> I will draft some changes and get back to you.
>
>
>> This addition does sound useful.
>> However, in addition to changes in the code, it would be helpful to
>> provide appropriate news entry and manual changes.
>>
>
> On Tue, Dec 13, 2022 at 5:00 AM Ihor Radchenko <yantar92@posteo.net>
> wrote:
>
>> "David O'Toole" <deeteeoh1138@gmail.com> writes:
>>
>> > After some discussion with Yantar on IRC, I humbly submit the attached
>> diff
>> > for your consideration.
>> >
>> > It adds new hooks to org-info-js to allow the following: 1. inserting
>> > page-specific HTML into each OrgInfo header, and 2. calling a custom
>> > JavaScript function to run after any page navigation button/link is
>> > clicked. I have used these hooks to implement Org-fleuron, a custom
>> config
>> > with nice navigation buttons, a greeting balloon, and embedded
>> theme/fonts.
>> > You can find out more about org-fleuron here:
>> > https://davidotoole.info/fleuron.html?#org5dc18bc and the page was made
>> > with the setup.
>> >
>> > I also corrected some of the English messages displayed by org-info-js.
>>
>> This addition does sound useful.
>> However, in addition to changes in the code, it would be helpful to
>> provide appropriate news entry and manual changes.
>>
>> See
>> https://git.sr.ht/~bzg/worg/tree/master/item/code/org-info-js/changes.org
>> and
>> https://git.sr.ht/~bzg/worg/tree/master/item/code/org-info-js/index.org
>>
>> Bastien, since the activity around org-info-js revived after a long
>> delay, should we move the code out of worg into a separate repo?
>>
>> --
>> Ihor Radchenko // yantar92,
>> Org mode contributor,
>> Learn more about Org mode at <https://orgmode.org/>.
>> Support Org development at <https://liberapay.com/org-mode>,
>> or support my work at <https://liberapay.com/yantar92>
>>
>

[-- Attachment #1.2: Type: text/html, Size: 3544 bytes --]

[-- Attachment #2: changes.org.diff --]
[-- Type: text/x-patch, Size: 693 bytes --]

diff -u /home/dto/Downloads/changes.org /home/dto/orginfo/changes.org
--- /home/dto/Downloads/changes.org	2022-12-13 11:41:29.005889535 -0500
+++ /home/dto/orginfo/changes.org	2022-12-13 11:48:20.807362246 -0500
@@ -8,7 +8,13 @@
 #+INFOJS_OPT: up:https://orgmode.org/worg/
 #+INFOJS_OPT: home:https://orgmode.org buttons:nil
 
+* 2022-12-13 David O'Toole
 
+  * Create additional hooks so that the end-user can insert
+    per-section custom HTML (OrgInfoPageInsertFunction) and handle
+    navigation events (OrgInfoAfterNavigateFunction).
+
+  * Correct English error/status messages displayed in minibuffer.
 
 * 2010-11-24 Benny Simonsen Part 1
 

Diff finished.  Tue Dec 13 12:18:39 2022

[-- Attachment #3: index.org.diff --]
[-- Type: text/x-patch, Size: 3438 bytes --]

diff -u /home/dto/Downloads/index.org /home/dto/orginfo/index.org
--- /home/dto/Downloads/index.org	2022-12-13 11:41:43.022078142 -0500
+++ /home/dto/orginfo/index.org	2022-12-13 12:17:18.460761688 -0500
@@ -192,8 +192,8 @@
      version 0.0.7.3a (fixed in current Org-mode versions). If you export with
      =skip:nil=, you may add this to your stylesheet:
      : #text-before-first-headline {color:red;font-weight:bold;}
-+ Hooks :: The OrgHtmlManager object provides hooks (two currently) to add
-     custom actions.
++ Hooks :: There are several hooks to add custom actions. See the
+  section "Hooks" for more information.
 
 * Shortcuts
 :PROPERTIES:
@@ -703,8 +703,15 @@
 :CUSTOM_ID: hooks
 :END:
 
-Currently two hooks are provided.  Each hook function is called with one or
-more parameters the first of which is the OrgHtmlManager object.
+Two styles of hooks are supported: Standard hooks (which use
+OrgHtmlManager and require a bit of bookkeeping) and simple hooks,
+which are JavaScript variables that hold a function.
+
+** Standard hooks
+
+Currently two standard hooks are provided.  Each hook function is
+called with one or more parameters the first of which is the
+OrgHtmlManager object.
 
 - '~onReady~' :: This hook is run once the document is loaded, the view is
      setup and the startup section is shown.  The second parameter
@@ -714,7 +721,6 @@
      first section.  The second parameter is an object with to OrgNodes: the
      previously shown section and the current section.
 
-
 To add functions to the hooks, fill a global object ~orgInfoHooks~ with the
 function objects you need.  This is necessary, because code added via the
 ~#+STYLE:~ option lines is executed before org-info.js is loaded.
@@ -748,6 +754,50 @@
 could happen otherwise (the hook loop will overlook a member. While the hook
 loop runs in first hook first, the remove loop removes the last hook first).
 
+** Simple hooks
+
+Simple hooks are just JavaScript variables that point to particular
+functions that OrgInfo will call. There are two simple hooks thus far:
+=OrgInfoPageInsertFunction= and =OrgInfoAfterNavigateFunction=.
+
+If you assign your own functions to these variables, be sure to do so
+after OrgInfo has loaded, or they will not work. You can do so from an
+org file like this:
+
+#+begin_src org
+ #+begin_export HTML
+ <script type="text/javascript">
+ function MyInsertButtons (pageNumber)
+ {
+   [code goes here]
+ }
+
+ function MyAfterNavigate (pageNumber)
+ {
+   [code goes here]
+ }
+
+ OrgInfoPageInsertFunction = MyInsertButtons;
+ OrgInfoAfterNavigateFunction = MyAfterNavigate;
+ </script>
+ #+end_export
+#+end_src 
+
+*** OrgInfoPageInsertFunction
+
+The variable =OrgInfoPageInsertFunction= should hold a JavaScript
+function that accepts an integer identifying which OrgInfo section
+header to insert HTML into. The function should return a string
+consisting of HTML to insert into the dynamic page header that OrgInfo
+builds for each section.
+
+*** OrgInfoAfterNavigateFunction
+
+The variable =OrgInfoAfterNavigateFunction= should hold a JavaScript
+function that accepts an integer identifying which OrgInfo section has
+been switched to. The function should do whatever user-defined action
+is desired. Any return value is ignored.
+
 * How it works
 
 First of all the script is included  in the header as described in [[#setup][Setup]].  The

Diff finished.  Tue Dec 13 12:17:37 2022

Re: For your consideration: Extending org-info-js with additional hooks

[David O'Toole]

[-- Attachment #1: Type: text/plain, Size: 354 bytes --]

At Ihor's invitation, I'd like to mention that I can help maintain
org-info-js going forward. I'm not a JavaScript expert but I seem to be
doing fine with adding my hooks and figuring out how the code works. Please
let me know what I can do to help out with maintenance. I already have
copyright assignment papers on file with the FSF so that's all set.

[-- Attachment #2: Type: text/html, Size: 396 bytes --]

Re: For your consideration: Extending org-info-js with additional hooks

[Bastien Guerry]

Ihor Radchenko <yantar92@posteo.net> writes:

> Bastien, since the activity around org-info-js revived after a long
> delay, should we move the code out of worg into a separate repo?

Yes, definitely.  David, would you like to set up a new repository
with the code from the org-info-js directory here:

https://git.sr.ht/~bzg/worg/tree/master/item/code/org-info-js

You can try to excise the directoy while preserving its history,
although I would not make it mandatory for org-info-js to live in
a new, separate repository.

Once this is done, we'll see how to remove org-info-js from Worg.

Thanks!

-- 
 Bastien

Re: For your consideration: Extending org-info-js with additional hooks

[David O'Toole]

[-- Attachment #1: Type: text/plain, Size: 754 bytes --]

Ok, I will get started on this :)

On Thu, Dec 29, 2022 at 10:38 AM Bastien Guerry <bzg@gnu.org> wrote:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
> > Bastien, since the activity around org-info-js revived after a long
> > delay, should we move the code out of worg into a separate repo?
>
> Yes, definitely.  David, would you like to set up a new repository
> with the code from the org-info-js directory here:
>
> https://git.sr.ht/~bzg/worg/tree/master/item/code/org-info-js
>
> You can try to excise the directoy while preserving its history,
> although I would not make it mandatory for org-info-js to live in
> a new, separate repository.
>
> Once this is done, we'll see how to remove org-info-js from Worg.
>
> Thanks!
>
> --
>  Bastien
>

[-- Attachment #2: Type: text/html, Size: 1279 bytes --]

Re: For your consideration: Extending org-info-js with additional hooks

[Ihor Radchenko]

"David O'Toole" <deeteeoh1138@gmail.com> writes:

> Ok, I will get started on this :)

Hi,

It has been a while since the last email in this thread.
May I know if you are still interested in taking over the maintenance of
org-info-js?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>