TWiki Variables » Search » Category: Export & Publishing

ENCODE{string} -- encode a string to URL entities, HTML entities, CSV format, and more

• Encode "special" characters in a string to HTML numeric entities, URL entities. Also escapes special characters for CSV use and more.
• Encoded characters:
  • all non-printable ASCII characters below space, except newline ("\n") and linefeed ("\r")
  • HTML special characters "<", ">", "&", single quote (') and double quote (")
  • TWiki special characters "%", "[", "]", "@", "_", "*", "=" and "|"
• Syntax: %ENCODE{"string"}%
• Supported parameters:

  Parameter:	Description:	Default:
  "string"	String to encode	required (can be empty)
  type="url"	Encode special characters for URL parameter use, like a double quote into %22	(this is the default)
  type="quotes"	Escape double quotes with backslashes (\"), does not change other characters. This type does not protect against cross-site scripting.	type="url"
  type="moderate"	Encode special characters into HTML entities for moderate cross-site scripting protection: "<", ">", single quote (') and double quote (") are encoded. Useful to allow TWiki variables in comment boxes.	type="url"
  type="safe"	Encode special characters into HTML entities for cross-site scripting protection: "<", ">", "%", single quote (') and double quote (") are encoded.	type="url"
  type="entity"	Encode special characters into HTML entities, like a double quote into &#034;. Does not encode newline (\n) or linefeed (\r).	type="url"
  type="entity" extra=" $n$r"	For type="entity" only, use the extra parameter to encode additional characters to HTML numeric entities. Formatting tokens can be used, such as "$n" for newline. Note that type="entity" extra=" $n$r" is equivalent to type="html".	type="url" extra=""
  type="html"	Encode special characters into HTML entities. In addition to type="entity", it also encodes space, \n and \r. Useful to encode text properly in HTML input fields. See equivalent ENTITY.	type="url"
  type="json"	Escape double quotes and backslashes with backslashes (\" and \\, respectively), escape non-printable characters with hex code \u0000 ... \u001F, does not change other characters. Use this to properly escape text for a JSON string. Example result: This is a string with \"quoted\" and \\backslashed\\ text.	type="url"
  type="csv"	Escape single quotes and double quotes by repeating them, other characters do not change. Use this to properly escape fields in CSV reports that output comma-separated values, such as "field 1","field 2 with ''single'' and ""double"" quotes".	type="url"
  newline="..."	Replace a newline with the specified value before encoding. Please note that newline="<br/>" does not bring <br/> to the output because < and > are encoded (except with the quotes and csv types). To have <br/> in the output, you need to specify newline="$br". However, newline="$br" does not work in combination with type="url" (the defautl type). This shouldn't be a problem because it's very rare to need to have <br/> encoded in a URL. In addition to $br, $n has a special meaning in a newline parameter value - $n results in a newline in the output. This parameter is expected to be used in combination with the moderate, safe, entity, or html type. With the other types, it causes unuseful results.

• Examples:
  • %ENCODE{"spaced name"}% expands to spaced%20name
  • %ENCODE{"spaced name" type="entity" extra=" "}% expands to spaced name
• Notes:
  • Values of HTML input fields should be encoded as "html". A shorter %ENTITY{any text}% can be used instead of the more verbose %ENCODE{ "any text" type="html" }%.
    Example: <input type="text" name="address" value="%ENTITY{any text}%" />
  • Double quotes in strings must be escaped when passed into other TWiki variables.
    Example: %SEARCH{ "%ENCODE{ "string with "quotes"" type="quotes" }%" noheader="on" }%
  • Use type="moderate", type="safe", type="entity" or type="html" to protect user input from URL parameters and external sources against cross-site scripting (XSS). type="html" is the safest mode, but some TWiki applications might not work. type="safe" provides a safe middle ground, type="moderate" provides only moderate cross-site scripting protection.
• Category: ApplicationsAndComponentsVariables, DevelopmentVariables, ExportAndPublishingVariables
• Related: ENTITY, FORMFIELD, QUERYPARAMS, URLPARAM (this topic)

ENTITY{string} -- encode a string to HTML entities

• Encode "special" characters to HTML entities. Useful to encode text properly for HTML input fields.
• Encoded characters:
  • all non-printable ASCII characters below space, including newline ("\n") and linefeed ("\r")
  • Space
  • HTML special characters "<", ">", "&", single quote (') and double quote (")
  • TWiki special characters "%", "[", "]", "@", "_", "*", "=" and "|"
• Syntax: %ENTITY{string}%
• Example: %ENTITY{text with "quotes" and
newline}% expands to text with "quotes" and
newline
• Notes:
  • To protect against cross-site scripting (XSS), always entity encode text intended for HTML input fields. This is especially true if text is received dynamically via URLPARAM or the like.
    Example: <input type="text" name="address" value="%ENTITY{any text}%" />
  • %ENTITY{string}% is roughly equivalent to %ENCODE{ "string" type="html" }%, but the latter cannot handle strings that have double quotes embedded in it.
• Category: DevelopmentVariables, FormattingAndRenderingVariables, ExportAndPublishingVariables
• Related: ENCODE, FORMFIELD, QUERYPARAMS, URLPARAM (this topic)

SEARCH{"text"} -- search content

• Inline search, shows a search result embedded in a topic
• Syntax: %SEARCH{"text" ...}%
• Supported parameters:

  Parameter:	Description: <-- -->	Default:
  nosearch="on"	Suppress search string	Show search string
  noempty="on"	Suppress results for webs that have no hits.	Show webs with no hits
  noheader="on"	Suppress default search header Topics: Changed: By: , unless a header is explicitly specified	Show default search header, unless search is inline and a format is specified (Cairo compatibility)
  zeroresults="off"	Suppress all output if there are no hits	zeroresults="on", displays: "Number of topics: 0"
  start="0" start="20"	Specify the number of results to skip. This is done after sorting if sort parameter is specified. This is intended for pagination of results. If this parameter is specified, %NTOPICS% in the search template is replaced with the number of topics matched. Without this parameter, %NTOPICS% doesn't exceed the limit value.	"0"
  sort="topic" sort="created" sort="modified" sort="editby" sort="parent" sort="parent(99)" sort="formfield(name)" sort="parent,  formfield(name)"	Sort the search results by: • topic: topic name, • created: topic creation time, • modified: last modified time, • editby: last editor, • parent: parent topic name, • parent(N): parent breadcrumb up to indicated level, • formfield(NAME): named TWikiForms field, • or a combination to sort by more than one field using a comma list. The sorting is done web by web; if you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort. Note that dates are sorted most recent date last (i.e at the bottom of the table). Legacy order parameter is used in case sort is not specified.	"topic"
  createdate="..."	similar to date but it's about create time instead of last edit. You can specify both date and createdate, in which case topics matching both conditions are shown.	All results
  nosummary="on"	Show topic title only	Show topic summary
  nonoise="on"	Shorthand for nosummary="on" nosearch="on" nototal="on" zeroresults="off" noheader="on" noempty="on"	Off
  scope="topic" scope="text" scope="all"	Search topic name (title); the text (body) of topic; or all (title and body)	"text"
  "text"	Search term. Is a keyword search, literal search, regular expression search, or query, depending on the type parameter. SearchHelp has more	required
  reverse="on" reverse="off, on"	Reverse the direction of the search. Specify a comma list of on, off tokens to toggle direction by sort field. If sort has more fields than reverse tokens, the state of the last reverse token is taken for the remaining fields.	"off"
  recurse="on"	Recurse into subwebs, if subwebs are enabled.	off
  multiple="on"	Multiple hits per topic. Each hit can be formatted. The last token is used in case of a regular expression ";" and search	Only one hit per topic
  newline="$br"	Line separator within a search hit. Useful if you want to put multi-line content into a table cell, for example if the format="" parameter contains a $pattern() that captures more than one line, or contains a $formfield() that returns a multi-line textfield. The following variables can be used in the newline value: $n expands to a newline, $br expands to a <br /> line break tag.	"$n" (Newline)
  separator=", "	Line separator between search hits. Specify format="$topic" separator=", " to get a comma separated list of topic names. The following variables can be used in the separator value: $n expands to a newline, $br expands to a <br /> line break tag.	"$n" (Newline)
  date="..."	limits the results to those pages with latest edit time in the given time interval.	All results
  limit="all" limit="16"	Limit the number of results returned. This is done after sorting if sort parameter is specified. This parameter specifing the number of results remains the same in the presense of the start parameter. Assuming there are more than 20 results matched, start="10" limit="10" results in 11th to 20th results are returned	"all"
  topic="WebPreferences" topic="*Bug"	Limit search to topics: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. Note this is a list of topic names and must not include web names.	All topics in a web
  nofinalnewline="on"	If on, the search variable does not end in a line by itself. Any text continuing immediately after the search variable on the same line will be rendered as part of the table generated by the search, if appropriate.	off
  expandvariables="on"	Expand variables before applying a FormattedSearch on a search hit. Useful to show the expanded text, e.g. to show the result of a SpreadSheetPlugin %CALC{}% instead of the formula	Raw text
  excludetopic="Web*" excludetopic="WebHome, WebChanges"	Exclude topics from search: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. Note this is a list of topic names and must not include web names.	None
  encode="html"	Encode special characters into HTML entities. If a FORMFIELD is passed into an HTML form field it should be encoded as "html". Additional encodings available: encode="quote", encode="moderate", encode="safe", encode="entity" and encode="url". See ENCODE for details.	no encoding
  nototal="on"	Do not show number of topics found	Show number
  default="..."	Default message if there are no hits in a web. See FormattedSearch for usage, variables & examples	No output
  header="..." format="..." footer="..."	Custom format results. See FormattedSearch for usage, variables & examples	Results in table
  type="keyword" type="word" type="literal" type="regex" type="query"	Control how the search is performed when scope="text" or scope="all" keyword: use Google-like controls as in soap "web service" -shampoo; searches word parts: using the example, topics with "soapsuds" will be found as well, but topics with "shampoos" will be excluded word: identical to keyword but searches whole words: topics with "soapsuds" will not be found, and topics with "shampoos" will not be excluded literal: search for the exact string, like web service regex: use a RegularExpression search like soap;web service;!shampoo; to search on whole words use \bsoap\b query: query search of form fields and other meta-data, like (Firstname='Emma' OR Firstname='John') AND Lastname='Peel'	%SEARCHVAR- DEFAULTTYPE% preferences setting (literal)
  web="Name" web="Main, Know" web="all"	Comma-separated list of webs to search. You can specifically \*exclude\* webs from an all search using a minus sign - for example, web="all,-Secretweb". The special word all means all webs that do not have the NOSEARCHALL variable set to on in their WebPreferences. Note that TWikiAccessControls are respected when searching webs; it is much better to use them than NOSEARCHALL.	Current web
  casesensitive="on"	Case sensitive search	Ignore case
  bookview="on"	BookView search, e.g. show complete topic text	Show topic summary
  headingoffset="2"	Adjust the level of headings in text of topics found, taking effect in $text and $pattern() of a FormattedSearch. A "2" or "+2" increases the level by two, e.g. a ---+ H1 turns into a ---+++ H3. Positive and negative values are supported. Adjusted min and max levels are H1 and H6, respectively.	no adjustment
  search="text"	(Alternative to above)	N/A

• Example: %SEARCH{"wiki" web="Main" scope="topic"}%
• Example with format: %SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"}% (displays results in a table with header - details)
• Hint: If the TWiki:Plugins.TablePlugin is installed, you may set a %TABLE{}% variable just before the %SEARCH{}% to alter the output of a search. Example: %TABLE{ tablewidth="90%" }%
• Category: DevelopmentVariables, DatabaseAndFormsVariables, ExportAndPublishingVariables, SearchingAndListingVariables
• Related: CHILDREN, EDITFORM, EDITFORMFIELD, FORM, FORMFIELD, META, METASEARCH, PARENTTOPIC, TOPICLIST, WEBLIST, FormattedSearch, SearchResultsPagination, QuerySearch, SearchHelp, SearchPatternCookbook, RegularExpression (this topic)

Total: 3 variables

Related Topics: TWikiVariables, TWikiVariablesSearch, TWikiVariablesQuickStart