"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.
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 |
ENCODE
is called with no optional parameters (e.g. %ENCODE{"string"}%
) then the default type="url"
encoding will be used.
type
parameter encodes the following "special characters" type="entity"
or type="entities"
Encode special characters into HTML entities, like a double quote into " "\n"
) and carriage return ("\r"
).
"<"
, ">"
, "&"
, single quote ('
) and double quote ("
)
"%"
, "["
, "]"
, "@"
, "_"
, "*"
, "="
, "$"
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
.
%ENCODE{"spaced name"}%
expands to spaced%20name
%ENCODE{"| Blah | | More blah |" old="|,$n" new="|,<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
<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.%SEARCH{ "%ENCODE{ "string with "quotes"" type="quotes" }%" noheader="on" }%
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'