Prototype JavaScript framework - String

interpolate

2007-10-23T16:40:00Z

interpolate(object[, pattern]) -> string

Treats the string as a Template and fills it with object’s properties.

Equivalent to calling evaluate on a previously-instantiated Template.

Examples


"#{animals} on a #{transport}".interpolate({ animals: "Pigs", transport: "Surfboard" });
//-> "Pigs on a Surfboard"


var syntax = /(^|.|\r|\n)(\<%=\s*(\w+)\s*%\>)/; //matches symbols like '<%= field %>'
var html = '<div>Name: <b><%= name %></b>, Age: <b><%=age%></b></div>';
html.interpolate({ name: 'John Smith', age: 26 }, syntax);
// -> <div>Name: <b>John Smith</b>, Age: <b>26</b></div>

isJSON

2007-06-20T14:39:00Z

isJSON() -> boolean

Check if the string is valid JSON by the use of regular expressions. This security method is called internally.

Examples


"something".isJSON()
// -> false
"\"something\"".isJSON()
// -> true
"{ foo: 42 }".isJSON()
// -> false
"{ \"foo\": 42 }".isJSON()
// -> true

unfilterJSON

2007-05-01T16:58:00Z

unfilterJSON([filter = Prototype.JSONFilter]) -> String

Strips comment delimiters around Ajax JSON or JavaScript responses. This security method is called internally.

Example


'/*-secure-\n{"name": "Violet", "occupation": "character", "age": 25}\n*/'.unfilterJSON()
// -> '{"name": "Violet", "occupation": "character", "age": 25}'

empty

2007-03-09T10:59:00Z

empty() -> Boolean

Checks if the string is empty.

Examples


''.empty();
//-> true

'  '.empty();
//-> false

endsWith

2007-03-09T10:59:00Z

endsWith(substring) -> Boolean

Checks if the string ends with substring.

Example


'slaughter'.endsWith('laughter')
// -> true

blank

2007-03-09T10:59:00Z

blank() -> Boolean

Check if the string is 'blank', meaning either empty or containing only whitespace.

Examples


''.blank();
//-> true

'  '.blank();
//-> true

' a '.blank();
//-> false

toJSON

2007-03-09T10:54:00Z

toJSON() -> String

Returns a JSON string.

Example


'The "Quoted" chronicles'.toJSON();
//-> '"The \"Quoted\" chronicles"'

evalJSON

2007-03-09T10:54:00Z

evalJSON([sanitize = false]) -> object

Evaluates the JSON in the string and returns the resulting object. If the optional sanitize parameter is set to true, the string is checked for possible malicious attempts and eval is not called if one is detected.

If the JSON string is not well formated or if a malicious attempt is detected a SyntaxError is thrown.

Examples


var person = '{ "name": "Violet", "occupation": "character" }'.evalJSON();
person.name;
//-> "Violet"

person = 'grabUserPassword()'.evalJSON(true);
//-> SyntaxError: Badly formed JSON string: 'grabUserPassword()'

person = '/*-secure-\n{"name": "Violet", "occupation": "character"}\n*/'.evalJSON()
person.name;
//-> "Violet"

Note

Always set the sanitize parameter to true for data coming from externals sources to prevent XSS attacks.

As String#evalJSON internally calls String#unfilterJSON, optional security comment delimiters (defined in Prototype.JSONFilter) are automatically removed.

include

2007-03-09T10:54:00Z

include(substring) -> Boolean

Check if the string contains a substring.

Example


'Prototype framework'.include('frame');
//-> true
'Prototype framework'.include('frameset');
//-> false

startsWith

2007-03-09T10:54:00Z

startsWith(substring) -> Boolean

Checks if the string starts with substring.

Example


'Prototype JavaScript'.startsWith('Pro');
//-> true

times

2007-03-09T10:52:00Z

times(count) -> string

Concatenates the string count times.

Example


"echo ".times(3);
//-> "echo echo echo "

inspect

2007-01-03T19:19:00Z

inspect([useDoubleQuotes = false]) -> String

Returns a debug-oriented version of the string (i.e. wrapped in single or double quotes, with backslashes and quotes escaped).

For more information on inspect methods, see Object.inspect.

Examples


'I\'m so happy.'.inspect();
// -> '\'I\\\'m so happy.\'' (displayed as 'I\'m so happy.' in an alert dialog or the console)

'I\'m so happy.'.inspect(true);
// -> '"I'm so happy."'  (displayed as "I'm so happy." in an alert dialog or the console)

scan

2007-01-03T15:28:00Z

scan(pattern, iterator) -> string

Allows iterating over every occurrence of the given pattern (which can be a string or a regular expression). Returns the original string.

Internally just calls String#gsub passing it pattern and iterator as arguments.

Examples


'apple, pear & orange'.scan(/\w+/, alert);
// -> 'apple pear orange' (and displays 'apple', 'pear' and 'orange' in three successive alert dialogs)

Can be used to populate an array:


var fruits = [];
'apple, pear & orange'.scan(/\w+/, function(match){ fruits.push(match[0])});
fruits.inspect()
// -> ['apple', 'pear', 'orange']

or even to work on the DOM:


'failure-message, success-message & spinner'.scan(/(\w|-)+/, Element.toggle)
// -> 'failure-message, success-message & spinner' (and toggles the visibility of each DOM element)

Note

Do not use the "g" flag on the regex as this will create an infinite loop.

sub

2007-01-03T14:46:00Z

sub(pattern, replacement[, count = 1]) -> string

Returns a string with the first count occurrences of pattern replaced by either a regular string, the returned value of a function or a Template string. pattern can be a string or a regular expression.

Unlike String#gsub, String#sub takes a third optional parameter which specifies the number of occurrences of the pattern which will be replaced. If not specified, it will default to 1.

Apart from that, String#sub works just like String#gsub. Please refer to it for a complete explanation.

Examples


var fruits = 'apple pear orange';

 fruits.sub(' ', ', ');
// -> 'apple, pear orange'

 fruits.sub(' ', ', ', 1);
// -> 'apple, pear orange'

 fruits.sub(' ', ', ', 2);
// -> 'apple, pear, orange'

fruits.sub(/\w+/, function(match){return match[0].capitalize() + ','}, 2);
// -> 'Apple, Pear, orange'

var markdown = '![a pear](/img/pear.jpg) ![an orange](/img/orange.jpg)';

markdown.sub(/!\[(.*?)\]\((.*?)\)/, function(match){
  return '<img alt="' + match[1] + '" src="' + match[2] + '" />';
});
// -> '<img alt="a pear" src="/img/pear.jpg" /> ![an orange](/img/orange.jpg)'

markdown.sub(/!\[(.*?)\]\((.*?)\)/, '<img alt="#{1}" src="#{2}" />');
// -> '<img alt="a pear" src="/img/pear.jpg" /> ![an orange](/img/orange.jpg)'

Note

Do not use the "g" flag on the regex as this will create an infinite loop.

gsub

2007-01-03T05:23:00Z

gsub(pattern, replacement) -> string

Returns the string with every occurence of a given pattern replaced by either a regular string, the returned value of a function or a Template string. The pattern can be a string or a regular expression.

If its second argument is a string String#gsub works just like the native JavaScript method replace() set to global match.


var mouseEvents = 'click dblclick mousedown mouseup mouseover mousemove mouseout';

mouseEvents.gsub(' ', ', ');
// -> 'click, dblclick, mousedown, mouseup, mouseover, mousemove, mouseout'

mouseEvents.gsub(/\s+/, ', ');
// -> 'click, dblclick, mousedown, mouseup, mouseover, mousemove, mouseout'

If you pass it a function, it will be invoked for every occurrence of the pattern with the match of the current pattern as its unique argument. Note that this argument is the returned value of the match() method called on the current pattern. It is in the form of an array where the first element is the entire match and every subsequent one corresponds to a parenthesis group in the regex.


mouseEvents.gsub(/\w+/, function(match){return 'on' + match[0].capitalize()});
// -> 'onClick onDblclick onMousedown onMouseup onMouseover onMousemove onMouseout'

var markdown = '![a pear](/img/pear.jpg) ![an orange](/img/orange.jpg)';

markdown.gsub(/!\[(.*?)\]\((.*?)\)/, function(match){
  return '<img alt="' + match[1] + '" src="' + match[2] + '" />';
});
// -> '<img alt="a pear" src="/img/pear.jpg" /> <img alt="an orange" src="/img/orange.jpg" />'

Lastly, you can pass String#gsub a Template string in which you can also access the returned value of the match() method using the ruby inspired notation: #{0} for the first element of the array, #{1} for the second one, and so on. So our last example could be easily re-written as:


markdown.gsub(/!\[(.*?)\]\((.*?)\)/, '<img alt="#{1}" src="#{2}" />');
// -> '<img alt="a pear" src="/img/pear.jpg" /> <img alt="an orange" src="/img/orange.jpg" />'

If you need an equivalent to String#gsub but without global match set on, try String#sub.

Note

Do not use the "g" flag on the regex as this will create an infinite loop.