Requirements and limitations for portlets that support XDIME markup

There are requirements and limitations for portlets that support XDIME markup. These portlets can use the standard portlet API.

Requirements

A portlet that generates XDIME markup must observe the following requirements:

A portlet can support multiple markup types. However, if it is added to a page that supports XDIME markup, its portlet.xml must indicate that the portlet supports the XDIME markup. The XDIME markup can be added to a portlet by either editing its portlet.xml. Or you can select the XDIME Markup when using the Mobile Portal Toolkit New Project wizard to create a portlet application project.
When the portlet implements the standard portlet API, it specifies the MIME type for XDIME rather than the XDIME markup name in portlet.xml. The XDIME MIME type is x-application/vnd.xdime+xml.
See the following portlet.xml excerpt for an example standard portlet that supports both HTML and XDIME markup for the view, edit, and configure modes:
```
<supports>
			<mime-type>x-application/vnd.xdime+xml</mime-type>
			<portlet-mode>view</portlet-mode>
			<portlet-mode>edit</portlet-mode>
			<portlet-mode>config</portlet-mode>
		</supports>
		<supports>
			<mime-type>text/html</mime-type>
			<portlet-mode>view</portlet-mode>
			<portlet-mode>edit</portlet-mode>
			<portlet-mode>help</portlet-mode>
			<portlet-mode>config</portlet-mode>
		</supports>
```
If you are developing a standard portlet, you must also specify the XDIME MIME type as the content type in your Java™ source code and in your XDIME JSPs.
- To set the content type in the Java source code of the portlet, invoke setContentType() method of the response object in the portlet methods, such as doView(), doEdit(), before invoking the XDIME JSPs. See the following code examples:
```
response.setContentType(request.getResponseContentType());
```
  or
```
response.setContentType("x-application/vnd.xdime+xml");
```
- To set the content type in the portlet XDIME JSPs, use the contentType attribute of the page directive as shown here:
```
<%@ page session="false" contentType="x-application/vnd.xdime+xml" %>
```
If a portlet includes its Multi-Channel Server policies in its WAR file, Mobile Portal Toolkit was used to create Multi-Channel Server policies for the portlet. The policy files must be created under the WebContent/mcs-policies directory in the portlet WAR file.
Note: A portlet can use policies that are not included in its WAR file. See the topic Portlet Specific Policies for more details.
The XDIME aggregator adds portlets to a page by inserting them into a region in the aggregator layout. The portlet must place all of its content within a canvas element, for example:
```
<canvas layout="/portlet_layout_name.mlyt" type="portlet">
rest of portlet markup goes here
</canvas>
```
where portlet_layout_name is the name of the layout policy used by the portlet.
Note: The layout used by the portlet may contain regions that include other canvasses.
XDIME elements are case-sensitive, so be sure to enter the elements in lowercase only. For example, <img src="..."/> is a valid XDIME element but <IMG src="..."/> is not valid.
The portlet <display-name> element in web.xml should not contain spaces. If spaces are used, the portlet policies are not imported into the Multi-Channel Server database when the portlet is installed.

Limitations

The following limitations apply to portlets that generate XDIME markup:

Standard XDIME portlets cannot use WSRP.
Standard XDIME portlets cannot use form fragments in a layout policy. If you want to use form fragments, you must create a portlet that uses the IBM® portlet API.
JavaServer Faces cannot be used with XDIME portlets.
Click-to-action portlet integration is not supported for XDIME portlets.
Portlets must not provide their own theme policies because device limitations prevent Multi-Channel Server from generating style rule markup that works for all devices. Style rules needed by portlets must be included in the theme policies used by the XDIME aggregator.
The portlet help mode is not supported by the XDIME aggregator.
Form input field variable names must not contain periods as certain devices cannot handle periods as delimiters for form input variable names. A better delimiter to use is an underscore "_" as shown in the following examples:
Bad example of a variable name:
```
<xftextinput name="my.input.field.1" />
```
Good example of a variable name:
```
<xftextinput name="my_input_field_1" />
```