StyleGuard Pro JavaScript API Guide

Note: This guide uses the following StyleGuard Pro server address: https://dev.styleguard.com. This is an example and can usually be used during development, but needs to be changed to a production StyleGuard Pro server, before the solution can be put into production.

Common JavaScript code block

The following block of JavaScript code is part of several JavaScripts further down. For consistency, the code block is shown and described only here and it is represented by the following placeholder in later JavaScripts: [insert code from earlier in this document].

1. Add the below code into your HTML files under the header section/tag
2. Replace parentAppIdProvidedByStyleGuard with value provided by StyleGuard Pro.
3. Replace "%dynamicParentAppVersion%"with the appropriate version of the parent application.
   var lingofy = {}; lingofy.settings = {}; lingofy.settings.baseUrl = "https://dev.styleguard.com/tansaclient/"; lingofy.settings.clientExtenstionJs = "tansa4ClientExtensionSimple.js"; lingofy.settings.parentAppId = "parentAppIdProvidedByStyleGuard"; lingofy.settings.parentAppVersion = "%dynamicParentAppVersion%";

Notes:

parentAppId: Use the value provided for you by StyleGuard Pro.

parentAppVersion: This should reflect the version of the parent system (editor or CMS system) at any given time, so that error logs and other logs reflect the version of the system being used, making debugging and tracking easier. Example value: "1.0.6.265".

Changes to your HTML-files:

To add the StyleGuard Pro menus, use the below code.

Override StyleGuard Pro Text Manipulation JavaScript Functions
selectText, replaceText, getTexts etc.

Changes to your HTML Page:

• Add the below JavaScript Code block in HTML page to initialize the StyleGuard Pro settings object.
  <script type="text/javascript"> [insert code from earlier in this document] function checkAndLoadMenuFromServer(){ var tansaLoaderScript = document.getElementById("tansaLoaderScript"); if(!tansaLoaderScript){ var script = document.createElement('script'); script.src = lingofy.settings.baseUrl + 'initTansaLoader.js' + '?' + new Date().getTime(); document.querySelector('head').appendChild(script); } else{ tansa4ClientExtension.initMenu(); } } </script>
• Add the below JavaScript Code block in HTML page to override the default StyleGuard Pro text manipulation functions.
  <script type="text/javascript"> window.tansa4ClientExtensionPlugin = { getTexts:function(lingofyGetTextsFuncRef) { // write a logic to get the text. // This should return the array of text. e.g ["text1", "text2", "text3"]. }, selectText: function(lingofySelectTextFunRef, index, startPos, endPos, occurrenceNo, textToSelect) { // write a logic to select the text. }, replaceText:function(lingofyReplaceTextFunRef, index, startPos, endPos, replacement, occurrenceNo, textToReplace) { // write a logic to replace the text. } }; </script>
• Where, function arguments are.
  Note : The lingofyGetTextsFuncRef, lingofySelectTextFunRef and lingofyReplaceTextFunRef arguments are the StyleGuard's default implementation function reference and all are optional.
  1. lingofyGetTextsFuncRef : Omit this argument to skip StyleGuard's default implementation of this function and make StyleGuard Pro execute ONLY your custom implementation of this function. Including this argument will make StyleGuard Pro run the default implementation FOLLOWED BY your implementation.
  2. lingofySelectTextFunRef: Omit this argument to skip StyleGuard's default implementation of this function and make StyleGuard Pro execute ONLY your custom implementation of this function. Including this argument will make StyleGuard Pro run the default implementation FOLLOWED BY your implementation.
  3. lingofyReplaceTextFunRef : Omit this argument to skip StyleGuard's default implementation of this function and make StyleGuard Pro execute ONLY your custom implementation of this function. Including this argument will make StyleGuard Pro run the default implementation FOLLOWED BY your implementation.
  4. index : Index of the text input or text container. E.g. textarea, text input etc. One-based integer value.
  5. startPos : Start position of the text to replace, relative to the text element.
  6. endPos : End position of the text to replace, relative to the text element.
  7. replacement : Replacement text for the text between start and end position.
  8. textToSelect : Text to select for the text between start and end position.
  9. textToReplace : Text to replace for the text between start and end position.
  10. occurrenceNo : Occurrence number of the text.
  
  
• For demo please click here

Attribute handling

Ignore text element

StyleGuard Pro provides two solutions to ignore text elements in proofing.

1. Using the predefined attribute name

By adding (lingofy.settings.requireProofingAttribute="true") as a line of code into your HTML files under the header section/tag and by adding attribute (lingofy-proofing="true") in your HTML element, to only those text element you want to proof.          

This setting will ignores all text elements except the ones that has the lingofy-proofing set to "true".

If lingofy.settings.requireProofingAttribute is not specified then all text elements will be processed. So, by default, this setting does not need to be specified.

Note: If you do not use the JS implementation as described earlier in this document, but instead rely on one of the StyleGuard Pro browser Extensions, you can still utilize the requireProofingAttribute setting by adding this under the header section/tag:

2. Using custom attribute names

Define the following attribute handling setting in <tomcat folder>\conf\defaultClientSettings.properties

general.SpellcheckAttributes=attributename1: "true/false", attributename2: "true/false"

Example 1:

general.SpellcheckAttributes=run-proofing: true, spellcheck: true

StyleGuard Pro ignores all text elements except the ones that has the attribute run-proofing set to "true" or (if run-proofing is not found) spellcheck set to "true".

Example 2:

general.SpellcheckAttributes=run-proofing: false
StyleGuard Pro processes all text elements except the ones that has the attribute run-proofing set to "false". 

Example 3:

general.SpellcheckAttributes=run-proofing: false, spellcheck: true

StyleGuard Pro will process all texts except the ones with run-proofing="false" in one page, and also ignore all texts except the ones with spellcheck="true" in another page.
If both of these attributes are defined in the same proofing session (page), then there will be conflicting rules. To avoid this, StyleGuard Pro will always consider only one attribute and apply that rule on all elements.

• In this case StyleGuard Pro first checks if any elements have attribute "run-proofing".

• If found, StyleGuard Pro will follow the "run-proofing: false" rule and process all texts except the ones with run-proofing="false".
• If no element contains attribute run–proofing then, StyleGuard Pro will look for the "spellcheck" attribute.

• If found, StyleGuard Pro will only process texts with spellcheck="true".
• If not found, StyleGuard Pro will follow the first rule and process all texts, as per the "run-proofing: false" rule.

Note:

If no custom attribute rules have been defined in defaultClientSettings.properties then StyleGuard Pro will follow the "lingofy-proofing: false" rule by default and process all texts except the ones with lingofy-proofing="false".

Single line handling

StyleGuard Pro provides a global setting in <tomcat folder>\conf\defaultClientSettings.properties that controls whether to process single line edit fields or not:

general.SingleLineHandling=1

1 = StyleGuard Pro will process single line edit fields.

0 = StyleGuard Pro won’t process single line edit fields.

Integrate with TinyMCE

Changes to your TinyMCE HTML Page:

• Add the below JavaScript Code block in HTML page to initialize the StyleGuard Pro settings object.
  <script type="text/javascript"> [insert code from earlier in this document] </script>

• Add StyleGuard Pro Extension plugin to the TinyMCE Plugins folder: Download and Extract the "TinyMCE StyleGuard Pro Plugin.zip", copy the "styleguard" folder and paste it into the "tinymce\plugins" folder.
• Update the TinyMCE initialization code, i.e. tinymce.init() function, to add "styleguard" and "styleguardButton".

Example:

---

Screen shots of a StyleGuard Pro integration in TinyMCE:

Integrate with CKEditor

Changes to your CKEditor HTML Page:

• Add the below JavaScript Code block in HTML page to initialize the StyleGuard Pro settings object.
  <script type="text/javascript"> [insert code from earlier in this document] </script>

• Add the following “CKEDITOR.replace” script code snippet to the html page. Also include the CKEditor JavaScript and plugin, and update the JavaScript path according to the location of the CKEditor JavaScript.
  <script type="text/javascript"> CKEDITOR.replace('ckEditor2', { extraPlugins : 'styleguard', toolbarGroups : [ { name: 'clipboard', groups: [ 'clipboard', 'undo' ] }, { name: 'editing', groups: [ 'find', 'selection', 'spellchecker' ]}, { name: 'links' }, { name: 'insert' }, { name: 'forms' }, { name: 'tools' }, { name: 'document', groups: [ 'mode', 'document', 'doctools' ] }, { name: 'others' }, '/', { name: 'basicstyles', groups: [ 'basicstyles', 'cleanup' ] }, { name: 'paragraph', groups: [ 'list', 'indent', 'blocks', 'align', 'bidi' ] }, { name: 'styles' }, { name: 'colors' }, { name: 'about' } ] }); </script>

• Add StyleGuard Pro Extension plugin in CKEditor Plugins folder: Download and Extract the "CKEditor StyleGuard Pro Plugin.zip", copy the "styleguard" folder and paste it into the "ckeditor\plugins" folder.

Screen shots of a StyleGuard integration in CKEditor: