Autolinking Javascript Plugin

Lev Eliezer Israel edited this page Jun 3, 2015 · 6 revisions

This project is now in process

See Sefaria Auto Linker

We would like to offer third party websites and bloggers a simple Javascript Plugin which would automatically turn any citations to Jewish texts found on a page into links which could either bring up a modal window to display the text on site, or a link out to the text on Sefaria.

1. Scan the current page for any citations that Sefaria understands, wrap them in a tag.

Sefaria currently undergoes a similar process for creating links from inline text citations. The code this is here: https://github.com/blockspeiser/Sefaria-Project/blob/master/static/js/util.js#L1324

This technique creates one gigantic regular expression out of the full list of known text titles. For development purposes, an up-to-date list can be obtained from our API here: http://www.sefaria.org/api/index/titles. When we move to serve this plugin from production, we can dynamically include this data in the body of the script.

Applying a regular expression to wrap found text across and entire DOM tree reliably can be tricky. The Sefaria Source Sheet builder makes use https://github.com/padolsey/findAndReplaceDOMText

1.1 Dealing with Ibid

We will also need a way to link et. al.-style links and Ibid style links, such as "(20:40)" or (Ibid 2:34), which need to be interpreted as a reference to the last book crawled by the script.

1.5 Make citations link out to Sefaria

Turning full citations into outbound links to Sefaria should be easy -- any valid citation can be used as a Sefaria URL.

2. Display text in a modal window on site

With a valid citation you can call http://www.sefaria.org/api/texts/:citaton to retrieve any available text. When a response is available in the text and/or he fields, they can be used to populate a modal window anchored to the citation show the text. A link in the modal window can also be available to bring users from the preview to our site.

You'll want to use the parameters context=0&commentary=0 on this API call. Full documentation for our API can be found on our API Documentation page.

Challenges

  1. Playing safe with host Javascript - don't break anyone's page!
  2. Playing safe with host CSS - make sure all elements are styled as desired without effect other elements on the page and without being affected by any CSS that may be on a host page.
  3. Performance - will the scanning process add too much latency to the host page?