|
en_PublicAPI
Documentation of the public API of Hyphenator.js
Public APIHyphenator.js provides an API that allows webdevelopers to customize behaviour and look of Hyphenator.js Methods and fields that are accessible (public) are defined in the following. FieldslanguagesObject that holds a key-value pairs, where key is the language and the value is the language-object loaded from (and set by) the pattern files. The language object holds the following members:
And optionally (or after prepareLanguagesObj() has been called):
Methodsvoid Hyphenator.config(object settings)The config-method gives you a wide range of possibilities to adapt behaviour and look of Hyphenator.js. To use the config method, you'll have to define an object that holds at least one of the following keys. The values for the associated keys must be of the defined type:
For detailed description of each property see below. Example 1 – defining a named objectDefine a special object hyphenatorSettings and pass it to Hyphenator.config(): <script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
var hyphenatorSettings = {
hyphenchar : '|',
urlhyphenchar : '|'
};
Hyphenator.config(hyphenatorSettings);
Hyphenator.run();
</script>Example 2 – defining an anonymous object<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
Hyphenator.config({
hyphenchar : '|',
urlhyphenchar : '|'
});
Hyphenator.run();
</script>properties classname and donthyphenateclassnameBy default Hyphenator.js looks for elements with a classname hyphenate. Instead of adding this classname to each element that you like to be hyphenated, you'll probably prefer using an existing classname (e.g. content) or define an other name. As of version 2.0.0 you can redefine the classname that marks elements that should not be hyphenated (defaults to donthyphenate). Example 3 – redefining a classname<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
Hyphenator.config({
classname : 'content',
donthyphenateclassname : 'header'
});
Hyphenator.run();
</script>property minwordlegthBy default Hyphenator.js only hyphenates words with a minimum of 6 letters. You can change this values. The higher the value, the slower the script; the lower the value, the better the result. Example 3 – redefining minwordlegth<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
Hyphenator.config({minwordlegth : 8});
Hyphenator.run();
</script>property hyphencharBy default Hyphenator.js puts the soft hyphen in each possible hyphenation point. Soft hyphens are invisible unless the line is breaked. To check hyphenation you can set hyphenchar to a visible character (such as the pipe '|'). Example 4 – redefining hyphenchar<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
Hyphenator.config({hyphenchar : '|'});
Hyphenator.run();
</script>property urlhyphencharWhen processing URLs and email-adresses a hyphen would invalidate the text. Thus, by default, a zero width space is used instead. You can change this character, too. Example 5 – redefining urlhyphenchar<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
Hyphenator.config({urlhyphenchar : '·'});
Hyphenator.run();
</script>property displaytoggleboxIf you want the user to be able to turn off an back on hyphenation, you can display the 'toggleBox' - by default a small light-grey button in the top right corner of the screen. Example 6 – setting displaytogglebox to true<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
Hyphenator.config({displaytogglebox : true});
Hyphenator.run();
</script>property toggleboxThe small light-grey button provided by Hyphenator.js can be replaced by any other element that fits the design of your website. To do so you'll have to define a function that takes an argument of type boolean. Call the function Hyphenator.toggleHyphenation() to toggle hyphenation. Don't forget to set displaytogglebox! Example 7 – redefining togglebox<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
var hyphenatorSettings = {
displaytogglebox : true,
togglebox : function (hyphenate) {
var myelem = document.getElementById('hyphenationbutton');
if (hyphenate) {
myelem.style.color = '#00FF00';
myelem.onclick = Hyphenator.toggleHyphenation;
} else {
myelem.style.color = '#FF0000';
myelem.onclick = Hyphenator.toggleHyphenation;
}
}
};
Hyphenator.config(hyphenatorSettings);
Hyphenator.run();
</script>
[...]
<div id="hyphenationbutton">toggle hyphenation</div>
[...]property remoteloadingHyphenator.js automatically loads the pattern files for each language, if they are available. Alternatively you can load the pattern files manually and disable the remote loading mechanism. It's very important, that pattern files are loaded AFTER Hyphenator.js Example 8 – setting remoteloading to false<script src="Hyphenator.js" type="text/javascript"></script>
<script src="patterns/en.js" type="text/javascript"></script>
<script type="text/javascript">
Hyphenator.config({remoteloading : false});
Hyphenator.run();
</script>property enablecacheHyphenator caches words that have been hyphenated to fasten execution. If for some reason (memory?) you want to disable caching, you can do it. Example 9 – setting enablecache to false<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
Hyphenator.config({enablecache : false});
Hyphenator.run();
</script>property onhyphenationdonecallbackHyphenator.js calls the function onhyphenationdonecallback() when hyphenation is complete. This function is empty by default. You can redefine it to execute any code upon completing hyphenation. Example 10 – redefining onhyphenationdonecallback<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
var hyphenatorSettings = {
onhyphenationdonecallback : function () {
alert('Hyphenation done');
}
}
Hyphenator.config(hyphenatorSettings);
Hyphenator.run();
</script>property onerrorhandlerIn some cases, Hyphenator.js calls a method called error(). By default this method displays an alert with the error message. This may not be suitable for deploymet, thus you can redefine the error()-method. Example 11 – redefining onerrorhandler<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
var hyphenatorSettings = {
onerrorhandler : function (e) {
//do nothing
}
}
Hyphenator.config(hyphenatorSettings);
Hyphenator.run();
</script>property intermediatestateWhen a paragraph is hyphenated, the browser does a reflow of the layout, which you might like or not. By default Hyphenator.js hides elements when they are hyphenated an makes them visible, when hyphenation is done. You can change this behaviour in such a manner, that elements sty visible. Example 12 – redefining intermediatestate<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
Hyphenator.config({intermediatestate : 'visible'});
Hyphenator.run();
</script>property selectorfunctionThis property is one of the most interesting, since it changes the way, Hyphenator.js selects the elements to be hyphenated. By default Hyphenator.js looks for all elements with classname='hyphenate'. If you declare a selector function, wich has to return a HTMLNodeList, you can hyphenate any arbitrary element your function returns. selectorfunction is really powerful, if it's used with a JavaScript-Framework like jQuery (see example), prototype or similar. These frameworks include functionalities to adress elements by CSS-selectors. Example 13 – defining selectorfunction<script src="jquery.js" type="text/javascript"></script>
<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
var hyphenatorSettings = {
selectorfunction: function () {
return $('p');
}
};
Hyphenator.config(hyphenatorSettings);
Hyphenator.run();
</script>void Hyphenator.run()Calling this method invokes hyphenation. Example<script src="Hyphenator.js" type="text/javascript"></script> <script type="text/javascript"> Hyphenator.run(); </script> void Hyphenator.addExceptions(string language, string words)Adds exceptions on a page-wide base. Use this to correct words that would be wrongly hyphenated by the patterns. Indicate the language in the first argument. The second argumet takes a comma separated string (WITH spaces) of prehyphenated words. For Hyphenator.js >=2.0.0: If the first argument is an empty string, the exception is 'global', not for a specific language, but for all languages. Example<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
Hyphenator.addExceptions('en','man-u-script, man-u-scripts');
Hyphenator.addExceptions('','FORTRAN');
Hyphenator.run();
</script>On this page, the word FORTRAN will not be hyphenated at all. mixed Hyphenator.hyphenate(mixed target, string lang)Hyphenates the target. If the target is a string, the hyphenated string is returned. If the target is an DOM-Object (an element), it will be hyphenated directly (as are its children). The patterns indicated by the 2nd attribute (lang) have to be loaded; if not, an error is thrown. Example<script src="Hyphenator.js" type="text/javascript"></script>
<script src="patterns/en.js" type="text/javascript"></script>
<script type="text/javascript">
alert(Hyphenator.hyphenate('Hyphenation is cool!', 'en'););
</script>bool Hyphenator.isBookmarklet()Returns true if Hyphenator.js has been called by a bookmarklet. void Hyphenator.toggleHyphenation()Calls Hyphenator.removeHyphenationFromDocument() if the state of Hyphenator is 3 or calls Hyphenator.hyphenateDocument() if the state is 4. Use his function when implementing your own toggleBox. Example – using Hyphenator.toggleHyphenation()<script src="Hyphenator.js" type="text/javascript"></script>
<script type="text/javascript">
var hyphenatorSettings = {
displaytogglebox : true,
togglebox : function (hyphenate) {
var myelem = document.getElementById('hyphenationbutton');
if (hyphenate) {
myelem.style.color = '#00FF00';
myelem.onclick = Hyphenator.toggleHyphenation;
} else {
myelem.style.color = '#FF0000';
myelem.onclick = Hyphenator.toggleHyphenation;
}
}
};
Hyphenator.config(hyphenatorSettings);
Hyphenator.run();
</script>
[...]
<div id="hyphenationbutton">toggle hyphenation</div>
[...]
|
Sign in to add a comment
