ENCODE -- encode characters in a string

Encode character sequences in "string", by mapping characters (or sequences of characters) to an alternative character (or sequence of characters). This macro can be used to encode strings for use in URLs, to encode to HTML entities, to protect quotes, and for as many other uses as you can imagine.

Parameters

Parameter	Description	Default
"string"	String to encode	"" (empty string)
type	Use a predefined encoding (see below).	Default is 'url'. Parameter type not be used if old or new are given.
old	Comma-separated list of tokens to replace. Tokens are normally single characters, but can also be sequences of characters. The standard format tokens may be used in this list. Each token must be unique - you cannot list the same token twice.	May not be used with type; required if new is used
new	comma-separated list of replacement tokens. The elements in this list match 1:1 with the elements in the old list. Again, the standard format tokens may be used. An empty element in the new list will result in the corresponding token in the old list being deleted from the string. If the new list is shorter than the old list it will be extended to the same length using the empty element. Tokens do not have to be unique. When using old and new, be aware that the results of applying earlier tokens are not processed again using later tokens. (see examples below)	May not be used with type; required if old is used

If ENCODE is called with no optional parameters (e.g. %ENCODE{"string"}%) then the default type="url" encoding will be used.

Predefined encodings

Unless otherwise specified, the type parameter encodes the following "special characters"

• type="entity" or type="entities" Encode special characters into HTML entities, like a double quote into "
  • all non-printable ASCII characters below space, except newline ("\n") and carriage return ("\r").
  • HTML special characters "<", ">", "&", single quote (') and double quote (")
  • TML special characters "%", "[", "]", "@", "_", "*", "=", "$" and "|"
• type="html" As type="entity" except it also encodes \n (newline) and carriage return ("\r").
• type="safe" Encode just the characters '"<>% into HTML entities.
• type="quote" or type="quotes" Escapes double quotes with backslashes (\"), does not change any other characters
• type="url" (default) Encode special characters for use in URL parameters, like a double quote into %22.

Examples

• %ENCODE{"spaced name"}% expands to spaced%20name
• %ENCODE{"| Blah | | More blah |" old="|,$n" new="&#124;,<br />"}% expands to =| Blah | | More blah | - this encoding is useful to protect special TML characters in tables.
• %ENCODE{"10xx1x01x" old="1,x,0" new="A,,B"}% expands to ABABA
• %ENCODE{"1,2" old="$comma" new=";"}% expands to 1;2

Values for HTML input fields must be entity encoded.
Example:

<input type="text" name="address" value="%ENCODE{ "any text" type="entity" }%" />

ENCODE can be used to filter user input from URL parameters and similar to help protect against cross-site scripting. The safest approach is to use type="entity". This can however prevent an application from fully working. You can alternatively use type="safe" which encodes only the characters '"<>% into HTML entities. When ENCODE is passing a string inside another macro always use double quotes ("") type="quote". For maximum protection against cross-site scripting you are advised to install the Foswiki:Extensions.SafeWikiPlugin.

Double quotes in strings must be escaped when passed into other macros.
Example:

%SEARCH{ "%ENCODE{ "string with "quotes"" type="quotes" }%" noheader="on" }%

When using old and new, be aware that the results of applying earlier tokens are not processed again using later tokens. For example:

   %ENCODE{"A" old="A,B" new="B,C"}% will result in 'B' (not 'C'),
   %ENCODE{"asd" old="as,d" new="d,f"}% will yield 'df', and
   %ENCODE{"A" old="A,AA" new="AA,B"}% will give 'AA' and.
   %ENCODE{"asdf" old="a,asdf" new="a,2"}% will give 'asdf'

Related

URLPARAM