The MForm consists of several definition controls, that should be used together.
These controls are:
- the
mf:Root control
- the
mf:Branch control
- the
mf:Choice control
- the
mf:Leaf control
These controls reflect different XML data definitions.
All of the described MForm definition controls inherit from one common class:
Offspring. This class is responsible for all the common definition controls
functionality:
All of these controls have the DisplayName property. This property
can be used in different contexts (as a text label, a text in a tab, or a title
text), which should describe the control.
The MinOccurs and MaxOccurs properties
All of these controls have properties MinOccurs and MaxOccurs,
of which MinOccurs must be greater or equal zero, and MaxOccurs
must be greater than zero. By default both of these properties are equal 1.
In the process of onpage control rendering, based on the MinOccurs and MaxOccurs
properties and the input XML, each of the MForm definition controls generates
an appropriate number of MForm item controls.These are:
- the
RootItem control in the Root control,
- the
BranchItem control in the Branch control,
- the
ChoiceItem control in the Choice control,
- the
LeafItem control in the Leaf control,
These controls can be manipulated once thay are created, but they cannot be created
by the user manually. This is similiar to the Repeater and RepeaterItem
controls. The item controls are child controls of the definition controls
and can be found inside the Controls property.
Generally, the definition controls are specified in the .aspx definition
but have no representation in the generated .html code. The item controls
on the other hand are not defined directly in the .aspx (though they are defined
indirectly, because changing the proprties of the definition control will
influence the way the item controls are generated) but they are visible
in the .html code.
From the XML point of view, the definition controls keep information about
the XML data definition which may repeat, whereas the item controls are
bound to corporeal XML nodes.
The definition control is aware of its child item controls through
the Items property. The item controls are aware of its definition
control through its Basis property.
The Mode property is used to define the way MForm control should behave
on the form. The default mode is the Edit mode in which adding, editing
and removing are enabled. The other mode is the View mode, in which
the control only shows the value. The Mode property is inherited in
the MForm controls hierarchy, so if the Root control is in View
mode, all of its MForm descendant controls will also be in View mode
(unless the property is overriden by explicitly specifying Edit mode
in the descendant control).
The example of how Mode property works can be found on
this page.
The Name property is the string representation of the offspring control's
qualified name. Some offsprings, like Branch and Leaf
represent definitions of XML nodes. For those controls, the Name property
is very important as it will denote which XML node will be read into the control,
as well as what will be the XML output. For other controls, like Root
and Choice this property does not affect the XML input and output.
However it is still very important, as this property is used when using the
xpath-like MForm control tree query language.
The prefixes in the qualified name are resolved through the Root's Manager
property, which is a XmlNamespaceManager created from UriMappings definitions.
-
Let's assume such Root's
UriMappings property:
<UriMappings>
<mf:UriMapping Prefix="" Namespace="urn:defaultNamespace" />
<mf:UriMapping Prefix="x" Namespace="urn:mysterious.x.namespace" />
</UriMappings>
- Example:
-
A branch control that has the Name property set to
SampleElement reflects
a definition of XML elements whose local name is "SampleElement"
and namespace uri is "urn:defaultNamespace"
- Example 2:
-
A leaf control that has the Name property set to
x:OtherElement reflects
a definition of XML elements whose local name is "OtherElement"
and namespace uri is "urn:mysterious.x.namespace"
When the MForm controls tree is fed with an input XML, this XML document nodes are
recursively matched with controls. If the match is found, the matched XML node becomes
control's data source. The Navigator property is a XPathNavigator
object created from this dta source.
XML is a tree structure in which order of nodes matters. To make MForm display less
coupled with the XML definition, the Ordinal property was introduced.
With the use of the Ordinal property, the order in which sibling MForm
controls are placed is irrelevant. The corresponding XML nodes will be ascendingly
sorted with the use of the property.
The ParentItem and ParentBasis properties
The OffspringsOwner base class
All controls except the Leaf control inherit from the OffspringsOwner
class, meaning that they may contain other MForm definition controls inside. These
MForm definition controls as well as other controls may be defined in the
Contents property.
The Contents property is a template that may consist of any controls,
particularly it my contain other MForm definition controls as its descendants. All
of these controls are instantiated in the child items of the offspring owner control.
- Example:
-
A Branch control with the MinOccurs property equal 3,
having Contents property equal
<asp:Label runat="server" Text="SomeText" />
<mf:Branch runat="server" Name="InnerBranch" >
...
<mf:Branch />
will render at least 3 BranchItem controls. Each of these BranchItem
controls will have the SomeText label and the InnerBranch
branch controls instantiated inside itself. Effectively, 3 SomeText
labels and 3 InnerBranch branches will be instantiated.
Again, if the InnerBranch branch definition control had MinOccurs
property equal more than 1, its Contents property would be instantiated
multiple times inside its BranchItem child items.
The root control reflects the xml document root.
The mf:Root control needs to be used as the root of conrols tree. Using
the mf:Root control inside the tree of MForm controls will result in
starting a new inner MForm control and is generally considered inappropriate.
The mf:Root control, as other OffspringsOwner controls,
has a Contents property. The Contents property may contain
any inner controls, particularly it may contain other MForm definition controls.
Prefix-namespace mappings
To be able to use the same namespace manager for the whole MForm tree, and to be
able to define this manager in .aspx, the UriMappings property has
been defined for the Root control. The UriMappings is a list of UriMapping
controls.
Each UriMapping control contains two properties:
- Prefix: the prefix string,
- Namespace: the namespace uri string,
To make it easier to navigate across the MForm controls, the methods Select
and SelectSingle are available for the Root control. These methods
expect an XPath-like expression to find instances of MForm items.
The branch control reflects a definition of XML element with attribute nodes or
with other children elements inside.
The Name property of the Branch control reflects the qualified name
of the XML element.
The mf:Branch control, as other OffspringsOwner controls,
has a Contents property. The Contents property may contain
any inner controls, particularly it may contain other MForm definition controls.
There are no restrictions on the contents of the Branch control.
The choice control reflects the group of xml nodes of which only one can be used.
The Name property of the Choice control has no particular meaning for
the reflected XML data representation. However this name may be used when selecting
MForm items using the xpath-like language so you should keep it meaningful.
The mf:Choice control, as other OffspringsOwner controls,
has a Contents property. The Contents property may contain
any inner controls, particularly it may contain other MForm definition controls.
Each of the mform definition controls inside the choice contents is one of the choice
options. All non-mform controls inside the Choice control will be rendered as they
are.
The leaf control reflects a xml attribute or a xml element which contains only a
text node.
The Name property of the Leaf control reflects the qualified name of
either the XML element or the name of the XML attribute. It works the same way as
in the Branch control.
To examine, whether the Leaf control reflects the element or the attribute, the
LeafType property exists.
By default, each leaf item control contains a label, and the text for this label
is taken from the DisplayName. The template for this label can be specified
within the Label property in the Leaf control.
Each leaf item control contains a value handler, which is used for manipulation
on the text of the leaf node. Each value handler is an adapter of a control it contains
inside. The default value handler is TextBoxValueHandler