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 ;-)

Joined: Sep 12, 2005
Posts: 28
Status: Offline

Joined: Aug 3, 2005
Posts: 72
Status: Offline

Creating a simple XSD
The first steps to create an XSD is to decide where you want the XSD to reside.  Normally the XSD should reside in a module in the schemas folder.   Hence the first this is to create a folder called schemas in the module of your choose.  One thing to note is that no matter where the XSD is located it can be used globally.  Now that the place where the XSD will reside has been created it is time to create the actual XSD file.  
1.	Create a new plan text file.
      a.	Click on the Wand that says New.  Pick a text file and then name the file simpleexample.xsd
2.	Edit the source code for the file simpleexample.xsd
3.	Put the following code in the file :

1<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
2	<xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>	
3	<xsd:element name="XmlContentDocSimpleTypes" type="OpenCmsXmlContentDocSimpleTypes"/>
4	<xsd:complexType name="OpenCmsXmlContentDocSimpleTypes">
5		<xsd:sequence>
6			<xsd:element name="XmlContentDocSimpleType" type="OpenCmsXmlContentDocSimpleType" minOccurs="0" maxOccurs="unbounded"/>
7		</xsd:sequence>
8	</xsd:complexType>
9	<xsd:complexType name="OpenCmsXmlContentDocSimpleType">
10		<xsd:sequence>
11			<xsd:element name="Title" type="OpenCmsString" />
12			<xsd:element name="Teaser" type="OpenCmsString" maxOccurs="3"/>
13			<xsd:element name="Text" type="OpenCmsHtml" />
14		</xsd:sequence>
15		<xsd:attribute name="language" type="OpenCmsLocale" use="required"/>
16	</xsd:complexType>
17</xsd:schema>
4.	A break down of the code is as follows (many of these descriptions come strait from the demo word for word)
Line 1: ?The root element provides the namespace declaration; this is always the same for each OpenCms XML content.  Simple put start with this line it stays the same always.?
Line 2: ?Inclusions of other schema definitions, this one has to be included always, followed by optional nested content XSDs.?  In this example there is only one very simple include that must be in every XSD.  
?	Side Note:  If you need to create nested XSDs then this is where you will be able to include the other XSD.  Then you will be able to use that XSD as a type which will be explained in lines 6 and 11 to 13.
Line 3:  ?The root element name and type of the XML content is defined here. The element name has to end with an ?s? (indicating a plural); the type must have exactly the same term with the prefix ?OpenCms?. ?
?	The name attribute should be just the name that you want to give to this XSD complex type with the suffix ?s?.
?	The type attribute is the name attribute with the prefix ?OpenCms? and the suffix ?s?.
Line 4: ?Definition of the complex type of the root element described in line 3. The sequence of this complex type describes one element.? 
?	The name attribute for xsd:complexType should be the same as the type attribute for xsd:element.
Line 5: Starts the sequence.
Line 6: ?Description of the child element: name and type follow the same restrictions as the root element and must have the same name and type value, but the trailing "s" has to be omitted (indicating a single element). The occurences of the element have to be set from none to unbounded as shown in the example.?
?	Make sure there is no ?s? on the end of these attributes.
?	Side Note:  If this XSD is included in another XSD then this type attribute will be what is used in lines 11 to 13.
Line 7: Ends the sequence.
Line 8: Ends the complex type.
?	This is the end of the plural (?s?) complex type
Line 9: Start of the second complex type definition.
?	This defines a single instance of the plural complex type.
?	The name attribute for this should NOT have the suffix ?s? at the end.
Line 10: Starts the sequence.
Lines 11 to 13: ?The element sequence can contain an unlimited number of element definitions. Each element must specify the corresponding data type in OpenCms and can contain restrictions of occurrences (with minOccurs and maxOccurs). If you do not enter minimum or maximum occurrences, the element has to occur exactly once. The definition of a default value (default) is possible, too.?
?	These lines define the basic elements that make up a single instance of the plural complex element.
?	If this XSD is included in another XSD then the type attribute defined in line 6 can be used as a basic type in the including XSD.
Line 14: Ends the sequence.
Line 15: ?The child element which is described by the second complex type definition must have an attribute named "language" of the type "OpenCmsLocale". This is fixed for every XML content except for nested contents.?
Line 16: Ends the singular complex type.
Line 17: Ends the Schema




Now that you have created a simple XSD the next step is to have it show up in New -> Structured content.
(If the XSD does not need to be able to be selected from OpenCms then you can stop here)


1.	Open the file opencms-modules.xml in your favorite editor.  This file should be located <opencms> WEB-INFconfig opencms-modules.xml.
2.	In this file locate the module where you created the XSD. 
        a.	This should look something like: 
        <module>
                  <name>name.of.module</name>
                    ?
         </module>
3.	Once you have found your module you will need to add or edit the node sets, <resourcetypes>, and <explorertypes>.
a.	Check to see if your module has these node sets if so then you will just need to add to them if not then you will need to create them.
       b.	This tutorial is going to assume you have to create the node sets.
4.	Creating the node set <resourcetypes>
?	Sample Code for <resourcetypes>:
1            <resourcetypes>
2                <type class="org.opencms.file.types.CmsResourceTypeXmlContent" name="simpleexample" id="77">
3                    <properties>
4                        <property>
5                            <name>content-conversion</name>
6                            <value type="shared"><![CDATA[cleanup;xhtml]]></value>
7                        </property>
8                        <property>
9                            <name>template-elements</name>
10                            <value type="shared"><![CDATA[/alkacon-documentation/documentation-xmlcontent/simpleexample/simplecontentdetails.jsp]]></value>
11                        </property>
12                    </properties>
13                    <param name="schema"> /system/modules/my_module/schemas/simpleexample.xsd</param>
14                </type>
15            </resourcetypes>

?	Break down of the sample code:
Line 1: This starts the <resourcetypes> node set.  If there is one already in your module then do not create a new one.
Line 2: There can be many <type> ?</type> inside of one <resourcetypes>.
?	The class attribute defines that we wish this resource to be of the type for XML content, so that it will be put with other XML content, what OpenCms calls structured content.
?	The name attribute defines the name of this resource type.
?	The id attribute: do to lack of documentation from OpenCms it is our understanding at this time that the id needs to be unique though out the entire file.  Meaning there no two <type> should have the same id.
Line 3: This starts the properties node.  There can be many different properties in this node
?	These properties are from OpenCms.  In OpenCms if you click on the file simpleexample.xsd and then select its properties you will see all the properties that can be set here.
?	The properties set here will be the default properties for any new structured content of this type.  
?	The properties can be changed after creation these are only the defaults.
Line 4: This starts one of the properties in the <properties> node.
?	Each <property> tag needs to have a name and value tag
Line 5: The Name tag is the name of the property as it appears in OpenCms
?	See the notes for Line 3 to find the names for the properties that can go here.

Line 6: This is the value that will appear in the properties of the file once it is created in OpenCms.
?	Do to lack of documentation from OpenCms it is our understanding at this time that the type should always be ?shared?
?	The text in the value node will be what appears as the value for the property in OpenCms
Line 7: This closes the property tag
Lines 8 to 11: This is another property that is defined.
?	The property defined in these lines defines the default JSP page which will be used to display the structured content.
Line 12: This closes the properties tag
Line 13: This is a parameter that defines where the schema can be found in OpenCms which defines the XSD.  The text for this should be the path to the XSD you created.
Line 14: This closes the type.
Line 15: This closes the resourcetype.  There can be an unbounded number of <type> tags in the <resourcetype> tag
?	For example:
	<resourcetype>
			<type>
				?
			</type>
			<type>
				?
			</type>
			<type>
				?
			</type>
			?
		</resourcetype>
5.	Creating the node set <explorertypes>  
      I.	Sample Code for <explorertypes> :
1            <explorertypes>
2                <explorertype name="simpleexample" key="fileicon.simpleexample" icon="article.gif" reference="xmlcontent">
3                    <newresource page="structurecontent" uri="newresource_xmlcontent.jsp?newresourcetype=simpleexample" order="54"/>
4                    <accesscontrol>
5                        <accessentry principal="GROUP.Administrators" permissions="+r+v+w+c"/>
6                        <accessentry principal="GROUP.Projectmanagers" permissions="+r+v+w+c"/>
7                        <accessentry principal="GROUP.Users" permissions="+r+v+w+c"/>
8                    </accesscontrol>
9                </explorertype>
10            </explorertypes>
     II.	Break down of the sample code:
Line 1: This starts the <explorertypes> node set.  If there is one already in your module then do not create a new one.
Line 2: This is begins a single explorertype.
?	The name attribute should be the same as the name you used for the <type> in step 4. Creating the node set <resourcetypes> above.
?	The key attribute is used to set the name that will appear in the list of structured content in OpenCms
o	This points to an entry in the workplace.properties folder in your module
?	Icon this is the icon that will appear in OpenCms for this structured content.
?	The reference should be xml_content
Line 3: This tag defines some variables that OpenCms needs
?	The page attribute for structured content should be ?structurecontent?.
?	In the uri attribute the left hand side of the equeation should be what is above.  The right hand side of the equation should be the same as the name in Line 2.
?	The order attribute should be different from the other orders.
Line 4 to 8: This sets the access controls.
Line 9: Ends the <explorertype>
Line 10: Ends the <explorertypes>
?	There can be zero to many <explorertype> inside of the <explorertypes> tags.
?	For example
	<explorertypes>
			<explorertype>
				?
			</explorertype>
			<explorertype>
				?
			</explorertype>
			<explorertype>
				?
			</explorertype>
			?
		</explorertypes>

You will now have to restart Tomcat and OpenCms.  Now you can create the a simpleexample xml file as easy as New -> Structured content -> simpleexample



Note: If the name does not look like what you want in New -> Structured content, then you need to work with your module?s workplace.properties file.  Setting up the fileicon.simpleexample correctly.

Intro
1.	Normally XSDs are stored in a module.  Select one to use or create a new one.
      a.	For this tutorial we will assume the module is named my_module and the structure to the XSD schemas is as follows: system/module/my_module/schemas/ my_xsd.xsd
      b.	Create a plan text file and name it my_xsd.xsd
      c.	my_xsd.xsd will be the XSD schema that will include two different XSD schemas to create on complex schema.
2.	The two XSDs that will be included in my_xsd.xsd will be externallink.xsd and internallink.xsd.   
      a.	externallink.xsd is shipped with the demos for OpenCms 6.0 and should be located at: /system/modules/org.opencms.frontend.templateone.modules/schemas/externallink.xsd.  The following is the code for the schema.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>	
	<xsd:element name="ExternalLinks" type="OpenCmsExternalLinks"/>	
	<xsd:complexType name="OpenCmsExternalLinks">
		<xsd:sequence>
			<xsd:element name="ExternalLink" type="OpenCmsExternalLink" minOccurs="0" maxOccurs="unbounded"/>
		</xsd:sequence>
	</xsd:complexType>
	<xsd:complexType name="OpenCmsExternalLink">
		<xsd:sequence>
			<xsd:element name="Href" type="OpenCmsString" />
			<xsd:element name="Description" type="OpenCmsString" minOccurs="0" />		
			<xsd:element name="NewWin" type="OpenCmsBoolean" default="false" />
		</xsd:sequence>
		<xsd:attribute name="language" type="OpenCmsLocale" use="optional"/>
	</xsd:complexType>
	<xsd:annotation>
		<xsd:appinfo>
			<resourcebundle name="org.opencms.frontend.templateone.modules.workplace"/>
			<layouts>
				<layout element="Href" widget="LinkGalleryWidget" />			
			</layouts>
		</xsd:appinfo>
	</xsd:annotation>  
</xsd:schema>

      b.	internallink.xsd is shipped with the demos for OpenCms 6.0 and should be located at: /system/modules/org.opencms.frontend.templateone.modules/schemas/internallink.xsd.  The following is the code for the schema.


<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
	<xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>	
	<xsd:element name="InternalLinks" type="OpenCmsInternalLinks"/>
	<xsd:complexType name="OpenCmsInternalLinks">
		<xsd:sequence>
			<xsd:element name="InternalLink" type="OpenCmsInternalLink" minOccurs="0" maxOccurs="unbounded"/>
		</xsd:sequence>
	</xsd:complexType>
	<xsd:complexType name="OpenCmsInternalLink">
		<xsd:sequence>
			<xsd:element name="Href" type="OpenCmsVfsFile" />
			<xsd:element name="Description" type="OpenCmsString" minOccurs="0" />		
			<xsd:element name="NewWin" type="OpenCmsBoolean" default="false" />
		</xsd:sequence>
		<xsd:attribute name="language" type="OpenCmsLocale" use="optional"/>
	</xsd:complexType>
	<xsd:annotation>
		<xsd:appinfo>
			<resourcebundle name="org.opencms.frontend.templateone.modules.workplace"/>
		</xsd:appinfo>
	</xsd:annotation>  
</xsd:schema>

My_xsd.xsd
1.	Edit the source code of my_xsd.xsd
2.	The Code for this XSD is as follows:

1<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
2	<xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>	
3	<xsd:include schemaLocation="opencms://system/modules/org.opencms.frontend.templateone.modules/schemas/internallink.xsd"/>
4	<xsd:include schemaLocation="opencms://system/modules/org.opencms.frontend.templateone.modules/schemas/externallink.xsd"/>
5	<xsd:element name="My_xsds" type="OpenCms My_xsds"/>
6	<xsd:complexType name="OpenCms My_xsds">
7		<xsd:sequence>
8			<xsd:element name=" My_xsd" type="OpenCms My_xsd" minOccurs="0" maxOccurs="unbounded"/>
9		</xsd:sequence>
10	</xsd:complexType>
11	<xsd:complexType name="OpenCms My_xsd">
12		<xsd:sequence>
13			<xsd:element name="Titlelist" type="OpenCmsString" />
14			<xsd:element name="InternalLink" type="OpenCmsInternalLink" minOccurs="0" maxOccurs="unbounded"/>
15 			<xsd:element name="ExternalLink" type="OpenCmsExternalLink" minOccurs="0" maxOccurs="unbounded"/>
16		</xsd:sequence>
17		<xsd:attribute name="language" type="OpenCmsLocale" use="optional"/>
18	</xsd:complexType>
19</xsd:schema>
3.	A break down of the code is as follows:
Line 1: Opens the Schema and sets the name space.
Line 2: This is the include statement that must be in any and all XSDs.
Line 3: This is the include statement for the internallink.xsd.  Now my_xsd can use the complexType OpenCmsInternalLink.
Line 4: This is the include statement for the externallink.xsd. Now my_xsd can use the complexType OpenCmsExternalLink.
?	Now that the two XSDs have been included the schemas they defined can be used just as if they were a basic type, like OpenCmsString.
Line 5: Declares the element.
Line 6 to 10: Sets up the plural complex type (this follows the rules as when creating a simple XSD)
Line 11 to 18: sets up the singular complex type.
?	Lines 14 and 15 use the complexType that was included in lines 3 and 4 respectivly. 
Line 19: Closes the schema
4.	You have now created a complex/nested XSD. 
5.	It is the same process to make a complex/nested XSD appear in the New -> structured content as it was for a simple XSD.

Joined: Mar 20, 2006
Posts: 18
Status: Offline

Joined: Mar 20, 2006
Posts: 18
Status: Offline