Using the DOM to create abbr/acronym tags

[Buddy Bradley]

Browsing through the blogs that I regularly read, just about everyone who matters has adopted the habit of marking up common acronyms (GIF, PHP, XHTML, JPEG, ASP, etc.) using the <abbr> or <acronym> tag.

I'd assumed that this was being done by a natty little JavaScript function that examined the relevant bit of the page for any of an array of stored abbreviations, and then re-wrote the text to include the tag, but looking at a few source codes that doesn't appear to be the case.

So - was I right; is there a function somewhere to do this?

And if not, why not - can it be done? (my first thought is yes, but it might need to be done using CSS3 rather than Javascript).

[Buddy Bradley]

After a quick Google, I realise I've overlooked regular expression matching:

function styleAcronyms() {

    oldBodyText = document.body.innerHTML;

    findGIF = /GIF/g;

    newBodyText = oldBodyText.replace(findGIF, '<acronym title=\"Graphical Interchange Format\">$1</acronym>');

    document.body.innerHTML = newBodyText;

  }

} 

Note that I don't use regular expressions all that often, so that bit probably doesn't work, but you get the general idea.

[vgarcia]

That looks like it would work, but you'd have to put quite a few cases in there (CSS, PHP, ASP, SQL, etc). I'd think it would be easier to just put the acronyms in as you're writing the HTML. That way, everyone gets the acronym/abbreviation and its title, not just users with Javascript enabled.

[Buddy Bradley]

After a little bit of experimentation, this works:

function changeText() {

var oldBodyText = document.getElementById("content").innerHTML;

var matchIt = new RegExp(/GIF/g);

var newBodyText = oldBodyText.replace(matchIt, "<acronym title=\'Graphical Interchange Format\'>GIF</acronym>");

var matchIt = new RegExp(/PHP/g);

var newBodyText = newBodyText.replace(matchIt, "<acronym title=\'PHP: Hypertext Preprocessor\'>PHP</acronym>");

document.getElementById("content").innerHTML = newBodyText;

} 

I take your point about this method excluding those without JavaScript enabled, but:

a) That's less than 1% of browsers (according to my webstats);

b) I would argue that this function augments the content of the page rather than being essential - if you can't hover over the acronym and get the full version it doesn't totally ruin your use of the site;

c) It saves a lot of typing if you refer to those sorts of things a lot, and you only need to change your JavaScript function each time you think of a new acronym (or one is invented!) for that new acronym to appear throughout your site.

[vgarcia]

b) I would argue that this function augments the content of the page rather than being essential - if you can't hover over the acronym and get the full version it doesn't totally ruin your use of the site;

It may not ruin your use of the site, but it can limit a visitor's understanding of your content. Think of all the ambiguous or obscure acronyms in Web development alone.

c) It saves a lot of typing if you refer to those sorts of things a lot, and you only need to change your JavaScript function each time you think of a new acronym (or one is invented!) for that new acronym to appear throughout your site.

The most common use of the acronym/abbr tags I've seen is to introduce the extended meaning (title) on the first occurrence of said abbreviation on the page. After that, the abbreviation is just written out (i.e. CSS, not <abbr title="Cascading Style Sheets">CSS</abbr>), with no title. That doesn't seem like such a pain to do in HTML to me.

[momos]

Originally Posted by vgarcia

The most common use of the acronym/abbr tags I've seen is to introduce the extended meaning (title) on the first occurrence of said abbreviation on the page. After that, the abbreviation is just written out (i.e. CSS, not <abbr title="Cascading Style Sheets">CSS</abbr>), with no title. That doesn't seem like such a pain to do in HTML to me.

But often people are redirected to an anchor inside a site, with the information they want, then they would have to go and search for the abbreviation anyway, because you would only explain it the first time it occurs!?

[paulyG]

Buddy, I have been looking for something similar for some time, but also extendable so that I can add acronyms / abbreviations for multiple departments.

e.g. TPO means one thing for planners and something else for Benefits claimants.

Would be desirable to be able to link to accronym.js file that did the DOM translation.

This would allow me to add/amend the acronyms centrally. Maybe pull the contents of the js file out of a dbase?

This could of course be done server-side but:
1 why not let the client computer do the work
2 those with no js could see a link Acronyms used in this department.
3 would be easier to add that .js line to a CMS (Content Management System) than try and teach users new tags. Enforcement nightmare.

Is that feasible? Does anyone else fancy working on a solution?

Might have a look later..

[Buddy Bradley]

paulyG:

I would guess that the simplest solution would be to create multiple versions of the acronyms.js file for different areas of the site to cover your planners/claimants issue - or maybe use one .js file and a conditional check for the page name or section:

function changeText() { 

var oldBodyText = document.getElementById("content").innerHTML; 

var matchIt = new RegExp(/TPO/g); 

if (location.href == "benefits.html") {

var newBodyText = oldBodyText.replace(matchIt, "<acronym title=\'Txxx Pxxx Oxxx\'>TPO</acronym>"); // First version

} else {

var newBodyText = oldBodyText.replace(matchIt, "<acronym title=\'Tzzz Pzzz Ozzz\'>TPO</acronym>"); // Second version

} 

document.getElementById("content").innerHTML = newBodyText; 

} 

[paulyG]

Buddy,

I changed your example slightly below, and incorporated into a page with some test cases.

1 call to RegExp() commented out - was this for backwards compatability?
(Me testing on IE5 / win98)
2 added spaces to replace() and added them back into the replace text otherwise this picks up TPOL erroneously.
3 I dig the use of 'content', all my content appears in similarly named divs anyhow - else could have horrible consequences if JS fly-out menus contained magic letters like TPO.

<html> <head> <title> The planners page </title>

<script type='text/javascript' language='Javascript'>



function changeText() { 

var oldBodyText = document.getElementById("content").innerHTML; 

//var matchIt = new RegExp(/TPO/g); 

var newBodyText = oldBodyText.replace(/ TPO /g, " <acronym title=\'Tree Preservation Order\'>TPO</acronym> "); 

document.getElementById("content").innerHTML = newBodyText; 

} 

</script>



<style type="text/css">

acronym {background-color:rgb(200,200,100);} 

</style>



</head>

<body onload='javascript:changeText();'>

<div id='content'>

<h3>This is the content</h3>

<p>contains the letters TPO you should not confuse that with tpo or even etpol or ETPOL.</p>

</div>

<div>

<h3>test area</h3> 

<p><acronym title="with an acronym">WIA</acronym>.</p>

<p>A TPO outside of our main content - should not be touched.</p>

</div> </body> </html> 

I enjoyed your location sniffer, but wouldn't be necessary in my case as each dept would have its own folder, own style sheet and own acronym.js file.

What I would now like to do is:
call the onload event from .js source file
add abb for abbreviation - is that different from acronym I wonder?

Watch out - this bbs has added underscores where the word Javascript appears.

Nice one - Cheers,

Paul

[Buddy Bradley]

paulyG:

I did consider adding spaces the acronym I was looking for, but thought that this would mean that occurrences next to punctuation (like full-stops or commas) would not be picked up. I suppose it's a judgement call, really - I can't see where you would use "JPEG" in any other context, but in your example it is probably more relevant.

No reason for using RegExp rather than putting it in the replace() function call, except that I like to put everything into variables to aid in debugging.

To call the function from an external .js file, the proper way is to add the function to the window.onload event handler - can't remember how to do it off the top of my head, but I think there's an article on it on Sitepoint.

The main reason for not using <abbr> is that Internet Explorer doesn't recognise it.

[paulyG]

Originally Posted by Buddy Bradley

I did consider adding spaces the acronym I was looking for, but thought that this would mean that occurrences next to punctuation (like full-stops or commas) would not be picked up. I suppose it's a judgement call, really - I can't see where you would use "JPEG" in any other context, but in your example it is probably more relevant.

Righto. So it should be another regEx that checks for punctuation or space, can do it in php - but not so sure about js.

Originally Posted by Buddy Bradley

No reason for using RegExp rather than putting it in the replace() function call, except that I like to put everything into variables to aid in debugging.

gotcha, only your original wouldnt work for me with that line in..?

Originally Posted by Buddy Bradley

To call the function from an external .js file, the proper way is to add the function to the window.onload event handler - can't remember how to do it off the top of my head, but I think there's an article on it on Sitepoint.

Neither can I, hence the Q, will have a look around, doesn't it involve giving the calling window a name though?

Originally Posted by Buddy Bradley

The main reason for not using <abbr> is that Internet Explorer doesn't recognise it.

Just discovered that myself, its in the xhtml spec though?

Created an external.js that does 3 things, makes a acronym, abbr (!) and a span class=explanation.

The explanation could be 255 chars that explains Tree Preservation Order when written like that.

Then needs a loop to do the changes..

I can forsee some recursive problems with this though, if your first sweep changes TPO to include title='Tree Preservation Order' then your second sweep turns that into say a 255 character explanation then you're getting unexpected results..

Thinking as I write, if I just used long version of explanation for the title for the acronym, then as a previous poster said:

at the top of the page write '..you need to get a Tree Preservation Order (TPO)'
-that is kind to none-js users
-the TPO bit will have the full 255 chars explanation as a title

Then from then on just write 'when you have your TPO'.

Am rambling a little here, but this is helping me tremendously..

Paul

[stereofrog]

Just a note regarding your discussion whether to put spaces around acronym in regexp. Regexp language has a special symbol for this -- \b "word boundary".

/\bGIF\b/ matches " GIF " and " GIF," but not " GIFT ".

HTH

[Buddy Bradley]

Nice one, stereofrog - I've never used regexp in very much detail before.

[Buddy Bradley]

Originally Posted by paulyG

I can forsee some recursive problems with this though, if your first sweep changes TPO to include title='Tree Preservation Order' then your second sweep turns that into say a 255 character explanation then you're getting unexpected results..

I suppose it depends on how anal you want to get with using tags in accordance with their semantic meaning. Technically you should only be using the <acronym> tag to expand acronyms ("Tree Preservation Order"), but there's nothing really to stop you making the title attribute into a longer description, even if it doesn't quite conform to the specified meaning of an <acronym>.

[paulyG]

Originally Posted by Buddy Bradley

I suppose it depends on how anal you want to get with using tags in accordance with their semantic meaning. <acronym>.

Just so, Buddy.. wait till you see something called the UK local authorities '6 year local plan' takes anal to new lows..

I want the markup to be accurate, yet js users to get added value.

As the abbr tag is not supported in IE it is ipso facto worthless then.

Y'see I had in mind 3 scenarios:
acronym - like TPO [title=Tree Preservation Order]
abbr - like Planning dept [title=Planning and development department, Development control section]
explanation - Tree Officer [title=Qualified local authority employee empowered to enforce Tree Preservation Orders]

I will stick to acronym for now - though stereofrogs' -- \b suggestion is magic, then consider creating a <span> for expanding the likes of Tree Officer, and will reluctantly drop <abbr>

Paul

[Buddy Bradley]

You could get really silly/detailed (delete as applicable) and add an <explanation> tag to your custom DTD...

[paulyG]

In case anyone else can use it.. here's a way of applying a glossary to existing pages without having to do too much work. include an external.js link file.

This is the contents of acronym.js which you can fill up with the acronyms and explanations for a department/website.

Have probs finding multi-dimension arrays in js, but this works, also had a bit of type juggling cludge to get theReg (reg expression) to work..

acronym.js:

function changeText() { 

var theBodyText = document.getElementById("content").innerHTML; 

var acro= new Array("TPO","HO","PO");

var newText= new Array("TPO=Tree Preservation Order, an official notice protecting a tree from being pruned without the permission of the local authority Tree Officer.","Housing Officer","Planning Officer");



var counter=0;



do {

var theReg="/\\b"+acro[counter]+"\\b/g";

theBodyText = theBodyText.replace(eval(theReg), "<acronym title=\'" + newText[counter] + ".\'>" + acro[counter] + "</acronym>"); 

counter++;

} while(counter<acro.length);

document.getElementById("content").innerHTML = theBodyText; 

} 

Heres a test/example file planning.html full of usual councilspeak.. note it only transforms text in a div whose id is 'content'.

<html> <head> <title> The planners page </title>
<script type='text/javascript' src='acronym.js'></script>
<style type="text/css">
acronym {color: red; cursor:hand;}
</style>

</head>
<body onload='javascript:changeText();'>
<div id='content'>
<p>At the top of the page write Tree Preservation Order (TPO) fully expanded. A well written page would include an full explanation of TPOs in any case. </p>
<p>Please call the Planning dept and speak to your PO, not your HO for more information about TPO's.</p>
</div> </body> </html>

If you are doing backend stuff you ought to be able to get your arrays of acronyms sucked out of a database, and at the same time create a html page full of all the acronyms that can be linked to with <noscript> tags.

TODO
initialise the changeText function from inside the external.js
find out about multidimensional arrays in js
I found a new tag <dfn> which could be used to define specialised terms which are NOT acronyms, which with the above should become glossary.js with any luck.

Paul

[paulyG]

Found how to initialise changeText from inside the acronym.js file along with DOM sniffer here on this sitepoint js discussion.

Getting there.

acronym.js now looks like:

var W3CDOM = (document.createElement && document.getElementsByTagName);



function changeText() { 

if (!W3CDOM) return;

var theBodyText = document.getElementById("content").innerHTML; 

var acro= new Array("TPO","HO","PO");

var newText= new Array("TPO=Tree Preservation Order, an official notice protecting a tree from being pruned without the permission of the local authority Tree Officer.","Housing Officer","Planning Officer");

var counter=0;



do {

var theReg="/\\b"+acro[counter]+"\\b/g";

theBodyText = theBodyText.replace(eval(theReg), "<acronym title=\'" + newText[counter] + ".\'>" + acro[counter] + "</acronym>"); 

counter++;

} while(counter<acro.length);

document.getElementById("content").innerHTML = theBodyText; 

} 

window.onload=changeText; 

and in the test file remove the onload event now.

This is important to me as not all sections will have glossaries, so the external.js link will not be written by my meta-data management system.

[adios]

Here's an amusing colloquy on all things abbrevio-acronymical...

Also a nice app here, with more considerations. This too.

This arguably should be implemented on the server; it's one thing to add behaviors in the browser, another to add markup that should have been there in the first place. Some blog software does this automatically via macro.

That said - interesting concept.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" 
    "http://www.w3.org/TR/html4/loose.dtd">

<html>
<head>
<title>untitled</title>
<style type="text/css">

#content1, #content2 {
	font: normal 13px "comic sans ms";
	color: darkgreen;
	padding: 0 8px;
	margin: 4px;
	border: 1px olive dashed;
	background: ghostwhite;
}
#content2 {
	font: normal 14px "comic sans ms";
	letter-spacing: .08em;
	color: darkred;
}
abbr, acronym {
	font-weight: bold;
	color: olivedrab;
	border-bottom: 1px dotted #000;
	cursor: help;
	position: relative; /* ie....wtf??? */
}

</style>
<script type="text/javascript">

//=============================================================================>

var abbrs = {
		TPO: "TPO=Tree Preservation Order, an official notice protecting a tree from being pruned without the permission of the local authority Tree Officer." ,
		HO: "Housing Officer" ,
		PO: "Planning Officer" ,
		RL: "Raving Loony" ,
		CRL: "Complete ¤¤¤ Raving Loony ¤¤¤"
	    }

//=============================================================================>

var els = [ 'content1' , 'content2' ];

//=============================================================================>

onload = function()
{
	if (!document.getElementsByTagName)
		return;
	var tag = (window.createPopup) ? 'acronym' : 'abbr'; 
	var abbr, oRegExp, oMatch, el, elHTML, which = 0;
	while (el = document.getElementById(els[which++]))
	{
		elHTML = el.innerHTML;
		for (abbr in abbrs)
		{
			oRegExp = new RegExp('\\b(' + abbr + ')(s?)\\b', 'g');
			elHTML = elHTML.replace(oRegExp, '<' + tag + ' title="' + abbrs[abbr] + '">$1</' + tag + '>$2'); 
		}
	el.innerHTML = elHTML;
	}
}

//=============================================================================>

</script>
</head>
<body>
<div id="content1">
<p>At the top of the page write Tree Preservation Order (TPO) fully expanded. A well written page would include an full explanation of TPOs in any case. </p>
<p>Please call the Planning dept and speak to your PO, not your HO for more information about TPOs.</p>
<p>If you are a certified RL, please call the authorities and bother them, we're quite busy, actually.</p>
</div>
<div id="content2">
<p>
Yes - I once <em>was</em> a RL...until I entered therapy. Thank Goodness. Now I'm a CRL.<img src="http://www.sitepoint.com/forums/images/smilies/xeye.gif" /><img src="http://www.sitepoint.com/forums/images/smilies/xeye.gif" /><img src="http://www.sitepoint.com/forums/images/smilies/xeye.gif" />
</p>
</div>
</body>
</html>

Needs a lot of work; I'd modify the regex to match plurals ('TPOs') and some other wrinkles. Might use spans. Might not.

cya, adios

Edit:

Fixed plurals, few other items...

[paulyG]

I like the idea of this solution for dealing with legacy documents - some kept in Lotus Notes and I cannot pass all of it through back end scripts.

This means in the thousands of legacy meeting agendas and minutes we have we can create links to, for example, a named councillors webpage from a glossary.

I dig what you say adios, and no doubt the correct markup will be added when everything is switched to some clever cms, but in the meantime I keep finding uses for this script..

Picking up plurals - good point.

approaching a final version now - got mulitdimensional arrays working, and added type 3 - a link.

The main thing I feel wrong about is that screen readers will not see anything at all.

I see you are using the <abbr> tag even though IE doesnt support it. Thats not going to be real world enough for us.. I may abuse the <dfn> tag or just use a span.. the way it is set up now I can change the tag used in a single file.. so when abbr is on 90% of our users browsers I will switch it over.

Anyhow this works for those that want it:
(the Gl array would be inserted when the page is built, depending on which section this is - though you could include it in the acronym.js file)

<html> <head> <title> The planners page </title>

<script type='text/javascript'>
var Gl=[[1,"TPO","Tree Preservation Order"],
[1,"HO","Housing Officer"],
[1,"PO","Planning Officer"],
[2,"Conservation Area","An area protected by law, you should see the local plan to see which areas are protected"],
[3,"Countryside","http://www.countryside.gov.uk"]]
</script>



<script type='text/javascript' src='acronym.js'></script>
<style type="text/css">
acronym {color: red; cursor:hand;} 
dfn {color:blue;cursor:hand;font-style:normal;}
</style>
</head>
<body>
<div id='content'>
<p>At the top of the page write Tree Preservation Order (TPO) fully expanded.  A well written page would include an full explanation of TPOs in any case. </p>
<p>If you live in the Countryside and the tree is located in a Conservation Area then speak to your PO, not your HO for more information about TPO's.</p>
</div> </body> </html>

Then call this from all pages

function changeText() { 
if (!document.getElementById) return;

var theBodyText = document.getElementById("content").innerHTML; 
var counter=0;
var tagname="";
do {
  var theReg="/\\b"+Gl[counter][1]+"\\b/g";
  //detect type of tag to display
  if (Gl[counter][0]<3){
 // send a tag to the dom
  Gl[counter][0]==1?tagName="acronym":tagName="dfn";

   theBodyText = theBodyText.replace(eval(theReg), "<" +tagName+ " title=\'" + Gl[counter][2] + ".\'>" + Gl[counter][1] + "</"+ tagName +">"); 

   }else{
   theBodyText = theBodyText.replace(eval(theReg), Gl[counter][1].link(Gl[counter][2])); 
   }
counter++;
} while(counter<Gl.length);
document.getElementById("content").innerHTML = theBodyText; 
} 
window.onload=changeText;

TODO
add support for plurals
create optional hidden div or pop win showing 'all acronyms and abbreviations in this section'
Get the array to sort in alphabetical order
Write <noscript> link to html version of glossary

Can see the error of my ways with setting the regexp now, thanks guys.

Thanks for the help and ideas.

Paul

[adios]

I see you are using the <abbr> tag even though IE doesnt support it.

Look closer:

var tag = (window.createPopup) ? 'acronym' : 'abbr';

That's a sniffer for MSIE (now that Opera 7+ has document.all). I used it as a quick alternative to a span wrapper, as in one of the links I posted, although I hinted that that approach might be more semantic.

Don't use eval(), nested arrays, double-quote delimeters (necessitating the escapes). The code I posted also lets you specify which element containers you'd like to target.

Be glad to assist more, but only if you're interested.

adios

[DHTML Kitchen]

Originally Posted by paulyG

1 why not let the client computer do the work
2 those with no js could see a link Acronyms used in this department.
3 would be easier to add that .js line to a CMS (Content Management System) than try and teach users new tags. Enforcement nightmare.

Is that feasible?

Not a good idea.

1 javascript is slow
2 you're excluding disabled users like retards, screen readers, and bots who read the acronym/abbr title, usurping one of the major benefits of these elements: accessibility
3 It would be easier to do it on the server. Write a servlet filter whose result would be cached. This would be faster. There's probably a good way to do it using XSLT, too.

Just because you can do it doesn't mean it's a good idea.

[paulyG]

Originally Posted by DHTML Kitchen

Not a good idea.

1 javascript is slow

Is there an output buffer for js then? like php ob flush kinda thing?

Originally Posted by DHTML Kitchen

2 you're excluding disabled users like retards, screen readers, and bots who read the acronym/abbr title, usurping one of the major benefits of these elements: accessibility

3 It would be easier to do it on the server. Write a servlet filter whose result would be cached. This would be faster. There's probably a good way to do it using XSLT, too.

Good point but as I said earlier, when we move our site into a new cms, writing the tags on the fly can be done.

Meanwhile this solution helps me to get togther a dbase table containing all the acronyms and definitions (that dozens of others will be creating) - its not just a matter of getting the code right.

I like your idea of a servlet filter do you mean a Java servelet? What will I have to have installed to have that then?

[paulyG]

Adios,

Originally Posted by adios

Look closer:

var tag = (window.createPopup) ? 'acronym' : 'abbr';

That's a sniffer for MSIE (now that Opera 7+ has document.all). I used it as a quick alternative to a span wrapper, as in one of the links I posted, although I hinted that that approach might be more semantic.

Yes, but the options on the ternary operator were the wrong way round which didnt work in IE5 and this threw me for a while, so I continued with the original idea..

Originally Posted by adios

Don't use eval(), nested arrays, double-quote delimeters (necessitating the escapes). The code I posted also lets you specify which element containers you'd like to target.

I saw the error of my ways with the eval() but whats wrong with nested arrays? I read quite a bit about them but saw no specific warnings?

[paulyG]

Droogs..

This DOM glossary can take 3 types of definition:

-acronym (with a title)
-dfn (ditto)
-a href link to a resource

As has been said, you should really do this on the server, but if like me you can't do that at the moment then try this if you can add an array of terms into your page.

This now catches plurals of words or terms, and negates the need for eval() I found out more about regexps at http://www.regular-expressions.com/javascript.html

function changeText() { 

if (!document.getElementById) return;

var counter=0;

var tagname=""

var theBodyText = document.getElementById("content").innerHTML; 

var theReg;

do {

     theReg = new RegExp('\\b(' + Gl[counter][1] + 's?)\\b','g');

//detect type of tag to display

    if (Gl[counter][0]<3){

// add a tag into the DOM

    Gl[counter][0]==1?tagName="acronym":tagName="dfn";

    theBodyText = theBodyText.replace(theReg, '<' +tagName+ ' title="' + Gl[counter][2] + '">$1</'+ tagName +'>'); 



    }else{

    theBodyText = theBodyText.replace(theReg, Gl[counter][1].link(Gl[counter][2])); 

    }

counter++;

} while(counter<Gl.length);

document.getElementById("content").innerHTML = theBodyText; 

} 

window.onload=changeText; 

Appypollylogies for the single and double quotes, but when I know it all has to be quoted and tested again in php I cant be arsed doing it now.. now how fast is it...

Paul