/*
   This schema specifies the format for describing a BrainML interface for
   querying or submitting to a BrainML data server.  An instance document
   conforming to this schema describes a "view" on the data structure defined
   by a BrainML data model.  The view refers to and incorporates elements from
   a BrainML model in a specified configuration adding user interface
   information including:

   () elements to show or hide;
   () instructional or descriptive material for elements;
   () display layout hints.

   Views are used to describe both web and graphical application interfaces.
*/

targetNamespace "urn:bml/brainml.org:internal/ModelView/1"
import "http://www.w3.org/2001/xml.xsd" namespace "http://www.w3.org/XML/1998/namespace"

/*
   Root element for a model view document.  Contains a collection of pages.
*/
element modelView { modelView-type }
complexType modelView-type {
   ( page+, )
   /* Specifies the model this view is for. */
   required attribute model { xs:anyURI }
   /* Base namespace for model element references beneath this item. */
   attribute xml:base
}

/* 
   Specifies a "page" in this view.  In a web interface, this might correspond
   to an actual web page.  In a workstation application, this might correspond
   to a window or tab-pane.  Contains a collection of items.
*/
element page { page-type }
complexType page-type {
   ( instructions?, ( item | br )+ )
   /*
      Identifier for the page, used by software to track it.  Should be
      unique within the document. */
   required attribute id { xs:string }
   /* Whether the fields with the same name under different items beneath this
      page should be merged and shown as a single field.  This is most useful
      for query interfaces where, for example, several items might have a
      'last_name' field but the user does not care about the distinction
      between them and just wants to search by name. */
   attribute combineFields { xs:boolean }
   /* Whether the fields for items beneath this page should be grouped together
      or split into sections by item. */
   attribute hideItems { xs:boolean }
   /* Base namespace for model element references beneath this page. */
   attribute xml:base
}

/* Specifies an item in the view, corresponding to a BrainML entity. */
element item { item-type }
complexType item-type {
   (  instructions?,
      ( item | \group | \field | link | br )* )
   /*
      Identifier for item.  This is used by the software processing view a
      view document to index this item.  It should be unique within the
      container.  If an id is not specified, the name of this item is used
      instead.
    */
   attribute id { xs:token }
   /*
      Namespace (BrainML model URN) of this item.  If unspecified, the
      prevailing xml:base from the container or ancestor is used.
   */
   attribute \namespace { xs:anyURI }
   /* The item's name in the model. */
   required attribute name { xs:token }
   /* Base namespace for model element references beneath this item. */
   attribute xml:base
   /* Use to override what is specified in the model, or for top-level items
      whose container cannot be determined (if not specified, will default
      to minOccurs = maxOccurs = 1).  Both minOccurs and maxOccurs must be
      present here if either is. */
   attribute minOccurs { xs:nonNegativeInteger }
   /* Use to override what is specified in the model, or for top-level items
      whose container cannot be determined (if not specified, will default
      to minOccurs = maxOccurs = 1).  Both minOccurs and maxOccurs must be
      present here if either is. */
   attribute maxOccurs { xs:token }
   /* If true, item will be displayed internally to parent item, as if it were a
      labeled subset of its fields, rather than a hierarchically contained
     member. */
   attribute minor { xs:boolean }
   /* If true, item will be displayed as a list item with other siblings of
      same type, rather than individually. */
   attribute \list { xs:boolean }
   /* User interface category.  This may be used to specify that special
      rendering should be used for this field.  The value must be recognized
      by the software doing the rendering or it will be ignored. */
   attribute category { xs:token }
}

/*
   Contains text providing any description or special instructions pertaining
   to an item.  In addition, if child "add" is present, its contents will be
   used to provide instructions when presenting the option to ADD an item of
   this type to the structure.
*/
element instructions { mixed ( add? )
   /* Instructions to use when interface presents option to add a new item
      of this type. */
   element add { xs:string }
}

/* Contains a collection of fields that should be presented as a unit. */
element \group { group-type }
complexType group-type {
   ( \field | link | br )*
   /* Identifier for group.  Required since there is no name. */
   required attribute id { xs:token }
}

/* Specifies a field of a model entity to be displayed under a view item. */
element \field { field-type }
complexType field-type {
   ( instructions?, extLink* )
   /*
      Identifier for field.  This is used by the software processing view a
      view document to index this item.  It should be unique within the
      item.  If an id is not specified, the name of this field is used
      instead.
    */
   attribute id { xs:token }
   /* The field's name in the model. */
   required attribute name { xs:token }
   /*
      Boolean attribute (valid values: { 'true', 'false' }) specifying whether
      this field MUST take on a value in an instance.
   */
   attribute \required { xs:boolean }
   /*
      Specifies the number of columns this field's value should be given in a
      columnar user interface display.
   */
   attribute colspan { xs:positiveInteger }

   /* Value to assume for field if not given. */
   attribute defaultValue { xs:string }

   /* Value to initialize field to (e.g. in user interface form). */
   attribute initialValue { xs:string }

   /* User interface category.  This may be used to specify that special
      rendering should be used for this field.  The value must be recognized
      by the software doing the rendering or it will be ignored. */
   attribute category { xs:token }

   /* Set false if this field may NOT be used in a template to fill out other
      copies of this object.  For example, when submitting data, if more than
      one instance of this object can occur, but the value on this field is
      often shared between them, it is left true.  If the data is always
      unique per-item, explicitly set to false. */
   attribute inTemplate { xs:boolean }
   /* Use to override what is specified in the model.
    * Both minOccurs and maxOccurs must be present here if either is. */
   attribute minOccurs { xs:nonNegativeInteger }
   /* Use to override what is specified in the model.
    * Both minOccurs and maxOccurs must be present here if either is. */
   attribute maxOccurs { xs:token }
}

/* Specifies that one of a view entity's linked entities in the model should
   be exposed to the user, so they may choose entities in a view instance
   to link to. */
element link { link-type }
complexType link-type {
   /*
      Identifier for link set.  This is used by the software processing view a
      view document to index this item, and to present a display name to the
      user.  It should be unique within the containing item, and inform the
      user as to the usage of this type of link.
    */
   attribute id { xs:token }
   /* Value should be a comma-separated list of IDs used elsewhere in
      this file. */
   required attribute targetTypeID { xs:token }
   /* Use to override what is specified in the model.
    * Both minOccurs and maxOccurs must be present here if either is. */
   attribute minOccurs { xs:nonNegativeInteger }
   /* Use to override what is specified in the model.
    * Both minOccurs and maxOccurs must be present here if either is. */
   attribute maxOccurs { xs:token }
}

/*
   Specifies an external link to a resource.  The text of the link is
   created by substituting a field's value for the value '$$$' in refTemplate.
   External links can be made from either entities (in which case the fieldName
   attribute must be specified) or fields (fieldName is implied and should be
   left blank).  The link will be rendered in a form appropriate to the view's
   display.  For example, in an HTML-based display, a hyperlink will be
   rendered.
*/
element extLink { extLink-type }
complexType extLink-type {
   /* Template for reference.  The value '%%%' will be substituted by field's
      value for final reference.  ('%%%' may be absent.) */
   required attribute refTemplate { xs:string }
   /* Template for displaying reference.  The value '%%%' will be substituted
      by field's value for final reference.  ('%%%' may be absent.) */
   required attribute refTitleTemplate { xs:string }
   /* Specifies whether external link should be displayed at level of item.
      If true, the link will be displayed at the item level;  if false or
      absent, link will be displayed at field itself. */
   attribute displayAtItemLevel { xs:boolean }
}

/*
   Separator marker akin to HTML specifying a line break in the user interface
   display.
*/
element br { br-type }
complexType br-type { }