Zimlet JavaScript API Reference - AjxStringUtil

Class AjxStringUtil


This class provides static methods to perform miscellaneous string-related utility functions.

Defined in: AjxStringUtil.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
Default constructor does nothing (static class).
Method Summary
Method Attributes Method Name and Description
<static>  
AjxStringUtil.capitalize(str)
Capitalizes the specified string by upper-casing the first character and lower-casing the rest of the string.
<static>  
AjxStringUtil.capitalizeFirstLetter(str)
Capitalizes the specified string by upper-casing the first character.
<static>  
AjxStringUtil.capitalizeWords(str)
Capitalizes all the words in the specified string by upper-casing the first character of each word (does not change following characters, so something like MTV stays MTV
<static>  
AjxStringUtil.checkForCleanHtml(html, okTags, untrustedAttrs)
Checks the given HTML to see if it is "safe", and cleans it up if it is.
<static>  
AjxStringUtil.convertToHtml(str, quotePrefix, openTag, closeTag)
Converts the string to HTML.
<static>  
AjxStringUtil.diffPoint(str1, str2)
Does a diff between two strings, returning the index of the first differing character.
<static>  
AjxStringUtil.encodeQuotes(str)
encode quotes for using in inline JS code, so the text does not end a quoted param prematurely.
<static>  
AjxStringUtil.equalsHtmlPlatformIndependent(html1, html2)
compare two html code fragments, ignoring the case of tags, since the tags inside innnerHTML are returned differently by different browsers (and from Outlook) e.g.
<static>  
AjxStringUtil.fitString(str, width)
Fits as much of a string within the given width as possible.
<static>  
AjxStringUtil.fixCrossDomainReference(url, restUrlAuthority, convertToRelativeURL)
correct the cross domain reference in passed url content eg: http:/// url might have rest url page which points to http:/// pages
<static>  
AjxStringUtil.fromMixed(text, sep)
Converts the given mixed-case text to a string of one or more words separated by spaces.
<static>  
AjxStringUtil.getAsString(o)
Returns the given object/primitive as a string.
<static>  
AjxStringUtil.getOriginalContent(text, isHtml)
Analyze the text and return what appears to be original (as opposed to quoted) content.
<static>  
AjxStringUtil.getUnitsFromSizeString(sizeString)
Gets the units from size string.
<static>  
AjxStringUtil.getWidth(str, bold, font)
Returns the width in pixels of the given string.
<static>  
AjxStringUtil.htmlDecode(str, decodeSpaces)
Decodes the string.
<static>  
AjxStringUtil.htmlEncode(str, includeSpaces)
HTML-encodes a string.
<static>  
AjxStringUtil.htmlRubyEncode(base, text)
Encode
<static>  
AjxStringUtil.jsEncode(str)
Encodes non-ASCII and non-printable characters as \uXXXX, suitable for JSON.
<static>  
AjxStringUtil.parseMailtoLink(str)
Parses a mailto: link into components.
<static>  
AjxStringUtil.parseQueryString(sourceUri)
Parse the query string (part after the "?") and return it as a hash of key/value pairs.
<static>  
AjxStringUtil.prettyPrint(obj, recurse, showFuncs, omit)
Pretty-prints a JS object.
<static>  
AjxStringUtil.queryStringRemove(qs, name)
Removes the given arg from the query string.
<static>  
AjxStringUtil.quoteText(params)
Quotes text with the given quote character.
<static>  
AjxStringUtil.repeat(str, num)
Returns the string repeated the given number of times.
<static>  
AjxStringUtil.shiftChar(keycode, shifted)
Returns the character for the given key, taking the shift key into consideration.
<static>  
AjxStringUtil.split(str, dels)
Splits a string, ignoring delimiters that are in quotes or parentheses.
<static>  
AjxStringUtil.splitKeepLeadingWhitespace(line)
Splits the line into words, keeping leading whitespace with each word.
<static>  
AjxStringUtil.stripTags(str, removeContent)
Removes HTML tags from the given string.
<static>  
AjxStringUtil.toMixed(text, sep, camel)
Converts the given text to mixed-case.
<static>  
AjxStringUtil.trim(str, compress, space)
Removes white space from the beginning and end of a string, optionally compressing internal white space.
<static>  
AjxStringUtil.trimHtml(html)
Removes non-content HTML from the beginning and end.
<static>  
AjxStringUtil.urlComponentDecode(str)
Decodes a string as if it were a part of a URL.
<static>  
AjxStringUtil.urlComponentEncode(str)
Encodes a string as if it were a part of a URL.
<static>  
AjxStringUtil.urlDecode(str)
Decodes a complete URL.
<static>  
AjxStringUtil.urlEncode(str)
Encodes a complete URL.
<static>  
AjxStringUtil.wordWrap(params, text, len, prefix, before, after, preserveReturns, isHeaders, isFlowed, htmlMode)
Wraps text to the given length and optionally quotes it.
Class Detail
AjxStringUtil()
Default constructor does nothing (static class).
Author: Ross Dargahi, Roland Schemers, Conrad Damon.
Method Detail
<static> AjxStringUtil.capitalize(str)
Capitalizes the specified string by upper-casing the first character and lower-casing the rest of the string.
Parameters:
{string} str
The string to capitalize.

<static> AjxStringUtil.capitalizeFirstLetter(str)
Capitalizes the specified string by upper-casing the first character. Unlike AjxStringUtil.capitalize - don't change the rest of the letters.
Parameters:
{string} str
The string to capitalize.

<static> AjxStringUtil.capitalizeWords(str)
Capitalizes all the words in the specified string by upper-casing the first character of each word (does not change following characters, so something like MTV stays MTV
Parameters:
{string} str
The string to capitalize.

<static> AjxStringUtil.checkForCleanHtml(html, okTags, untrustedAttrs)
Checks the given HTML to see if it is "safe", and cleans it up if it is. It must have only the tags in the given list, otherwise false is returned. Attributes in the given list will be removed. It is not necessary to include "#text", "html", "head", and "body" in the list of allowed tags.
Parameters:
{string} html
HTML text
{array} okTags
whitelist of allowed tags
{array} untrustedAttrs
list of attributes to not allow in non-iframe.

<static> {string} AjxStringUtil.convertToHtml(str, quotePrefix, openTag, closeTag)
Converts the string to HTML.
Parameters:
{string} str
the string
quotePrefix
openTag
closeTag
Returns:
{string} the resulting string

<static> {number} AjxStringUtil.diffPoint(str1, str2)
Does a diff between two strings, returning the index of the first differing character.
Parameters:
{string} str1
a string
{string} str2
another string
Returns:
{number} the index at which they first differ

<static> AjxStringUtil.encodeQuotes(str)
encode quotes for using in inline JS code, so the text does not end a quoted param prematurely.
Parameters:
str

<static> AjxStringUtil.equalsHtmlPlatformIndependent(html1, html2)
compare two html code fragments, ignoring the case of tags, since the tags inside innnerHTML are returned differently by different browsers (and from Outlook) e.g. IE returns CAPS for tag names in innerHTML while FF returns lowercase tag names. Outlook signature creation also returns lowercase. this approach is also good in case the browser removes some of the innerHTML set to it, like I suspect might be in the case of stuff coming from Outlook. (e.g. it removes head tag since it's illegal inside a div)
Parameters:
html1
html2

<static> {String} AjxStringUtil.fitString(str, width)
Fits as much of a string within the given width as possible. If truncation is needed, adds an ellipsis. Truncation could happen at any letter, and not necessarily at a word boundary.
Parameters:
{String} str
a string
{Number} width
available width in pixels
Returns:
{String} string (possibly truncated) that fits in width

<static> AjxStringUtil.fixCrossDomainReference(url, restUrlAuthority, convertToRelativeURL)
correct the cross domain reference in passed url content eg: http:/// url might have rest url page which points to http:/// pages
Parameters:
url
restUrlAuthority
convertToRelativeURL

<static> AjxStringUtil.fromMixed(text, sep)
Converts the given mixed-case text to a string of one or more words separated by spaces.
Parameters:
{string} text
The mixed-case text.
{string} sep
(Optional) The separator between words. Default is a single space.

<static> {String} AjxStringUtil.getAsString(o)
Returns the given object/primitive as a string.
Parameters:
{primitive|Object} o
an object or primitive
Returns:
{String} the string

<static> {string} AjxStringUtil.getOriginalContent(text, isHtml)
Analyze the text and return what appears to be original (as opposed to quoted) content. We look for separators commonly used by mail clients, as well as prefixes that indicate that a line is being quoted.
Parameters:
{string} text
message body content
isHtml
Returns:
{string} original content if quoted content was found, otherwise NULL

<static> {string} AjxStringUtil.getUnitsFromSizeString(sizeString)
Gets the units from size string.
Parameters:
{string} sizeString
the size string
Returns:
{string} the units

<static> AjxStringUtil.getWidth(str, bold, font)
Returns the width in pixels of the given string.
Parameters:
{string} str
string to measure
{boolean} bold
if true, string should be measured in bold font
{string|number} font
size to measure string in. If unset, use default font size

<static> {string} AjxStringUtil.htmlDecode(str, decodeSpaces)
Decodes the string.
Parameters:
{string} str
the string to decode
{boolean} decodeSpaces
if true, decode spaces
Returns:
{string} the string

<static> {string} AjxStringUtil.htmlEncode(str, includeSpaces)
HTML-encodes a string.
Parameters:
{string} str
the string to encode
{boolean} includeSpaces
if true, to include encoding spaces
Returns:
{string} the encoded string

<static> AjxStringUtil.htmlRubyEncode(base, text)
Encode
Parameters:
base
{string} Ruby base.
text
{string} Ruby text (aka furigana).

<static> {string} AjxStringUtil.jsEncode(str)
Encodes non-ASCII and non-printable characters as \uXXXX, suitable for JSON.
Parameters:
{string} str
the string
Returns:
{string} the encoded string

<static> {Object} AjxStringUtil.parseMailtoLink(str)
Parses a mailto: link into components. If the string is not a mailto: link, the object returned will have a "to" property set to the string.
Parameters:
{String} str
email address, possibly within a "mailto:" link
Returns:
{Object} object with at least a 'to' property, and possibly 'subject' and 'body'

<static> {Object} AjxStringUtil.parseQueryString(sourceUri)
Parse the query string (part after the "?") and return it as a hash of key/value pairs.
Parameters:
{String} sourceUri
the source location or query string
Returns:
{Object} a hash of query string params

<static> AjxStringUtil.prettyPrint(obj, recurse, showFuncs, omit)
Pretty-prints a JS object. Preferred over JSON.stringify for the debug-related dumping of an object for several reasons: - doesn't have an enclosing object, which shifts everything over one level - doesn't put quotes around keys - shows indexes for arrays (downside is that prevents output from being eval-able)
Parameters:
obj
recurse
showFuncs
omit

<static> {String} AjxStringUtil.queryStringRemove(qs, name)
Removes the given arg from the query string.
Parameters:
{String} qs
a query string
{String} name
the arg name
Returns:
{String} the resulting query string

<static> {string} AjxStringUtil.quoteText(params)
Quotes text with the given quote character. For HTML, surrounds the text with the given strings. Does no wrapping.
Parameters:
{hash} params
a hash of parameters
{string} params.text
the text to be wrapped
{string} params.pre Optional
prefix for quoting
{string} params.before Optional
text to prepend to final result
{string} params.after Optional
text to append to final result
Returns:
{string} the quoted text

<static> {string} AjxStringUtil.repeat(str, num)
Returns the string repeated the given number of times.
Parameters:
{string} str
a string
{number} num
number of times to repeat the string
Returns:
{string} the string

<static> {char} AjxStringUtil.shiftChar(keycode, shifted)
Returns the character for the given key, taking the shift key into consideration.
Parameters:
{number} keycode
a numeric keycode (not a character code)
{boolean} shifted
whether the shift key is down
Returns:
{char} a character

<static> {array} AjxStringUtil.split(str, dels)
Splits a string, ignoring delimiters that are in quotes or parentheses. Comma is the default split character, but the user can pass in a string of multiple delimiters. It can handle nested parentheses, but not nested quotes.

TODO: handle escaped quotes

Parameters:
{string} str
the string to split
{string} dels Optional
an optional string of delimiter characters
Returns:
{array} an array of strings

<static> {array} AjxStringUtil.splitKeepLeadingWhitespace(line)
Splits the line into words, keeping leading whitespace with each word.
Parameters:
{string} line
the text to split
Returns:
{array} the array of words

<static> {string} AjxStringUtil.stripTags(str, removeContent)
Removes HTML tags from the given string.
Parameters:
{string} str
text from which to strip tags
{boolean} removeContent
if true, also remove content within tags
Returns:
{string} the resulting HTML string

<static> {string} AjxStringUtil.toMixed(text, sep, camel)
Converts the given text to mixed-case. The input text is one or more words separated by spaces. The output is a single word in mixed (or camel) case.
Parameters:
{string} text
text to convert
{string|RegEx} sep
text separator (defaults to any space)
{boolean} camel
if true, first character of result is lower-case
Returns:
{string} the resulting string

<static> {string} AjxStringUtil.trim(str, compress, space)
Removes white space from the beginning and end of a string, optionally compressing internal white space. By default, white space is defined as a sequence of Unicode whitespace characters (\s in regexes). Optionally, the user can define what white space is by passing it as an argument.

TODO: add left/right options

Parameters:
{string} str
the string to trim
{boolean} compress
whether to compress internal white space to one space
{string} space
a string that represents a user definition of white space
Returns:
{string} a trimmed string

<static> {String} AjxStringUtil.trimHtml(html)
Removes non-content HTML from the beginning and end. The idea is to remove anything that would appear to the user as blank space. This function is an approximation since that's hard to do, especially when dealing with HTML as a string.
Parameters:
{String} html
HTML to fix
Returns:
{String} trimmed HTML

<static> {string} AjxStringUtil.urlComponentDecode(str)
Decodes a string as if it were a part of a URL. Falls back to unescape() if necessary.
Parameters:
{string} str
the string to decode
Returns:
{string} the decoded string

<static> {string} AjxStringUtil.urlComponentEncode(str)
Encodes a string as if it were a part of a URL. The difference between this function and AjxStringUtil.urlEncode is that this will also encode the following delimiters:
 			: / ? & =
Parameters:
{string} str
the string to encode
Returns:
{string} the resulting string

<static> {string} AjxStringUtil.urlDecode(str)
Decodes a complete URL.
Parameters:
{string} str
the string to decode
Returns:
{string} the decoded string

<static> {string} AjxStringUtil.urlEncode(str)
Encodes a complete URL. Leaves delimiters alone.
Parameters:
{string} str
the string to encode
Returns:
{string} the encoded string

<static> {string} AjxStringUtil.wordWrap(params, text, len, prefix, before, after, preserveReturns, isHeaders, isFlowed, htmlMode)
Wraps text to the given length and optionally quotes it. The level of quoting in the source text is preserved based on the prefixes. Special lines such as email headers always start a new line.
Parameters:
{hash} params
a hash of parameters
{string} text
the text to be wrapped
{number} len
the desired line length of the wrapped text, defaults to 80
{string} prefix
an optional string to prepend to each line (useful for quoting)
{string} before
text to prepend to final result
{string} after
text to append to final result
{boolean} preserveReturns
if true, don't combine small lines
{boolean} isHeaders
if true, we are wrapping a block of email headers
{boolean} isFlowed
format text for display as flowed (RFC 3676)
{boolean} htmlMode
if true, surround the content with the before and after
Returns:
{string} the wrapped/quoted text

Documentation generated by JsDoc Toolkit 2.3.0 on Tue Jun 28 2016 21:01:30 GMT-0400 (EDT)