XML.AddNode

AddNode (Работа со значением ветки)
Объект: Объект XML Статус разработки: Реализована Тип: Функция Обращение к БД: Нет Исключения: Невозможно превратить в строка или число, неверный формат аргументов, ветка-сирота. Визуальность: Нет

• Начальная страница
• Общее описание
• Объекты
• Объект XML

Функция позволяет добавить новую ветку как последнюю подчиненную ветку текущей. Для ветки задается полное имя, значение, атрибуты, если они необходимы. Также по умолчанию производится текстовое форматирование. Значение ветки может содержать подчиненные ветки. Функция может быть использована как с объектом XML, так и с объектом ветки XML (в т.ч. непозиционированной). Функцию нельзя использовать с объектом осиротевшей ветки (см. Объект XML).

Синтаксис

XML.AddNode(<Имя ветки с пространством имен (STRING)>,<Значение ветки (STRING)>,<Атрибуты ветки (STRING)>="",<Использовать форматирование (INT)>=1):<Объект добавленной ветки (XMLBRANCH)>

Аргументы

• <Имя ветки с пространством имен (STRING)> - Аргумент задает полное имя добавляемой ветки. Имена веток имеют определенные ограничения по стандарту XML, см. описание атрибута FullName.
• <Значение ветки (STRING)> - (необязательный аргумент) Значение ветки -- произвольный текст, который может содержать подчиненные ветки, если это необходимо (в том числе, особенные ветки комментария). Важно: функция не выполняет автоматического перекодирования предоставленного текста значения в формат XML (т.е., не кодирует знаки &, ", <, > и '). Для кодирования значения веток необходимо вызвать функцию EncodeXMLString. Это сделано для того, чтобы можно было использовать значения, содержащие подчиненные ветки. Если аргумент не указан, ветка будет добавлена в виде самозакрывающегося тега (т.е., не будет иметь значения).
• <Атрибуты ветки (STRING)> - (необязательный аргумент) Аргумент задает атрибуты ветки, если они необходимы. Атрибуты имеют следующий формат: <Атрибут1>="<Значение 1>"[ <Атрибут2>="<Значение 2>" ...]. Имена атрибутов имеют такие же ограничения, как и имена веток (см. описание атрибута FullName). Имена атрибутов также могут содержать пространства имен. По стандарту одна ветка не может иметь два атрибута с одним и тем же именем, однако, проверка таких случаев в этой функции не производится, соответствие стандарту остается на совести разработчика. Значения атрибутов должны быть заранее перекодированы в формат XML (см. описание второго аргумента).
• <Использовать форматирование (INT)> - (необязательный аргумент) Аргумент включает режим сохранения текстового форматирования для удобства чтения текста XML документа человеком. В этом режиме каждая новая ветка следует с новой строки и каждый открывающийся тег ветки отделен от начала строки определенным количеством пробелов. Для разделителя используются два пробела на один уровень глубины ветки в структуре документа XML. Если режим не активен, никаких дополнительных знаков совместно с новой веткой добавлено не будет.

Возвращаемое значение

Возвращает объект ветки XML, позиционированный на добавленной ветке.

Примеры

aObject:=XML.Create();

//Добавление особой ветки
aObject.Text:="<?xml version=""1.0"" encoding=""UTF-8"" ?>";

//Позиционирование объекта ветки
aNode:=aObject.Root;

//Добавление обычной ветки
aNode:=aNode.AddNode("data",,"var1='value1'",0);

//Будет выведено: "<?xml version="1.0" encoding="UTF-8" ?><data var1='value1'/>"
Message(aObject.Text);

//Изменение значения текущей ветки (data)
//Значение может содержать подчиненные ветки
aNode.Value:="<subdata>text goes here...</subdata>";

//Изменение позиционирования
aNode.Path:="<data><subdata>";

//Будет выведено "text goes here..."
Message(aNode.Value);

//Будет выведено "<?xml version="1.0" encoding="UTF-8" ?><data var1='value1'><subdata>text goes here...</subdata></data>"
Message(aObject.Text);