[opencms-dev] Templates in XML

[Gonzalez, Arnau (GE Consumer Finance, consultant)]

This was sent in this mailing list before, have a look at it.

Arnau



Here's the short overview about how to create XML content definitions. Feel
free to ask additional questions if something seems inclomplete.

1. Start with the XML schema
You first need to define the XML content structure. To do this, create an
XML schema (currently this is just a "plain" file). The XML schema mut
follow the layout of the demo files. Check out "/xmlcontent/article.xsd" and
all files in "/system/modules/org.opencms.frontend.templateone/schemas/"
which give you a couple of examples. Please note that the layout is
mandatory, in case you make any mistake it wont word. A fine point is that
there's always an "inner" and "outer" node name, e.g. "article" and
"articles". The "outer" name _must_ be the inner name with an "s" appended.
For the current choice of available data types check the demos and the file
"opencms-vfs.xml". For the beginning, I recommend you start with a very
small schema, maybe based on "article.xsd" where you _remove_ most of the
nodes, and rename the schema to "myarticle". Just leave the title data
field.

The first schema might look like this:
<?xml version="1.0" encoding="UTF-8"?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
	
	<xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>

	<xsd:element name="myarticles" type="OpenCmsMyArticles"/>
	
	<xsd:complexType name="OpenCmsMyArticles">
		<xsd:sequence>
			<xsd:element name="myarticle"
type="OpenCmsMyArticle" minOccurs="0" maxOccurs="unbounded"/>
		</xsd:sequence>
	</xsd:complexType>

	<xsd:complexType name="OpenCmsMyArticle">
		<xsd:sequence>
			<xsd:element name="title" type="OpenCmsString" />
		</xsd:sequence>
		<xsd:attribute name="language" type="OpenCmsLocale"
use="required"/>
	</xsd:complexType>

	<xsd:annotation>
		<xsd:appinfo>
			<mapping element="Title" mapto="property:Title" />
		</xsd:appinfo>
	</xsd:annotation>  
</xsd:schema>



2. Create a content with the new schema. 
Since the schema is not yet available for creating "new" files, you must do
that manually. Create a new file of type "Generic XML content". This will be
just an empty file. Now open that file with "Edit controlcode". Then supply
a valid XML for the schema, like this:

<?xml version="1.0" encoding="UTF-8"?>

<myarticles xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="opencms://sites/default/xmlcontent/myarticle.
xsd">
  <myarticle language="en">
    <title><![CDATA[Sample article 1]]></title>
  </myarticle>
</mayrticles>

The fine point here's the pointer to the XML schema in the VFS using
xsi:noNamespaceSchemaLocation="opencms://sites/default/xmlcontent/myarticle.
xsd". You mut point to the location of your schema here.

Note that the "Edit controlcode" editor will not allow you to save the
content if either the schema contains errors, or the XML is not formed
according to the schema. So if you can't save, check that both the schema
and the XML is vaild. Once you are able to save, you are certain that it
worked. 


3. Open the created file using "Edit". 
Now you should see the "nice" editor, that displays the node name "title"
and an input field for that. 


4. Create a "detail" page. 
The demo contains a "full featured" example. Here's like the "minimum
version", without a template:

<%@ taglib prefix="cms" uri="http://www.opencms.org/taglib/cms" %>

<cms:contentload collector="singleFile" param="opencms:uri" editable="true">
<h1><cms:contentshow element="Title" /></h1>
</cms:contentload>

Save this file as "mydetail.jsp".


5. Connect the detail page to the XMl content using the "template-elements"
property.
At this point, I recommend moving everything into a new folder, called e.g.
"myfolder". This folder should now contain the XML schema, the one
"myarticle" created and the detail page "mydetail.jsp". Note that you must
manually correct the schema location in the "myarticle" since the file was
moven in the VFS.

Now, open the properties of "myfolder", and switch to "Advanced" mode.
Locate the "template-elements" property on the lower half of the screen.
Into this propety you must point to the location of the detail page, so add
"/myfolder/mydetail.jsp" as propety value. 

Save the properties and go into the "myfolder" again. Click on the created
"myarticle". It should now be displayed using the created detail page. Note
that the reason why in our demos all XML files and with ".html" is to make
sure the "html" mimetype is used. If your XMl content does not end with
.html, there might be issues displaying it correctly because of a wring mime
type. 


6. Create an overview list page
Now create a JSP page "mylist.jsp" in "myfolder". The mimimum version might
look like this:

<%@ taglib prefix="cms" uri="http://www.opencms.org/taglib/cms" %>

<cms:contentload collector="allInFolderDateReleasedDesc"
param="/myfolder/myarticle_${number}.html|11" editable="true">
<h3><cms:contentshow element="Title" /></h3>
</cms:contentload>

Click on the page. It should now display your single myarticle. Note that
you can now create a new article using the "wizard wand". Add some more
myarticles. They will be named "myarticle_0001.html" and up. 

The "param" attribute controls what files are actually listed.
param="/myfolder/myarticle_${number}.html|11" translates to: All contents of
type 11 (generic XML content) in "/myfolder/". New files should be named
"myarticle_${number}.html". You can also get the folder part from a property
by using the "property" attribute and leavin this out of "param", see the
provided demo for that.


7. Localizing the XML content editor and providing help texts
Check the folder
"/system/modules/org.opencms.frontend.templateone.xmlcontentdemo/classes/org
/opencms/frontend/templateone/xmlcontentdemo/". If contains the workplace
translations and lables for the editor. Syntax should be pretty clear. Note
that you must restart OpenCms / Tomact if you make changes to one of the
properties files. Note that if you create your own module, the "classes"
folder must get exported as export point. 


8. Add own resource type and workplace context menu
Last thing to do is to add an own resource type for you new content. Check
out the "opencms-vfs.xml" in the WEB-INF/config folder. There you should
find the node for the "article" content. Duplicate this node for your
"myarticle". You also see that it points to the location of the schema. You
also must give your type a new number. This may look like this:

<type class="org.opencms.file.types.CmsResourceTypeXmlContent">
	<param name="resource.type.id">13</param>
	<param name="resource.type.name">myarticle</param>
	<param name="schema">/sites/default/myfolder/myarticle.xsd</param>
</type>			

Then add the context menu, which is done in "opencms-workplace.xml", and it
may look like this:

<explorertype name="myarticle" key="fileicon.myarticle" icon="myarticle.gif"
reference="xmlcontent">
	<newresource
uri="newresource_xmlcontent.jsp?newresourcetype=myarticle" order="25"/>
</explorertype>	

Note that the "key" refers to a localization entry, so this must be located
in a workplace property file (see 7). The image "myarticle.gif" must be
located in "/system/workplace/resources/filetypes/". 

You need to restart OpenCms after these changes are made. After this, you
should be able to create a new "myarticle" type with the "new" function in
the workplace.


That's all for now. I'm sure I forgot something, so feel free to ask more
"to the point" questions ;-)

Best Regards,
Alex.

Alexander Kandzior
Alkacon Software - The OpenCms Experts
http://www.alkacon.com