Google Git
Sign in
apache / tapestry4 / d33c3e83908561b067f859815c313c0a7f27909d / . / tapestry / src / site / xdoc / components / general / insert.xml
blob: e482ea698251bfd97e418a5d1b01c82d76b849cf [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright 2004, 2005 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<document>
<properties>
<title>Insert</title>
</properties>
<body>
<section name="Insert">
<p>
Allows for the insertion of text (with a specified format) into the HTML response. The text itself can
be filtered or not. When filtering is enabled (the default), certain characters (such as
<code>&lt; and &gt;</code>
) are escaped into HTML safe representations (such as
<code>&amp;lt; and &amp;gt;</code>
).
</p>
<p>
Also allows insertion of multi-line text, breaking it into individual lines according to a mode.
Commonly used to properly display the data provided by a user via the
<a href="../form/textarea.html">TextArea</a>
component.
</p>
<p>
<strong>See also:</strong>
<a href="../../apidocs/org/apache/tapestry/components/Insert.html">
org.apache.tapestry.components.Insert
</a>
<a href="renderblock.html">RenderBlock</a>
,
<a href="renderbody.html">RenderBody</a>
</p>
<section name="Parameters">
<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Required</th>
<th>Default Value</th>
<th>Description</th>
</tr>
<tr>
<td>value</td>
<td>Object</td>
<td>no</td>
<td></td>
<td>
The value to be inserted. If the binding is null, then nothing is inserted. Any object may
be inserted, the
<code>toString()</code>
method is used to convert it to a printable value.
</td>
</tr>
<tr>
<td>format</td>
<td>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/text/Format.html">Format</a>
</td>
<td>no</td>
<td></td>
<td>
An optional format object used to convert the value parameter for insertion into the HTML
response.
</td>
</tr>
<tr>
<td>class</td>
<td>String</td>
<td>no</td>
<td></td>
<td>
If specified, then the output is wrapped in an HTML tag, using the value specified as the
CSS class. (the html tag being whatever you used to reference the component to begin with )
<br />
<br />
<span class="warn">
<strong>Warning:</strong>
<p>
Using class to force tag rendering is now deprecated, please use the renderTag
parameter to control tag rendering.
</p>
</span>
</td>
</tr>
<tr>
<td>renderTag</td>
<td>boolean</td>
<td>no</td>
<td>false</td>
<td>
If specified, then the output is wrapped in an HTML tag.
<p>Example:</p>
<source><![CDATA[
<div jwcid="@Insert" value="literal:TestValue" class="myStyle" id="An Id" renderTag="true">
Text
</div>
]]></source>
</td>
</tr>
<tr>
<td>raw</td>
<td>boolean</td>
<td>no</td>
<td>false</td>
<td>
If true, then the method
<a
href="../../apidocs/org/apache/tapestry/IMarkupWriter.html#printRaw(java.lang.String)">
<code>IMarkupWriter.printRaw(String)</code>
</a>
is used, rather than
<a
href="../../apidocs/org/apache/tapestry/IMarkupWriter.html#print(java.lang.String)">
<code>IMarkupWriter.print(String)</code>
</a>
.
<p>
This bypasses the normal safeguards and is used when the value to
insert contains HTML markup that should be emitted as is.
</p>
</td>
</tr>
<tr>
<td>mode</td>
<td>
<a
href="../../apidocs/org/apache/tapestry/components/InsertMode.html">
InsertMode
</a>
</td>
<td>no</td>
<td></td>
<td>
Controls how each line is rendered.
<p>
The OGNL expression
<code>@org.apache.tapestry.components.InsertMode@PARAGRAPH</code> OR
<code>@org.apache.tapestry.components.InsertMode@BREAK</code>
can be used to specify paragraph or line break rendering mode.
</p>
</td>
</tr>
</table>
<p>
Body:
<strong>removed</strong>
</p>
<p>
Informal parameters:
<strong>allowed</strong>
</p>
<p>
Reserved parameters:
<em>none</em>
</p>
<p>
The value parameter is split into multiple lines when specifying a "mode" paramater, and
each line is printed. The BREAK
<em>mode</em>
renders a
<code>&lt;br/&gt;</code>
tag between lines (that is, before each line after the first line output). The alternate mode
renders
<code>&lt;p&gt; and &lt;/p&gt;</code>
tags around each line.
</p>
</section>
<section name="Examples">
<p>
Inserts the pages dueDate and applies the specified DateFormat and HTML class.
Example output:
</p>
<img src="../../images/ComponentReference/Insert.png"
alt="Insert Screen Shot" />
<p>HTML template</p>
<source xml:space="preserve">
&lt;table class="examples" cellpadding="8"&gt;
&lt;tr&gt;
&lt;td&gt;
The order was due on the &lt;font color="red"&gt;&lt;b&gt;
&lt;span jwcid="@Insert" value="ognl:date" format="ognl:dateFormat" class="ognl:dueClass"&gt;21 January 2002&lt;/span&gt;.
&lt;/td&gt;
&lt;/tr&gt;
&lt;/table&gt;
</source>
<p>
This will extract the date and dueClass properties from the page. It will also
obtain the dateFormat property (which is lazily instantiated), and use that to
format the date before inserting it.
</p>
<p>Java class</p>
<source xml:space="preserve">
public abstract class EnquiryPage extends BasePage
{
private Format _dateFormat;
public Format getDateFormat()
{
if (_dateFormat == null)
_dateFormat = new SimpleDateFormat("dd MMM yyyy");
return _dateFormat;
}
public abstract Date getDueDate();
public abstract String getDueClass();
}
</source>
</section>
</section>
</body>
</document>