element method

void element(String name, { String? namespace, Map<String, String?> namespaces = const {}, Map<String, String> attributes = const {}, bool isSelfClosing = true, Object? nest, })

Adds a XmlElement node with the provided tag name.

If a namespace URI is provided, the prefix is looked up, verified and combined with the given tag name.

If a map of namespaces is provided the uri-prefix pairs are added to the element declaration, see also XmlBuilder.namespace.

If a map of attributes is provided the name-value pairs are added to the element declaration, see also XmlBuilder.attribute.

Finally, nest is used to further customize the element and to add its children. Typically this is a Function that defines elements using the same builder object. For convenience nest can also be a valid XmlNode, a string or another common object that will be converted to a string and added as a text node.

For example, to generate an XML element with the tag message and the contained text Hello World one would write:

builder.element('message', nest: 'Hello World');

To add multiple child elements one would use:

builder.element('message', nest: () {
  builder..text('Hello World')
         ..element('break');
});

Implementation

void element(
  String name, {
  String? namespace,
  Map<String, String?> namespaces = const {},
  Map<String, String> attributes = const {},
  bool isSelfClosing = true,
  Object? nest,
}) {
  final element = NodeBuilder();
  _stack.add(element);
  try {
    namespaces.forEach(this.namespace);
    attributes.forEach(attribute);
    if (nest != null) {
      _insert(nest);
    }
    element.name = _buildName(name, namespace);
    element.isSelfClosing = isSelfClosing;
    if (optimizeNamespaces) {
      // Remove unused namespaces: The reason we first add them and then remove
      // them again is to keep the order in which they have been added.
      element.namespaces.forEach((uri, meta) {
        if (!meta.used) {
          final qualified = meta.name.qualified;
          final attribute = element.attributes.firstWhere(
              (attribute) => attribute.name.qualified == qualified);
          element.attributes.remove(attribute);
        }
      });
    }
  } finally {
    _stack.removeLast();
  }
  _stack.last.children.add(element.buildElement());
}