Merge pull request #209 from jonathanvanschenck/feature/add-api

Add API for use by other plugins

.all-contributorsrc

@@ -187,6 +187,15 @@
         "code",
         "translation"
       ]
+    },
+    {
+      "login": "jonathanvanschenck",
+      "name": "jonathanvanschenck",
+      "avatar_url": "https://avatars.githubusercontent.com/u/44685047?v=4",
+      "profile": "https://github.com/jonathanvanschenck",
+      "contributions": [
+        "code"
+      ]
     }
   ],
   "contributorsPerLine": 7,

docs/Plugin API.md

@@ -0,0 +1,54 @@
+# Plugin API
+`obsidian-bible-reference` provides a globally accessible API which other plugins and tools can use to query and render bible verses. Many thanks to [obsidian-dataview](https://github.com/blacksmithgu/obsidian-dataview) for this idea. This API is accessible either via:
+
+```js
+// Either:
+const OBRAPI = window.app.plugins.plugins["obsidian-bible-reference"].api;
+
+// Or:
+const OBRAPI = window.BibleReferenceAPI;
+```
+
+## Functions
+
+### `BibleReferenceAPI#queryVerses()`
+Lookup verses for a given reference, with optional overrides for default parameters.
+```
+async queryVerses(query: string, opts?: BibleReferencePluginSettings): Promise<VerseSuggesting | null>
+```
+#### Example
+From the developer console (ctrl+shift+i):
+```
+(await window.BibleReferenceAPI.queryVerses("John 3:16", { bibleVersion: "ESV" })).allFormattedContent;
+// Returns:
+// ' [!bible] [John 3:16 - ESV](https://bolls.life/ESV/43/3/)\n' +
+// '> 16. “For God so loved the world,  that he gave his only Son, that whoever believes in him should not perish but have eternal life.\n\n'
+```
+
+## Using With Other Plugins
+If you are using [SilentVoid13's templater](https://github.com/SilentVoid13/Templater) -- you can create a template for "bible study notes" like as follows:
+
+```
+<%*
+const BRAPI = window.BibleReferenceAPI;
+
+const reference = await tp.system.prompt("Verses","", true);
+const version = await tp.system.prompt("Version",BRAPI.settings.bibleVersion);
+
+const verses = await BRAPI.queryVerses(reference, { bibleVersion: version });
+
+if ( !verses  ) throw new Error("Cannot parse verses");
+_%>
+
+<% tp.file.rename("Notes on " + reference.replace(/:/g,".")) _%>
+---
+creation: <% tp.date.now("YYYY-MM-DD") %>
+text: <% reference %>
+---
+# <% "Notes on: " + reference %>
+
+## Text
+<% verses.allFormattedContent -%>
+
+## Notes
+```

src/api/PluginAPI.ts

@@ -0,0 +1,41 @@
+import { BibleReferencePluginSettings } from '../data/constants'
+import { VerseSuggesting } from '../verse/VerseSuggesting'
+import { verseMatch } from '../utils/verseMatch'
+import { getSuggestionsFromQuery } from '../utils/getSuggestionsFromQuery'
+
+/**
+ * A subset of the plugin's API, to be exposed globally for programmatic use
+ *
+ * Available via: `app.plugins.plugins['obsidian-bible-reference'].api` or globally as (i.e. on window) `BibleReferenceAPI`
+ *
+ * Many thanks to `obsidian-dataview` for the implementation reference
+ */
+export class BibleReferenceAPI {
+  settings: BibleReferencePluginSettings
+
+  public constructor(
+    public app: App,
+    public settings: BibleReferencePluginSettings
+  ) {
+    this.settings = settings;
+  }
+
+  private mergeSettings(opts?: BibleReferencePluginSettings): BibleReferencePluginSettings {
+    return opts
+      ? Object.assign(Object.assign({}, this.settings), opts)
+      : Object.assign({}, this.settings);
+  }
+
+  /**
+   * Lookup verses from a string
+   *
+   * Adapted from `VerseLookupSuggestModal#getSuggestions`
+   *
+   * @param {String} query - the query string (e.g. 'Luke 1:1')
+   * @param {BibleReferencePluginSettings?} [opts=undefined] - optional overrides for any settings
+   */
+  async queryVerses(query: string, opts?: BibleReferencePluginSettings): Promise<VerseSuggesting | null> {
+    if ( !verseMatch(query) ) return null;
+    return getSuggestionsFromQuery(`${query}`, this.mergeSettings(opts)).then(verseArray => verseArray[0] || null);
+  }
+}

src/main.ts

@@ -17,11 +17,13 @@ import { FlagService } from './provider/FeatureFlag'
 import { EventStats } from './provider/EventStats'
 import { getBibleVersion } from './data/BibleVersionCollection'
 import { pluginEvent } from './obsidian/PluginEvent'
+import { BibleReferenceAPI } from './api/PluginAPI'
 
 export default class BibleReferencePlugin extends Plugin {
   settings: BibleReferencePluginSettings
   verseLookUpModal: VerseLookupSuggestModal
   verseOfDayModal: VerseOfDayModal
+  api: BibleReferenceAPI
   private cachedVerseOfDaySuggesting: {
     verseOfDaySuggesting: VerseOfDaySuggesting
     ttl: number
@@ -41,6 +43,10 @@ export default class BibleReferencePlugin extends Plugin {
     this.addVerseLookupCommand()
     this.addRibbonButton()
 
+    this.api = new BibleReferenceAPI(this, this.settings);
+    // Register the api globally
+    (window['BibleReferenceAPI'] = this.api) && this.register(() => { delete window['BibleReferenceAPI'] });
+
     const flagService = FlagService.getInstace()
     await flagService.init('obsidian-app')
     if (FlagService.instance.isFeatureEnabled('vod')) {