Monday, May 9, 2016

Oracle Documentation permalink creation

Tim Hall of ORACLE-BASE spoke for a lot of people when he (yet again) wrote about Oracle Documentation links changing all the time. There exists a method for a more permanent link to Oracle Documentation, but it can be a hazzle to create such a permalink involving manually searching HTML code of the doc source (see my comment to Tim's blog post.)


Then I thought that this manual creation of permalink probably could be automated and started to research a bit. The answer is yes, you can get help with a bookmarklet.



The thing is you need to create a URL of the form:

http://www.oracle.com/pls/topic/lookup?ctx=dbVVR&id=DOCID

VVR is version and release, for example 121 for version 12.1.
DOCID is an ID in form AAAAA99999, for example SQLRF01702.

The DOCID can be found if you view the source HTML of the documentation page, find the anchor you want, and read the ID of the anchor. So to automate, I needed something to isolate the anchors in question, find the ID, and create the permalink URL.

I searched around and found a nice little Show Anchors Bookmarklet. Useful in itself, but also fairly easy to rewrite into a specialized version that works specifically for Oracle Documentation. So I rewrote it ;-)

UPDATE: Now it works on documentation versions 11.1, 11.2 and 12.1 (at least those are tested ;-).

To use it, what you do is you create a new bookmark in your browser. The bookmark Name you can give what you want, something like "OraDoc LinkMaker" or similar. The bookmark URL you copy and insert this javascript code:

javascript:(function(){function ls(u,c){var h=document.getElementsByTagName("head")[0];var s=document.createElement("script");s.src=u;var d=false;s.onload=s.onreadystatechange=function(){if(!d&&(!this.readyState||this.readyState=="loaded"||this.readyState=="complete")){d=true;c();s.onload=s.onreadystatechange=null;h.removeChild(s);}};h.appendChild(s);}var $;var ver=location.href.match(/docs.oracle.com.*(\/|\.)([0-9]{3})\//)[2];var loc="http://www.oracle.com/pls/topic/lookup?ctx=db"+ver+"&id=";function a(e,n){$('<a href="'+loc+n+'" title="'+loc+n+'"><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABGdBTUEAAK/INwWK6QAAABl0RVh0U29mdHdhcmUAQWRvYmUgSW1hZ2VSZWFkeXHJZTwAAAGdSURBVDjLpVMxa8JAFL6rAQUHXQoZpLU/oUOnDtKtW/MDBFHHThUKTgrqICgOEtd2EVxb2qFkKTgVChbSCnZTiVBEMBRLiEmafleCDaWxDX3w8e7dve+7l3cv1LZt8h/jvA56vV7DNM20YRgE/jyRSOR+ytvwEgAxvVwui/BF+LTvCtjNwKvj/X8CbgXPOHMEZl559HsTu93uPQi7jBiNRgMEx8PR0GIxRB+y2eze2gqQeAXoSCaqqu5bpsWIdyzGvvRrBW7rdDo2I6ZSKeq7B8x0XV/bwJWAJEnHSMwBDUEQWq5GfsJthUJhlVuv11uckyiGgiH2RWK73RYRb2cymbG7gnK5vIX9USwWI1yAI/KjLGK7teEI8HN1TizrnZWdRxxsNps8vI3YLpVKbB2EWB6XkMHzgAlvriYRSW+app1Mpy/jSCRSRSyDUON5nuJGytaAHI/vVPv9p/FischivL96gEP2bGxorhVFqYXDYQFCScwBYa9EKU1OlAkB+QLEU2AGaJ7PWKlUDiF2BBw4P9Mt/KUoije+5uAv9gGcjD6Kg4wu3AAAAABJRU5ErkJggg%3D%3D" /></a>').insertBefore(e);}ls("http://ajax.googleapis.com/ajax/libs/jquery/1.3/jquery.min.js",function(){$=jQuery;$("[id]:not(input[type='hidden'])").each(function(i){if(this.id.match(/^[A-Z]{5}[0-9]{5}$/)){a(this,this.id);};});});})()

(If it's tricky to copy-paste from this long line, you can grab it from this text file instead.)

Now you have a bookmarklet that when pressed can change the content of the documentation webpage you are looking at.

So for example I am on a part of the doc for SELECT, and I press my bookmarklet:


Now all anchors on the page that are of the form AAAAA99999 will show a small anchor icon (not just the visible part but on the entire page) and the anchor icon will be a link containing the permalink URL:


Now it is easy to right-click and copy link address:


The result is: http://www.oracle.com/pls/topic/lookup?ctx=db121&id=SQLRF56467

And then that link can be used in a blog post or PL/SQL challenge quiz or wherever you need a more permanent link to Oracle Documentation.

Hopefully this is useful to at least some - if not then it was at least a bit of fun fiddling with JQuery ;-)

2 comments:

  1. Hi.

    That's great. I've added it to my browser. :) I was using the show anchors plugin before, but this is obviously a lot more relevant for the Oracle links.

    One point, the copy/paste from your site adds some extra stuff on to the string, even if you display it as a file in the browser. You have to save it as a file and open the file to get the clean version of the text.

    I figure it's one of those plugins that automatically adds a credit on to any text copied from your site. :)

    Cheers

    Tim...

    ReplyDelete
    Replies
    1. Thanks for the heads-up on the clean text, Tim.

      Actually, it was Blogger that recognized within the script code there was something that looked like a relative URL and automatically prepended "http://www.blogger.com/" to that bit of the code ;-)

      I've HTML encoded the source code - it looks like it works now.

      /Kim

      Delete