Hello Seam Developers,
In my quest to better understand the pages.xml file (and accompanying schema), I've been going through the pages.xsd file and I've come up with some suggestions regarding the pages.xsd - pages schema 2.0 (although these also apply to 2.1 as well).
1.) Enforcement of schema rules
The pages element contains a sequence of a choice between conversation elements and page elements unbounded so as many as you want, and after that, an unbounded number of exception elements. However, if one places the exceptions up at the top (i.e., before any page or conversation elements), the application runs just fine. IOW, the schema rule is not being enforced. This rule should either be enforced by the application or replaced with:
<xs:element name="pages"> <xs:complexType> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <xs:element ref="pages:conversation"/> <xs:element ref="pages:page"/> <xs:element ref="pages:exception"/> </xs:sequence> <xs:attributeGroup ref="pages:attlist.pages"/> </xs:complexType> </xs:element>
Same issue with the exception element ... the end-conversation element having to be at the beginning is not being enforced. I'm assuming that this should be enforced.
Other rules not being enforced (or that should ... see view-id attribute in redirect's view-id attribute) include:
- exception element doesn't enforce order of end-conversation, http-error redirect respectively
- both http-error and redirect allow many messages, schema reports to only allow zero or one
- redirect view-id attribute should be of type IDREF or xs:keyref, don't want to point to a page that doesn't exist right?
- http-error error-code attribute should be required(?)
These enforcement rules should either be taken out or they should be enforced. Leaving as is causes confusion and unwanted bug reports which may not in fact be due to bugs.
2.) Using Regex to clarify allowable values
The use of regex would greatly help narrow what a user (us app developers). For example, the view-id attribute of the page element accepts ... a view id. Why not restrict it like this:
<xs:attribute name="view-id"> <xs:simpleType name="view-id"> <xs:restriction base="xsd:NMTOKEN"> <xs:pattern value="/.*"/> </xs:restriction> </xs:simpleType> </xs:attribute>
If one wanted, a narrowing of scope could further the selection to something like:
<xs:attribute name="view-id"> <xs:simpleType name="view-id"> <xs:restriction base="xsd:NMTOKEN"> <xs:pattern value="/.*\..*"/> </xs:restriction> </xs:simpleType> </xs:attribute>
<xs:attribute name="view-id"> <xs:simpleType name="view-id"> <xs:restriction base="xsd:NMTOKEN"> <xs:pattern value="/.*\.(\.seam|\.html|\.xhtml|.\jsp)"/> </xs:restriction> </xs:simpleType> </xs:attribute>
But that would probably be too restrictive (someone might complain that they can't create a page called index.monkey)
Restrict page element's
conversation attribute to being token
scheme to being either http or https
3.) Schema Annotation/Documentation
Although the new 2.1 pages xsd has been fleshed out a bit more (and even annotation and documentation elements are included now), there is minimal documentation inside of this schema. Simply stating the obvious (e.g., 'Page action' for the action element) doesn't help app developers fully understand the intentions of particular elements. Fleshing the xsd schema out more will also help (you) the framework developers in solidifying the contract each element has with API calls possibly written by someone else.
This sort of check really should be performed at the beginning of the startup procedure and belch validation exceptions if the user has not provided a valid pages.xml file.
Anyways, these are the ones that I've had a chance to play with so there could be others. I hope this doesn't come off as trolling, intonation gets lost in forum posts and so I just wanted to be clear that I'm not writing this out of anger but rather enthusiasm about this framework and particularly understanding the pages.xsd document and being able to use it correctly. One thing that I've been really trying to avoid is potentially filing out a bug report when in fact it's simply user error ... that would be embarrassing.
Anyways, if need be I will file a JIRA report. Let me know ...