/*

* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:       Element node functions

*

*/

#ifndef XMLENGINE_ELEMENT_H_INCLUDED

#define XMLENGINE_ELEMENT_H_INCLUDED

#include "XmlEngAttr.h"

#include "XmlEngNamespace.h"

template<class T> class RXmlEngNodeList;

/**

 * Instance of TXmlEngElement class represents an XML element in the DOM tree.

 *

 * <b>Namespace handling:</b>

 *

 * Namespace of XML element is an URI that in pair with <i>local part</i> of

 * element's name consistute <b>expanded-name</b> of element. It is said that "the element

 * is of <i>NNN</i> namespace".

 *

 * XML elements are shown as belonging to a specific namespace by using <i>prefixes</i>

 * that previously were bound to some namespace URIs. The scope of a prefix is the

 * element, where it was declared and all its child (sub-)elements.

 *      

 * Namespace declaration is created by using special <b>xmlns:<i>{prefix-name}</i></b>

 * attribute (which is not really considered as attribute in DOM):

 * @code 

 *    <a xmlns:pr="http://some.uri.com/"> ... </a>

 * OR

 *    <pr:a xmlns:pr="http://some.uri.com/"> ... </a>

 *    <a xmlns="http://some.uri.com/"> ... </a>

 * @endcode

 *

 * The latter two examples are equivalent and show the use of <i>default namespace</i>.

 *    

 * Implementation notes:

 *	- Element having no namespace is either presented with a NULL TXmlEngNamespace node 

 *    or a TXmlEngNamespace node that has NULL prefix and namespace URI set to "". 

 *    The former is used by default on all nodes, whereas the latter is for cases

 *    when some node contains undeclaration of the default namespace:

 * @code

 *	   <a xmlns=""> .. </a>

 * @endcode

 *

 * - The prefix of the default attribute is NULL, not "" (zero-length string)

 *	 "" corresponds to  

 *   @code

 *       <a xmlns:="http://some.uri.com/"> ... </a>

 *   @endcode

 *   (it does not contradict XML spec, but you are strongly advised against using this)

 *

 * - Prefix <b>"xml"</b> is reserved by XML Namespace spec for special purposes; it is implicitly bound

 *   to XML's namespace <i>"http://www.w3.org/XML/1998/namespace"</i> and no one is allowed

 *   to use this prefix except as with spec-defined elements and attributes or to rebind this 

 *   prefix to other namespaces

 *

 * - Namespace URI may be "" only for default namespace. In other words,

 *   "" namespace URI may not be bound to non-NULL prefix. 

 *          

 *   Declaration of "" namespace with NULL prefix results in:

 *   @code

 *       <a xmlns=""> ... </a>

 *   @endcode

 *   which <i>undeclares</i> any existing (in some parent element) default namespace

 *   for the scope of element 'a': element, its attributes and all child nodes of DOM tree.

 *   Note, that such "undeclaration" will be added only if neccessary. 

 *        

 * - Unneccessary namespace declaration are ignored. Attemps to add namespace binding 

 *   using same namespace URI and prefix if such binding already exists in the scope

 *   will have no effect.

 *

 * - <b>IMPORTANT!</b> Attributes DO NOT HAVE default namespaces. If an attribute has no

 *   prefix, its namespace is <b>undeclared</b> even if there is some default namespaces for

 *   the scope of the element, which contains the attribute.

 *

 * So, it is wrong to write something like this:

 * @code

 *     <a xmlns="ns_uri"  attr="value"> ... </a>

 * @endcode

 * and assume that the <b>attr</b> belongs to namespace pointed to with <i>ns_uri</i>.

 *    

 * <b>HINTS:</b>

 * - Use namespace declaration nodes as much as possible (but watch out prefix collisions).

 * - Add most referred to namespace declarations (AddNamespaceDeclarationL(uri,pref)) after

 *   any other namespace declarations in a element -- the will be found faster in

 *   namespace lookups.

 *

 * @lib XmlEngineDOM.lib

 * @since S60 v3.1

 */

class TXmlEngElement : public TXmlEngNode

{

  public:

    /**

     * Default constructor for automatic variables (not initialized)

	 *

     * @since S60 v3.1

	 */

    inline TXmlEngElement();

    /**

     * Constructor

     *

     * @since S60 v3.1

	 * @param aInternal element pointer

	 */

    inline TXmlEngElement(void* aInternal);

    /** 

    *    @name XmlEngine's non-DOM extensions

    */

    /** @{ */

    /**

     *   Retrieves list of attribute nodes of the element

     *   

     *   @param aList - a node list object to initialize

     *

     *   Passed by reference list of nodes is initialized and after call to

     *   Attributes(..) is ready for use with HasNext() and Next() methods:

     *

     *   @code

     *       ...

     *       TXmlEngElement root = doc.DocumentElement();

     *       RXmlEngNodeList<TXmlEngAttr>    attlist;

     *       root.GetAttributes(attlist);

     *       while (attlist.HasNext())

     *           processAttribute(attlist.Next());

     *       ...

	 *       attlist.Close();

     *   @endcode

	 *

     * @since S60 v3.1

	 */

    IMPORT_C void GetAttributes(RXmlEngNodeList<TXmlEngAttr>& aList) const;

    /**

     * Retrieves list of child elements of the element

     *

     * @since S60 v3.1

	 * @param aList - a node list object to initialize

     *

     * Passed by reference list of nodes is initialized and after the call

     * it is ready for use with HasNext() and Next() methods:

     *   

     * @note Returned list is a "filtered view" of the underlying

     *       list of all element's children (with text nodes, comments

     *       processing instructions, etc.)

	 */ 

    IMPORT_C void GetChildElements(RXmlEngNodeList<TXmlEngElement>& aList) const;

    /**

     * Creates new attribute node out of any namespace (i.e. it has no prefix),

     * sets attribute's value and links it as the last attribute of the current element

     *

     * @since S60 v3.1

	 * @param  aName   A local name of attribute

     * @param  aValue  Value to set for new attribute or NULL (sets value to "")

     * @return         A handler to the newly created attribute node;

     *

     * For adding attribute as the first one, use TXmlEngNode::SetAsFirstSibling() on the attribute:

     * @code

     *     TXmlEngElement el = ... ; // get some element

     *     el.AddNewAttributeL("version","0.1").SetAsFirstSibling();

     * @endcode

     *   

     * @see   SetAsLastSibling(), MoveBeforeSibling(TXmlEngNode) and MoveAfterSibling(TXmlEngNode)

     *

     * @note   - No checks are made that attribute with such name exists

     *           Use this method only on newly created elements!

     *           Otherwise, use TXmlEngElement::SetAttributeL(..)

     *         - Attributes do not inherit default namespace of its element

     *           (http://w3.org/TR/REC-xml-names/#defaulting)

     *         - attribute's value is the second argument in all AddNewAttributeL(..) methods

     *         - Use of NULL as value is more preferrable then "" 

	 */

    IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName, const TDesC8& aValue);

    /**

     * Creates new attribute node and add it to the element

     *

     * Provided handle to namespace declaration is used to set up

     * attribute's namespace.

     *

     * @since S60 v3.1

	 * @param  aName   A local name of attribute

     * @param  aValue  Value to set for new attribute or NULL (sets value to "")

     * @param  aNsDef  Namespace to add to the attribute

     * @return         A handler to the newly created attribute node;

     *

     * @note If aNsDef is not defined in some of attributes ascendants

     *      (including this element), then

     *      ReconcileNamespacesL() method must be called on

     *      this element later.

	 */

    IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName,

                                    const TDesC8& aValue, 

                                    const TXmlEngNamespace aNsDef);

    /**

     * Creates new attribute on the element. Namespace declaration for the attribute namespace is

     * created too.

     *

     * @since S60 v3.1

	 * @param  aName   A local name of attribute

     * @param  aValue  Value to set for new attribute or NULL (sets value to "")

     * @param  aNsUri  Namespace uri

     * @param  aPrefix  Namespace prefix

     * @return         A handler to the newly created attribute node;

     *

     * @note

     *    - Namespace declarations are reused if possible (no redundant ones are created)

     */

    IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName, 

                                    const TDesC8& aValue,

                                    const TDesC8& aNsUri, 

                                    const TDesC8& aPrefix);

    /**

     * Creates new attribute node using namespace of its parent element (this element),

     * sets attribute's value and links it as the last attribute of the element

     *

     * @since S60 v3.1

	 * @param aName Local name of attribute 

     * @param aValue Value to set for new attribute or NULL (sets value to "")

     * @return A handler to the newly created attribute node;

     *    

     * For more hints how to use it refer to AddNewAttributeL(const TDesC8&,const TDesC8&)

     *        

     * @note    

     *     - No checks are made that attribute with such name exists

     *     - if namespace of the parent element is default (i.e. bound prefix is NULL),

     *       then temporary prefix will be used and bound to the same namespace URI as elements

     *       (It is due to the fact that default namespaces do not spread on unprefixed attributes,

     *       see http://w3.org/TR/REC-xml-names/#defaulting)

     */

    inline   TXmlEngAttr AddNewAttributeSameNsL(const TDesC8& aName, const TDesC8& aValue);

    /**

     * Creates new attributes using namespace, which is bound to the specified prefix

     *

     * @since S60 v3.1

	 * @param  aLocalName   A local name of attribute

     * @param  aValue  Value to set for new attribute or NULL (sets value to "")

     * @param  aPrefix  Namespace prefix for new attribute

     * @return A handler to the newly created attribute node;

     *

     * Use this mothod only for construction of new parts of DOM tree, where

     * you know for sure that prefix is bound in the given scope.

     * @code

     *     TXmlEngElement el = parent.AddNewAttributeUsePrefixL("property","ObjName","rdf");

     *     el.AddNewAttributeUsePrefixL("type", "xs:integer", "rdf");

     * @endcode

     *

     * Otherwise, you should check that prefix is bound like this example shows:

     * @code

     *     TXmlEngNamespace boundNS = TXmlEngNamespace::LookupByPrefix(thisElement, prefix);

     *     if (boundNS.NotNull()){

     *         thisElement.AddNewAttributeUsePrefixL("name", value, prefix);

     *     }

     * @endcode

     *

     * @note

     *     Use AddNewAttributeNsL(name,value,nsDefNode) as much as you can, because

     *     it is most efficient way to create namespaced DOM elements (no additional

     *     lookups for namespace declarations are required).

     *  

     * @code

     *     // If namespace with given URI is not in the scope, then it will be declared

     *     // and bound to "data" prefix.

     *     TXmlEngNamespace nsDef = elem.FindOrCreateNsDefL("http://../Data", "data");

     *     elem.AddNewAttributeL("location", "...", nsDef);

     *     elem.AddNewElementL("child", nsDef).AddNewAttributeL("attr","...value...");

     *     // the result is

     *         ...

     *      <elem xmlns:data="http://../Data" data:location="...">

     *         <data:child attr="...value..."/>

     *      </elem>

     *         ...

     *     //

     * @endcode    

     */

    IMPORT_C TXmlEngAttr AddNewAttributeUsePrefixL(const TDesC8& aLocalName, 

                                             const TDesC8& aValue, 

                                             const TDesC8& aPrefix);

    /**

     * Creates new attributes using namespace in the scope, which has specified URI

     *   

     * Almost the same as AddNewAttributeUsePrefixL(...) but does lookup by namespace URI

     *

     * @since S60 v3.1

	 * @param  aLocalName   A local name of attribute

     * @param  aValue  Value to set for new attribute or NULL (sets value to "")

     * @param  aNsUri  Namespace uri for new attribute

     * @return - NULL attribute if namespace declaration is not found OR newly added to the end of

     *           attribute list attribute of this element.

     *

     * @see AddNewAttributeUsePrefixL(const TDesC8&,const TDesC8&,const TDesC8&)

     */

    IMPORT_C TXmlEngAttr AddNewAttributeWithNsL(const TDesC8& aLocalName, 

                                          const TDesC8& aValue, 

                                          const TDesC8& aNsUri);

    /**

     * Add attribute to element that will be used as Xml:Id.

     *

     * No check if such attribute exists are made.

     * 

     * @since S60 v3.2

	 * @param aLocalName Name of attribute that should be add.

	 * @param aValue Value of the attribute

	 * @param aNs Namespace of the attribute

	 * @return Attribute if created. Null attribute if Id exist

     *

     * @note Call RXmlEngDocument.RegisterXmlIdL(aName,aNsUri) first

     *       to register existed id's in the document.

     */

    IMPORT_C TXmlEngAttr AddXmlIdL(const TDesC8& aLocalName,

                                       const TDesC8& aValue,

                                       TXmlEngNamespace aNs = TXmlEngNamespace());

    /**

     * Adds child element with no namespace

     *

     * @since S60 v3.1

	 * @param aName name of the element

     * @return A handler to the newly created element node;

     *

     * Results in adding element with aName and no prefix.

     *

     * This method is the best for creation of non-namespace based documents

     * or document fragments, where no default namespace declared.

     *

     * It may be used also as a method for adding element from default namespace,

     * BUT namespace will be assigned ONLY after serialization of the current

     * document and parsing it back into a DOM tree!! If you need that default namespace

     * was inherited by new element immediately use:

     * @code

     *    ...

     *    TXmlEngNamespace defns = element.DefaultNamespace();

     *    TXmlEngElement newEl = element.AddNewElementL("Name",defns);

     *    ...

     * @endcode

     *

     * If truly undefined namespace for the element is required, then <b>DO NOT USE</b>

     * this method if there is a default namespace in the scope!

     */

    IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aName);

    /**

     * Creates new child element with provided name and namespace declaration

     *

     * @since S60 v3.1

	 * @param aLocalName Name of the element

     * @param aNsDecl Handle of the namespace declaration, that must be retrieved from

     *            one of the ascendant nodes of the new elements (and its prefix

     *            should not be remapped to another namespace URI for the scope

     *            of the new element)

     * @return    Created element node (and added as the last child of its parent)

     */

    IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName, TXmlEngNamespace aNsDecl);

    /**

     * Creates new child element with provided name, prefix and namespace URI

     *

     * New namespace declaration will be attached to the parent (this) element and used

     * as namespace for newly created child element. If such binding already exists

     * (same prefix is bound to same URI), it will be reused. If the prefix is already

     * bound to some another namespace URI, it will be rebound by the new namespace

     * declaration node.

     *

     * @since S60 v3.1

	 * @param aLocalName Name of the element

     * @param aNsUri     URI of element's namespace

     * @param aPrefix    Prefix of the element

     * @return Created element node (and added as the last child of its parent)

     */

    IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName, 

                                     const TDesC8& aNsUri, 

                                     const TDesC8& aPrefix);

    /**

     * Adds child element with same namespace (and prefix if present) as parent element has

     *

     * @since S60 v3.1

	 * @param aLocalName element's name

     * @return New element that was added to the end of children list of its parent (this element)

     */

    IMPORT_C TXmlEngElement AddNewElementSameNsL(const TDesC8& aLocalName);

    /**

     * Performs lookup for the namespace declaration for specified prefix and

     * adds new child element with found namespace.

     *

     * The assumption is that prefix is bound, otherwise run-time error

     * (Symbian's Leave or exception) occurs

     *

     * @note   Use this method only if there is a binding for the given prefix.

     *

     * @since S60 v3.1

	 * @param aLocalName element's name

     * @param aPrefix    prefix to use

     * @return new TXmlEngElement that was added to the end of children list of its parent (this element)

     */

    IMPORT_C TXmlEngElement AddNewElementUsePrefixL(const TDesC8& aLocalName, const TDesC8& aPrefix);

    /**

     * Performs lookup for the namespace declaration for specified namespace URI and

     * adds new child element with found namespace.

     *

     * The assumption is that namespace with given URI was declared,

     * otherwise run-time error (Symbian' Leave or exception) occurs

     * 

     * @note Use this method only if namespace declaration for the provided URI exists.

     *

     * @since S60 v3.1

	 * @param aLocalName    element's name

     * @param aNsUri        namespace of element

     * @return new TXmlEngElement that was added to the end of children list of its parent (this element)

     */

    IMPORT_C TXmlEngElement AddNewElementWithNsL(const TDesC8& aLocalName, const TDesC8& aNsUri);

    /**

     * Creates new child element; if there is no a prefix binding for new element's namespace,

     * a namespace decaration is created with generated prefix at specified element.

     *

     * @since S60 v3.1

	 * @param aLocalName    Name of the element to create

     * @param aNsUri        Namespace URI of the new element

     * @param aNsDeclTarget An element where namespace declaraton should be placed

     *                     if there is a needed to create new namespace declaration;

     *                     NULL is used to specify the created element itself

     *

     * As aNsDeclTarget any ascendant of the new node may be provided:

     * @code

     *     el.AddNewElementAutoPrefixL(tagName,uri,NULL); // declare on the new element

     *     el.AddNewElementAutoPrefixL(tagName,uri,el);   // declare on the parent element

     *     el.AddNewElementAutoPrefixL(tagName,uri,doc.DocumentElement()); // declare on the root element

     *    ...

     * @endcode

     *

     * @note

     *  The farther namespace declaration up in the document tree,

     *  the longer time namespace declaration lookups take.

     */

    IMPORT_C TXmlEngElement AddNewElementAutoPrefixL(const TDesC8& aLocalName, 

                                               const TDesC8& aNsUri, 

                                               TXmlEngElement aNsDeclTarget);

    /**

     * Get element content.

     * This method may be used in most cases, when element has only simple text content

     * (without entity references embedded).

     * If element's contents is mixed (other types of nodes present), only contents of

     * first child node is returned if it is a TXmlEngTextNode node. For getting mixed contents of the

     * element of contents with entity references, WholeTextValueCopyL() should be used.

     *

     * @since S60 v3.1

	 * @return Basic contents of the element

     * 

     * @see TXmlEngNode::WholeTextContentsCopyL()

     */

    IMPORT_C TPtrC8 Text() const;

    /**

     * Adds text as a child of the element.

     *

     * @since S60 v3.1

	 * @param aString text to be added as element's content.

     * 

     * @note There may be several TXmlEngTextNode and TXmlEngEntityReference nodes added actually,

     *   depending on the aString value