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

["David O'Toole" <deeteeoh1138@gmail.com>]

[-- 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