nsXFormsRepeatElement Class Reference

Inheritance diagram for nsXFormsRepeatElement:

Collaboration diagram for nsXFormsRepeatElement:

Detailed Description

See also:: http://www.w3.org/TR/xforms/slice9.html#id2632123

There are two main functions of repeat: 1) "Expanding its children" and 2) Maintaining the repeat-index. These are described here:

Expanding its children

On Refresh(), nsXFormsRepeatElement, does the following for each node in the nodeset the <repeat> tag is bound to:

1) Creates a new <contextcontainer> (nsXFormsContextContainer)

2) Clones all its children (that is children of its mElement) and appends them as children to the nsXFormsContextContainer

3) Sets the context node and size for the nsXFormsContextContainer, so that children can retrieve this through nsIXFormsContextControl.

4) Inserts the nsXFormsContextContainer into its visual content node.

For example, this instance data:

 <instance>
   <data>
     <n>val1</n>
     <n>val2</n>
   </data>
 </instance>

and this repeat:

 <repeat nodeset="n">
   Val: <output ref=".">
 </repeat>

will be expanded to:

 <repeat nodeset="n">
   (anonymous content)          (XBL)
     <contextcontainer>         (contextNode == "n[0]" and contextPosition == 1)
       Val: <output ref=".">   (that is: 'val1')
     </contextcontainer>
     <contextcontainer>         (contextNode == "n[1]" and contextPosition == 2)
       Val: <output ref=".">   (that is: 'val2')
     </contextcontainer>
   (/anonymous content)         (XBL)
 </repeat>

Besides being a practical way to implement <repeat>, it also means that it is possible to CSS-style the individual "rows" in a <repeat>.

Maintaining the repeat-index

The repeat-index points to the current child contextcontainer selected, which should be fairly easy, was it not for "nested repeats".

If the DOM document has the following:

 <repeat id="r_outer">
   <repeat id="r_inner">
 </repeat>

r_inner is cloned like all other elements:

 <repeat id="r_outer">
   (anonymous content)
     <contextcontainer>
       <repeat id="r_inner">
     </contextcontainer>
     <contextcontainer>
       <repeat id="r_inner">
     </contextcontainer>
   (/anonymous content)

   (DOM content -- not shown)
     <repeat id="r_inner">
   (/DOM content)
 </repeat>

So r_inner in fact exists three places; once in the DOM and twice in the anonymous content of r_outer. The problem is that repeat-index can only be set for one row for each repeat. The approach we use here is to check whether we clone any <repeat> elements in Refresh() using our own CloneNode() function. If a <repeat> is found, we mark the original (DOM) <repeat> inactive with regards to content (mIsParent), and basically just use it to store a pointer to the current cloned <repeat> (mCurrentRepeat). We also store a pointer to the (DOM) parent in the cloned repeat (mParent).

There are two ways the repeat-index can be changed, 1) by <setindex> (nsXFormsSetIndexElement) and 2) by a <contextcontainer> getting focus. We thus listen for focus-events in nsXFormsContextContainer::HandleDefault().

If a <repeat> changes the repeat-index, any nested repeats have their repeat-index reset to their starting index (ResetInnerRepeats()).

Notes / todo

Todo:: Support attribute based repeats, as in: (XXX) <html:table xforms:repeat-nodeset="...">

See also:: http://www.w3.org/TR/xforms/index-all.html#ui.repeat.via.attrs
http://bugzilla.mozilla.org/show_bug.cgi?id=280368

Todo:: What happens if you set attributes on the parent repeat? Should they propagate to the cloned repeats? (XXX)

Note:: Should we handle ? The spec. says that it's a "Optional hint to the XForms Processor as to how many elements from the collection to display."

See also:: https://bugzilla.mozilla.org/show_bug.cgi?id=302026


Public Member Functions
NS_DECL_ISUPPORTS_INHERITED NS_IMETHOD	OnCreated (nsIXTFElementWrapper *aWrapper)
NS_IMETHOD	OnDestroyed ()
NS_IMETHOD	BeginAddingChildren ()
NS_IMETHOD	DoneAddingChildren ()
NS_IMETHOD	Bind (PRBool *aContextChanged)
NS_IMETHOD	Refresh ()
NS_IMETHOD	TryFocus (PRBool *aOK)
NS_IMETHOD	IsEventTarget (PRBool *aOK)
NS_IMETHOD	GetUsesSingleNodeBinding (PRBool *aUsesSNB)
NS_DECL_NSIXFORMSREPEATELEMENT	nsXFormsRepeatElement ()
virtual const char *	Name ()
Protected Member Functions
nsresult	GetIntAttr (const nsAString &aName, PRInt32 *aVal, const PRUint16 aType)
	Retrieves an integer attribute and checks its type.
nsresult	SetChildIndex (PRUint32 aPosition, PRBool aState, PRBool aIsRefresh=PR_FALSE)
	Set the repeat-index state for a given (nsIXFormsRepeatItemElement) child.
nsresult	ResetInnerRepeats (nsIDOMNode *aNode, PRBool aIsRefresh)
	Resets inner repeat indexes to 1 for first level of nested repeats of \|aNode\|.
nsresult	CloneNode (nsIDOMNode aSrc, nsIDOMNode *aTarget)
	Deep clones aSrc to aTarget, with special handling of <repeat> elements to take care of nested repeats.
PRBool	IsBindingAttribute (const nsIAtom *aAttr) const
	Checks whether an attribute is a binding attribute for the control.
void	SanitizeIndex (PRUint32 *aIndex, PRBool aIsScroll=PR_FALSE)
	Make sure that an index value is inside the valid index range.
nsresult	UnrollRows (nsIDOMXPathResult *aNodeset)
	Unroll the template content into the visual rows by cloning template content and inserting into contextcontainers.
already_AddRefed< nsIDOMElement >	GetAnonymousContent ()
	Returns either the anonymous content of the repeat or null;.
nsresult	InsertTemplateContent (nsIDOMNode *aNode)
	Insert the template content for a repeat node into the given node.
virtual void	AfterSetAttribute (nsIAtom *aName)
	Causes Bind() and Refresh() to be called if aName is the atom of a single node binding attribute for this control.
nsRepeatState	UpdateRepeatState (nsIDOMNode *aParent)
	Override of nsXFormsStubElement's function.
Protected Attributes
PRUint32	mCurrentIndex
	The current repeat-index, 0 if no row is selected (can happen for nested repeats) or there are no rows at all.
PRUint32	mMaxIndex
	The maximum index value.
nsCOMPtr< nsIXFormsRepeatElement >	mParent
	The parent repeat (nested repeats).
PRUint32	mLevel
	The nested level of the repeat.
PRUint32	mCurrentRowCount
	The number of "repeat rows" the repeat currently have unrolled.
PRPackedBool	mAddingChildren
	True while children are being added.
PRPackedBool	mIsParent
	Are we a parent for nested repeats.
PRPackedBool	mIsAttributeBased
	Is the repeat attribute-based (ie.
nsCOMPtr< nsIDOMNode >	mAttrBasedRepeatNode
	If this repeat is attribute based that means it is contained by certain element that have repeat related attributes (see http://www.w3.org/TR/xforms/slice9.html#ui.repeat.via.attrs) then this property is a clone of that element exepting it doens't have any repeat related attributes.
nsCOMPtr< nsIXFormsRepeatElement >	mCurrentRepeat
	The currently selected repeat (nested repeats).
nsCOMArray< nsIXFormsControl >	mIndexUsers
	Array of controls using the repeat-index.

Constructor & Destructor Documentation

NS_DECL_NSIXFORMSREPEATELEMENT nsXFormsRepeatElement::nsXFormsRepeatElement ( ) [inline]

Member Function Documentation

nsresult nsXFormsRepeatElement::GetIntAttr	(	const nsAString &	aName,
		PRInt32 *	aVal,
		const PRUint16	aType
	)			`[protected]`

Parameters:

	aName	The attribute to retrieve
	aVal	The value
	aType	The attribute (Schema) type

Returns:: Normal error codes, and NS_ERROR_NOT_AVAILABLE if the attribute was empty/nonexistant

Todo:: This function will be part of the general schema support, so it will only live here until this is implemented there. (XXX)

Todo:: Is this the correct error to return? We need to distinguish between an empty attribute and other errors. (XXX)

Todo:: ToInteger is extremely large, "xxx23xxx" will be parsed with no errors as "23"... (XXX)

Todo:: Check maximum values? (XXX)

nsresult nsXFormsRepeatElement::SetChildIndex	(	PRUint32	aPosition,
		PRBool	aState,
		PRBool	aIsRefresh = `PR_FALSE`
	)			`[protected]`

Parameters:

	aPosition	The position of the child (1-based)
	aState	The index state
	aIsRefresh	Is this part of a refresh event

nsresult nsXFormsRepeatElement::ResetInnerRepeats	(	nsIDOMNode *	aNode,
		PRBool	aIsRefresh
	)			`[protected]`

Parameters:

	aNode	The node to search for repeats
	aIsRefresh	Is this part of a refresh event

nsresult nsXFormsRepeatElement::CloneNode	(	nsIDOMNode *	aSrc,
		nsIDOMNode **	aTarget
	)			`[protected]`

Parameters:

	aSrc	The source node
	aTarget	The target node

PRBool nsXFormsRepeatElement::IsBindingAttribute ( const nsIAtom * aAttr ) const [protected, virtual]

This should be overriden by controls that have "non-standard" binding attributes.

Parameters:

aAttr

The attribute to check.

Reimplemented from nsXFormsControlStub.

void nsXFormsRepeatElement::SanitizeIndex	(	PRUint32 *	aIndex,
		PRBool	aIsScroll = `PR_FALSE`
	)			`[protected]`

Parameters:

	aIndex	The index value to sanitize
	aIsScroll	Send scroll events if first or last index?

nsresult nsXFormsRepeatElement::UnrollRows ( nsIDOMXPathResult * aNodeset ) [protected]

already_AddRefed< nsIDOMElement > nsXFormsRepeatElement::GetAnonymousContent ( ) [protected]

nsresult nsXFormsRepeatElement::InsertTemplateContent ( nsIDOMNode * aNode ) [protected]

Parameters:

aNode

The node to insert content into.

void nsXFormsRepeatElement::AfterSetAttribute ( nsIAtom * aName ) [protected, virtual]

Called by AttributeSet and AttributeRemoved.

Reimplemented from nsXFormsControlStub.

nsRepeatState nsXFormsRepeatElement::UpdateRepeatState ( nsIDOMNode * aParent ) [protected, virtual]

Needed to properly handle the case where the repeat is generated as anonymous content to elements with repeat attrs on them.

Parameters:

aParent

The new parent of the XForms control

Reimplemented from nsXFormsStubElement.

NS_DECL_ISUPPORTS_INHERITED NS_IMETHOD nsXFormsRepeatElement::OnCreated ( nsIXTFElementWrapper * aWrapper )

Reimplemented from nsXFormsDelegateStub.

NS_IMETHODIMP nsXFormsRepeatElement::OnDestroyed ( )

Reimplemented from nsXFormsDelegateStub.

NS_IMETHODIMP nsXFormsRepeatElement::BeginAddingChildren ( )

NS_IMETHODIMP nsXFormsRepeatElement::DoneAddingChildren ( )

NS_IMETHODIMP nsXFormsRepeatElement::Bind ( PRBool * aContextChanged )

Reimplemented from nsXFormsControlStub.

NS_IMETHODIMP nsXFormsRepeatElement::Refresh ( void )

Todo:: The spec says: "This node-set must consist of contiguous child element nodes, with the same local name and namespace name of a common parent node. The behavior of element repeat with respect to non-homogeneous node-sets is undefined."