LookupByXPath Method (relativeTo, query, valueBuilder)

[This is preliminary documentation and is subject to change.]

Find an SifElement given an XPath-like query string.

Declaration Syntax

Visual Basic

Visual C++

public Element LookupByXPath(
	SifDataObject relativeTo,
	string query,
	IValueBuilder valueBuilder
)

Public Function LookupByXPath ( _
	relativeTo As SifDataObject, _
	query As String, _
	valueBuilder As IValueBuilder _
) As Element

public:
Element^ LookupByXPath (
	SifDataObject^ relativeTo, 
	String^ query, 
	IValueBuilder^ valueBuilder
)

Parameters

relativeTo (SifDataObject): A SifDataObject to which the query is relative to.
query (String): An XPath-like query string as described above.
valueBuilder (IValueBuilder)

Return Value

The Element satisfying the query, or null if no match was found (unless the create parameter is true). If the query resolves to an attribute, a SimpleField object is returned. If it resolves to an element, a SifElement object is returned. In both cases the caller can obtain the text value of the attribute or element by calling its TextValue property.

Remarks

Query strings can only take one of these forms:

@Attr
Element
Element/@Attr
Element/Element/.../@Attr
Element[@Attr='value1']
Element[@Attr1='value1',@Attr2='value2',...]/Element/...

When the create parameter is true, the method will ensure that the elements and attributes specified in the query string are created in the SifDataObject. All values are evaluated by the ValueBuilder implementation passed to this method. In addition, the query string may end with a value expression in the form "Element[@Attribute='val']=expression", where expression is evaluated by the ValueBuilder. Refer to the DefaultValueBuilder class for a description of how value expressions are evaluated by in XPath query strings by default.

Note that when create is true, this method will attempt to create a new element when a set of attributes is specified and an element does not already exist with those same attribute settings. This is not always desirable, however. For example, if you call this method in succession with the following XPath query strings, the result will be a single OtherId[@Type='ZZ'] element with a value of "$(School)". This is because each call will match the OtherId[@Type='ZZ'] element created by the first call, and will replace its value instead of creating an new instance of the OtherId element:

CopyC#

OtherId[@Type='ZZ']=GRADE:$(Grade)
OtherId[@Type='ZZ']=HOMEROOM:$(HomeRoom)
OtherId[@Type='ZZ']=SCHOOL:$(School)

Produces:

<OtherId Type='ZZ'>SCHOOL:$(School)</OtherId>

To instruct the function to always create a new instance of an element even when a matching element is found, append the attribute list with a plus sign. The plus sign must come immediately before the closing right backet regardless of how many attributes are specified in the attribute list:

CopyC#

OtherId[@Type='ZZ'+]=GRADE:$(Grade)
OtherId[@Type='ZZ'+]=HOMEROOM:$(HomeRoom)
OtherId[@Type='ZZ'+]=SCHOOL:$(School)

Produces:

CopyC#

<OtherId Type='ZZ'>GRADE:$(Grade)</OtherId>
<OtherId Type='ZZ'>HOMEROOM:$(HomeRoom)</OtherId>
<OtherId Type='ZZ'>SCHOOL:$(School)</OtherId>

Assembly: Edustructures.SifWorks.Adk (Module: Edustructures.SifWorks.Adk) Version: 2.0.0.10