This project has moved. For the latest updates, please go here.

Element Attributes in TOC

Topics: Questions
Jan 22, 2011 at 3:43 PM

Hello,

I have observed a trend in the presentation that I do not understand.
You can observe it even in the provided samples. Some elements with attributes have their attributes
displayed in the TOC as sub-nodes. But attributes of others are not displayed in the TOC.

Please can you explain why this is the case or it is a bug?

Best regards,
Paul 

Coordinator
Jan 22, 2011 at 11:18 PM
Edited Jan 22, 2011 at 11:20 PM

Hi Paul,

This depends on the schema. For example, let's consider the following schema:

<xs:element name="elementWithLocalAttributes">
  <xs:complexType>
    <xs:attribute name="localAtt1" type="xs:string" />
    <xs:attribute name="localAtt2" type="xs:token"/>
  </xs:complexType>
</xs:element>

<xs:attribute name="globalAtt1" type="xs:boolean" />
<xs:attribute name="globalAtt2" type="xs:decimal" />

<xs:element name="elementWithReferencesToGlobalAttributes">
  <xs:complexType>
    <xs:attribute ref="globalAtt1" />
    <xs:attribute ref="globalAtt2" />
  </xs:complexType>
</xs:element>

<xs:element name="elementWithNamedType" type="typeWithLocalAttributes" />
  
<xs:complexType name="typeWithLocalAttributes">
  <xs:attribute name="localAtt1" type="xs:int" />
  <xs:attribute name="localAtt2" type="xs:dateTime"/>
</xs:complexType>

<xs:complexType name="typeWithGlobalAttributes">
  <xs:attribute ref="globalAtt1" />
  <xs:attribute ref="globalAtt2" />
</xs:complexType>

The schema declares the following items:

  • The element elementWithLocalAttributes has two attributes that are declared together with the element.
  • Two global attributes globalAtt1 and globalAtt2.
  • The element elementWithReferencesToGlobalAttributes that does only reference these two global attributes.
  • The element elementWithNamedType that references a named complex type typeWithLocalAttributes that declares two attributes.
  • For completeness, there is also a named complex type typeWithGlobalAttributes that references the global attributes.

When processed by XSDDoc this results in the following TOC:

As you can see, only elements and types that declare attributes locally have them in the TOC. The general idea is that the TOC reflects who declares what; there are no duplicates. So this is not a bug but by design.

Does this make sense?

Thanks,
-Immo

Jan 23, 2011 at 5:54 AM

 

Hello Immo,
Thanks for the reply and for taken the time to explain all these. 

>>ImmoDoes this make sense?
Yes, it does.
Just wondering if anyone looking at the documentation will simply understand this. 

Another take on this presentation...how about this?

Best regards,
Paul. 

Coordinator
Jan 31, 2011 at 1:27 AM

I agree that the current presentation is not neccessarily easy to understand. However, the problem is that in my examples the attributes are locally scoped. Your suggestion seems reasonable to me although I have to admit that I belive the fundamental problem is still apparent. The user does not think in types but in elements and attributes. Moving the type specific parts from one node to the other does not neccesarily help. The user still has to know the type that defined them.

The only real solution that I see to this problem is writing the schema in a certain way up front. For example, you can define the schema so that it only uses global elements and attributes and all types are anonymous.

For a tool I believe one cannot solve this problem in a general way without making too many simplifying assumptions that are probably wrong (such as element names are unique).

Marked as answer by terrajobst on 2/15/2014 at 6:17 PM
Jan 31, 2011 at 2:02 AM

Hello Immo,

Thanks for the reply.

>>Immo: The user still has to know the type that defined them.

The suggestion takes advantage of one well-thought feature in your library, the use of icons.
This makes it easy to distinguish between the reference items and the owned items.

Any clicking on the attribute link in the right pane takes the user to the right page showing what is what about
that attribute, so I think this will not really be the case.

The other thoughts into this...

1. The presentation in the left (TOC) is simplified and similar for all elements. 
2. Most users of the schema documentation are not going to extend the schema, and will only need to know the
    attributes for the various elements they wish to use, global or local is not an issue for.
    Anyone looking further is trying to extend the schema, where it is applicable.
3. It took a page from your presentation of the Attribute Group. When researching on this for my original plan to do
   a similar library, I found presentations that displayed the Element/Attribute form in the TOC. I never liked it, since for
   longer element names, the TOC is difficult to use - having to adjust the horizontal scrollbar to view all.

Well, it is a suggestion :) There is currently no better presentation of the XML schema documentation than you did.

Best regards,
Paul.