In-Portal Developers Guide

This is a wiki-based Developers Guide for In-Portal Open Source CMS. The purpose of this guide is to provide advanced users, web developers and programmers with documentation on how to expand, customize and improve the functionality and the code the In-Portal software. Please consider contributing to our documentation writing effort.

K4:Обработка XML документов

From In-Portal Developers Guide

Jump to: navigation, search
Current revision (01:18, 28 November 2010) (view source)
(back to Russian)
 
Line 1: Line 1:
{{toc | category = Вспомогательные классы | sortkey = 002.001}}
{{toc | category = Вспомогательные классы | sortkey = 002.001}}
<!-- Пишите ПОСЛЕ этой строки, пожалуйста. Ничего не стирать! -->
<!-- Пишите ПОСЛЕ этой строки, пожалуйста. Ничего не стирать! -->
-
<code>XML</code> is a convenient tree-structure format of organizing data. Each element can contain a value and/or other elements. Text inside an element can alternate with child elements, but it will still be considered a single value. Moreover, each element can have attributes. All of this is shown in the below example (let it be a file called "<code>sample.xml</code>"):
+
<code>XML</code> - удобный формат описания данных, который строится по древовидной структуре. Каждый элемент может содержать значение и/или другие элементы. Текст внутри элемента может чередоваться с дочерними элементами, но он всё равно будет расценен как единое значение. Кроме того, у каждого элемента могут быть заданы атрибуты. Всё выше описанное отражено в ниже приведённом примере (пусть это будет файл "<code>sample.xml</code>"):
<source lang="xml">
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<?xml version="1.0" encoding="utf-8"?>
Line 34: Line 34:
</source>
</source>
-
== The CDATA Block ==
+
== Блок CDATA ==
-
If the content of an element needs to contain symbols that could disrupt the correct parsing of an XML document, then the contents need to be inside a CDATA block. Some of these symbols include "<code>></code>", "<code><</code>" и "<code>&</code>". The syntax of a <code>CDATA</code> block looks like this:
+
Если требуется указать в качестве содержания одного из элементов символы, которые могут помешать корректной разборке XML документа, то нужно содержание элемента заключать в блок CDATA. К ряду символов таких символов относятся символы "<code>></code>", "<code><</code>" и "<code>&</code>". Синтаксис блока <code>CDATA</code> выглядит следующим образом:
<source lang="xml">
<source lang="xml">
Line 41: Line 41:
</source>
</source>
-
Data inside a CDATA block should not contain "<code>]]></code>" because it will considered the end of the block. If it's absolutely necessary to have "<code>]]></code>" then the following approach will work:
+
Данные внутри блока <code>CDATA</code> не должны содержать последовательность "<code>]]></code>", т.к. она будет воспринята как окончание данного блока. Если задание такой последовательности символов необходимо, следует воспользоваться следующим подходом:
<source lang="xml">
<source lang="xml">
Line 47: Line 47:
</source>
</source>
-
In the above example, the contents are separated into two parts, each of which is inside a <code>CDATA</code> block. It's especially convenient to use <code>CDATA</code> in the situation where <code>XML</code> needs to be written to show to a user, but won't be processed when parsing the XML document.
+
В выше приведённом примере данные разбиты на два фрагмента и каждый из них заключён в свой блок <code>CDATA</code>. Особенно удобно применение <code>CDATA</code> в случае, когда нужно написать <code>XML</code>, который будет показан пользователю, но не обработан при разборке XML документа.
-
== Getting an XML Document ==
+
== Получение XML документа ==
-
Before parsing an <code>XML</code> document, it has to be received.
+
Перед тем, как разбирать <code>XML</code> документ, содержащийся в файле, его нужно сначала прочитать.
-
=== Getting a Local File ===
+
=== Получение локального файла ===
-
To get a local file (i.e. located on the same computer as the site), the standard [http://us.php.net/manual/en/function.file-get-contents.php file_get_contents] function can be used. This function returns the contents of file, the path of which is passed as its first argument.
+
Для получения локального файла (т.е. находящегося на том-же компьютере, что и сам сайт) следует использовать стандартную функцию [http://php.prod.intechnic.lv/manual/en/function.file-get-contents.php file_get_contents]. Данная функция возвращает содержание файла, путь к которому передан в качестве первого её аргумента.
<source lang="php">
<source lang="php">
Line 59: Line 59:
</source>
</source>
-
=== Getting a Remote File ===
+
=== Получение удалённого файла ===
-
The [http://us.php.net/manual/en/function.file-get-contents.php file_get_contents] function also allows retrieving the contents of a remote file. However, for security reasons, the server may restrict this functionality. Therefore, it's strongly recommended to use the standard K4 <code>kCurlHelper</code> class to retrieve remote files.
+
Функция [http://php.prod.intechnic.lv/manual/en/function.file-get-contents.php file_get_contents] также позволяет получать содержимое файлов, находящихся на удалённых ресурсах. Однако, в целях безопасности, на сервере может быть запрещена эта возможность. Поэтому настоятельно рекомендуется получать удалённый файл при помощи стандартного класса K4 - <code>kCurlHelper</code>.
<source lang="php">
<source lang="php">
Line 69: Line 69:
</source>
</source>
-
The <code>Send</code> method has a second optional parameter, which indicates that the connection should be terminated right after getting the contents of the document. By default, it's set to "<code>true</code>", i.e. terminate connection.
+
У метода <code>Send</code> также есть второй необязательный параметр, который указывает на то, что нужно закрывать соединение сразу после получения содержания документа. По умолчанию он равен "<code>true</code>", т.е. закрывать соединение.
-
== Parsing an XML Document ==
+
== Разборка XML документа ==
-
Realized in the <code>kXMLHelper</code> class is a convenient mechanism for parsing an XML document. The first step is to create an object of the class.  
+
В классе <code>kXMLHelper</code> реализован удобный механизм разбора XML документа. Сначала следует создать экземпляр класса.
<source lang="php">
<source lang="php">
Line 79: Line 79:
</source>
</source>
-
Then, to start the parsing of the XML document retrieved earlier.
+
Далее, начать обработку полученного ранее XML документа.
<source lang="php">
<source lang="php">
Line 85: Line 85:
</source>
</source>
-
A tree structure of objects will be returned as a result, in which all objects are connected using links. The contents of each object of the <code>kXMLNode</code> class looks like this:
+
В результате будет возвращена древовидная структура объектов, в которой все объекты связаны при помощи ссылок. Содержимое каждого объекта класса <code>kXMLNode</code> выглядит так:
<source lang="php">
<source lang="php">
Line 110: Line 110:
</source>
</source>
-
{{TipBox|The below description of the contents of an object of the kXMLNode class will be based on the example at the beginning of the article.}}
+
{{TipBox|Всё ниже приведённое описание содержания объекта класса kXMLNode будет основано на примере, приведённом в начале статьи.}}
 +
Переменной <code>$root_node</code> будет присвоен родительский (root) объект, т.е. это объект xml-элемента "<code>our_document</code>". Атрибут "<code>Children</code>" (private) содержит массив всех дочерних элементов текущего элемента. В данном примере ими являются два элемента - "<code>some_tag</code>" и "<code>planet_earth</code>". У последнего - два дочерних элемента "<code>continent</code>". Важно понимать, что элементы массива - точно такие же объекты, как и текущий. У них, в свою очередь, могут быть свои дочерние элементы, и так далее.
-
The parent (root) object will be assigned to the <code>$root_node</code> variable, i.e. the xml-element object "<code>our_document</code>". The "<code>Children</code>" (private) attribute contains an array of all child elements of the current element. In this example, these are the two elements "<code>some_tag</code>" and "<code>planet_earth</code>". The last one has two "<code>continent</code>" child elements. It's import to understand that array elements are the same as other objects, they can themselves have child elements, etc.
+
У каждого элемента есть атрибут <code>Position</code>. Это - порядковый номер элемента среди соседних элементов (элементов того же уровня, например - "country" Canada и "country" USA). Атрибуты "<code>firstChild</code>" и "<code>lastChild</code>" содержат первый и последний (с точки зрения его <code>Position</code>) дочерний элемент соответственно.
-
Each element has a <code>Position</code> attribute. This is its order in the elements (same level elements, for example - "country" Canada and "country" USA). The "<code>firstChild</code>" and "<code>lastChild</code>" elements contain the first and last (from the point of view of their <code>Position</code>) child elements, respectively.  
+
Для последующей обработки полученной информации используется методы и атрибуты именно класса <code>kXMLNode</code>.
-
For further processing of received information the <code>kXMLNode</code> class methods and attributes are used.
+
== Практическое использование kXMLHelper ==
-
 
+
Ниже приведён код, который распечатает все страны описанного выше XML-документа.
-
== kXMLHelper in Practice ==
+
-
 
+
-
The below code prints all of the countries in the above XML-document.
+
<source lang="php">
<source lang="php">
Line 129: Line 127:
$continent_node =& $root_node->FindChild('continent');
$continent_node =& $root_node->FindChild('continent');
-
// Cycling through it and all the rest of the continent nodes
+
// Cycling through it and all the rest continent nodes
do {
do {
// Getting first country node
// Getting first country node
$country_node =& $continent_node->firstChild;
$country_node =& $continent_node->firstChild;
-
// Cycling through it and all the rest of the continent nodes
+
// Cycling through it and all the rest continent nodes
     do {
     do {
         echo $continent_node->Attributes['ID'] . ' - ' . trim($continent_node->Data) . ': ' . $country_node->Attributes['ID'] . ' - ' . trim($country_node->Data) . '<br/>';
         echo $continent_node->Attributes['ID'] . ' - ' . trim($continent_node->Data) . ': ' . $country_node->Attributes['ID'] . ' - ' . trim($country_node->Data) . '<br/>';
Line 141: Line 139:
</source>
</source>
-
The <code>$continent_node</code> variable stores the first found "<code>continent</code>" object, i.e. - "<code>North America</code>". The first loop goes through the continents. The <code>NextSibling</code> method is used to go to the element of the same level (the counterpart of this method is <code>PrevSibling</code>). The first country is chosen from the continent. The inner loop goes through all countries of a continent and returns them in the below format. Note, the text values of the elements are accessible through the "<code>Data</code>" attribute.  
+
В переменной <code>$continent_node</code> сохраняется первый найденный объект "<code>continent</code>", т.е. - "<code>North America</code>". В первом цикле перебираются континенты. Для перехода к элементу того же уровня используется метод <code>NextSibling</code> (есть противоположный ему метод <code>PrevSibling</code>). Из континента выбирается первая страна. Внутренний цикл перебирает все страны данного континента и делает вывод в приведённом ниже формате. Как можно заметить, текстовое значение элементов доступно через атрибут "<code>Data</code>".  
  1 - North America: 1 - Canada
  1 - North America: 1 - Canada
Line 149: Line 147:
  2 - Europe: 3 - Lithuania
  2 - Europe: 3 - Lithuania
-
== "kXMLNode" Class Methods ==
+
== Методы класса "kXMLNode" ==
-
Below are public methods of the <code>kXMLNode</code> class. All these methods are for reading data, but not for recording it.  
+
Ниже приведены public методы класса <code>kXMLNode</code>. Все методы рассчитаны на чтение данных, но не на их запись.
 +
 
{| class="prettytable"  
{| class="prettytable"  
-
! Method || Description
+
! метод || описание
|-
|-
| <code>&FindChild($name)</code>
| <code>&FindChild($name)</code>
-
| Returns the first element descendant with the given name. Works recursively through to the last level.  
+
| Возвращает первый встретившийся элемент-потомок с указанным именем. Работает рекурсивно, до самого последнего уровня.
|-
|-
| <code>FindChildValue($name, $attr=null)</code>
| <code>FindChildValue($name, $attr=null)</code>
-
| Returns either the value of the element descendant (if only its name is set) or one of its attributes (if explicitly set).
+
| Возвращает либо значение элемента-потомка (если задано только его имя), либо один из атрибутов (если явно указан).
|-
|-
| <code>&GetChildByPosition($position)</code>
| <code>&GetChildByPosition($position)</code>
-
| Returns the child element that's located at the given position.
+
| Возвращает дочерний элемент, который находится по указанной позиции.
|-
|-
| <code>GetXML()</code>
| <code>GetXML()</code>
-
| Generates and returns an XML-document, built from the current element. Possible not only in the previous structural change.
+
| Генерирует и возвращает XML-документ, построенный от текущего элемента. Актуально при предыдущем изменении структуры и не только.
|}
|}
 +
 +
[[ru:{{FULLPAGENAME}}]]
 +
[[en:K4:KXMLHelper]]

Current revision

Вспомогательные классы Вспомогательные классы
Статьи в этой категории
  • Обработка XML документов

XML - удобный формат описания данных, который строится по древовидной структуре. Каждый элемент может содержать значение и/или другие элементы. Текст внутри элемента может чередоваться с дочерними элементами, но он всё равно будет расценен как единое значение. Кроме того, у каждого элемента могут быть заданы атрибуты. Всё выше описанное отражено в ниже приведённом примере (пусть это будет файл "sample.xml"):

<?xml version="1.0" encoding="utf-8"?>
<our_document>
	<some_tag>
		Some tag's content.
	</some_tag>
	<planet_earth>
	    <continent id="1">
		North America
            	<country id="1">
			Canada
		</country>
          	<country id="2">
			USA
		</country>
	    </continent>
	    <continent id="2">
	    	Europe
            	<country id="1">
			Estonia
		</country>
            	<country id="2">
			Latvia
		</country>
            	<country id="3">
			Lithuania
		</country>
	    </continent>
	</planet_earth>
</our_document>

Contents

Блок CDATA

Если требуется указать в качестве содержания одного из элементов символы, которые могут помешать корректной разборке XML документа, то нужно содержание элемента заключать в блок CDATA. К ряду символов таких символов относятся символы ">", "<" и "&". Синтаксис блока CDATA выглядит следующим образом:

<![CDATA[Some symbolic data, that > breaks & xml]]>

Данные внутри блока CDATA не должны содержать последовательность "]]>", т.к. она будет воспринята как окончание данного блока. Если задание такой последовательности символов необходимо, следует воспользоваться следующим подходом:

<![CDATA[]]]]><![CDATA[>]]>

В выше приведённом примере данные разбиты на два фрагмента и каждый из них заключён в свой блок CDATA. Особенно удобно применение CDATA в случае, когда нужно написать XML, который будет показан пользователю, но не обработан при разборке XML документа.

Получение XML документа

Перед тем, как разбирать XML документ, содержащийся в файле, его нужно сначала прочитать.

Получение локального файла

Для получения локального файла (т.е. находящегося на том-же компьютере, что и сам сайт) следует использовать стандартную функцию file_get_contents. Данная функция возвращает содержание файла, путь к которому передан в качестве первого её аргумента.

$file_contents = file_get_contents(WRITEABLE . '/user_files/sample.xml');

Получение удалённого файла

Функция file_get_contents также позволяет получать содержимое файлов, находящихся на удалённых ресурсах. Однако, в целях безопасности, на сервере может быть запрещена эта возможность. Поэтому настоятельно рекомендуется получать удалённый файл при помощи стандартного класса K4 - kCurlHelper.

$curl_helper =& $this->Application->recallObject('CurlHelper');
/* @var $curl_helper kCurlHelper */
 
$xml_data = $curl_helper->Send('http://sample-host.com/sample.xml');

У метода Send также есть второй необязательный параметр, который указывает на то, что нужно закрывать соединение сразу после получения содержания документа. По умолчанию он равен "true", т.е. закрывать соединение.

Разборка XML документа

В классе kXMLHelper реализован удобный механизм разбора XML документа. Сначала следует создать экземпляр класса.

$xml_helper =& $this->Application->recallObject('kXMLHelper');
/* @var $xml_helper kXMLHelper */

Далее, начать обработку полученного ранее XML документа.

$root_node =& $xml_helper->Parse($file_contents);

В результате будет возвращена древовидная структура объектов, в которой все объекты связаны при помощи ссылок. Содержимое каждого объекта класса kXMLNode выглядит так:

kxmlnode Object (
	[Name] => xml_element_name
	[Attributes] => Array
	(
		[1st_attribute_name] => 1st_attribute_value
		[2nd_attribute_name] => 2nd_attribute_value
		...
	)
	[Children] => Array
	(
		[0] =>	kxmlnode Object
		[1] =>	kxmlnode Object
		...
	)
	[Data] => text_value_that_this_XML_element_encapsulates
	[firstChild] => kxmlnode Object
	[lastChild] => kxmlnode Object
	[Parent] =>  kxmlnode Object
	[Position] => 1
)
Image:Tipbox Icon.gif Всё ниже приведённое описание содержания объекта класса kXMLNode будет основано на примере, приведённом в начале статьи.

Переменной $root_node будет присвоен родительский (root) объект, т.е. это объект xml-элемента "our_document". Атрибут "Children" (private) содержит массив всех дочерних элементов текущего элемента. В данном примере ими являются два элемента - "some_tag" и "planet_earth". У последнего - два дочерних элемента "continent". Важно понимать, что элементы массива - точно такие же объекты, как и текущий. У них, в свою очередь, могут быть свои дочерние элементы, и так далее.

У каждого элемента есть атрибут Position. Это - порядковый номер элемента среди соседних элементов (элементов того же уровня, например - "country" Canada и "country" USA). Атрибуты "firstChild" и "lastChild" содержат первый и последний (с точки зрения его Position) дочерний элемент соответственно.

Для последующей обработки полученной информации используется методы и атрибуты именно класса kXMLNode.

Практическое использование kXMLHelper

Ниже приведён код, который распечатает все страны описанного выше XML-документа.

$root_node =& $xml_helper->Parse($xml_data);
/* @var $root_node kXMLNode */
 
// Getting first continent node
$continent_node =& $root_node->FindChild('continent');
 
// Cycling through it and all the rest continent nodes
do {
	// Getting first country node
	$country_node =& $continent_node->firstChild;
 
	// Cycling through it and all the rest continent nodes
    	do {
        	echo $continent_node->Attributes['ID'] . ' - ' . trim($continent_node->Data) . ': ' . $country_node->Attributes['ID'] . ' - ' . trim($country_node->Data) . '<br/>';
    	} while ($country_node =& $country_node->NextSibling());
} while ($continent_node =& $continent_node->NextSibling());

В переменной $continent_node сохраняется первый найденный объект "continent", т.е. - "North America". В первом цикле перебираются континенты. Для перехода к элементу того же уровня используется метод NextSibling (есть противоположный ему метод PrevSibling). Из континента выбирается первая страна. Внутренний цикл перебирает все страны данного континента и делает вывод в приведённом ниже формате. Как можно заметить, текстовое значение элементов доступно через атрибут "Data".

1 - North America: 1 - Canada
1 - North America: 2 - USA
2 - Europe: 1 - Estonia
2 - Europe: 2 - Latvia
2 - Europe: 3 - Lithuania

Методы класса "kXMLNode"

Ниже приведены public методы класса kXMLNode. Все методы рассчитаны на чтение данных, но не на их запись.

метод описание
&FindChild($name) Возвращает первый встретившийся элемент-потомок с указанным именем. Работает рекурсивно, до самого последнего уровня.
FindChildValue($name, $attr=null) Возвращает либо значение элемента-потомка (если задано только его имя), либо один из атрибутов (если явно указан).
&GetChildByPosition($position) Возвращает дочерний элемент, который находится по указанной позиции.
GetXML() Генерирует и возвращает XML-документ, построенный от текущего элемента. Актуально при предыдущем изменении структуры и не только.