element method Null safety

void element(
  1. String name,
  2. {String? namespace,
  3. Map<String, String> namespaces = const {},
  4. Map<String, String> attributes = const {},
  5. bool isSelfClosing = true,
  6. 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 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.addLast(element);
  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 name = meta.name;
        final attribute = element.attributes
            .firstWhere((attribute) => attribute.name == name);
        element.attributes.remove(attribute);
      }
    });
  }
  _stack.removeLast();
  _stack.last.children.add(element.buildElement());
}