From 75bff3178a5164ed205bfeb0b83d92cb70e27a25 Mon Sep 17 00:00:00 2001
From: Mehdi Achour <didou@php.net>
Date: Mon, 20 Dec 2004 03:10:23 +0000
Subject: [PATCH] document DOMAttr->isId() and DOMDocument->getElementById()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@175105 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/dom/functions/dom-domattr-isid.xml  | 31 ++++++++++++++-
 .../dom-domdocument-getelementbyid.xml        | 38 +++++++++++++++++--
 2 files changed, 64 insertions(+), 5 deletions(-)

diff --git a/reference/dom/functions/dom-domattr-isid.xml b/reference/dom/functions/dom-domattr-isid.xml
index 664d63c918..2a7691641d 100644
--- a/reference/dom/functions/dom-domattr-isid.xml
+++ b/reference/dom/functions/dom-domattr-isid.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
   <refentry id='function.dom-domattr-isId'>
    <refnamediv>
     <refname>DOMAttr->isId</refname>
@@ -18,8 +18,35 @@
      </methodsynopsis>
     </classsynopsis>
     <para>
-     This function checks if the attribute is a defined ID.
+     This function checks if the attribute is a defined ID. &return.success;
     </para>
+    <para>
+     According to the DOM standard this requires a DTD which defines the 
+     attribute ID to be of type ID. You need to validate your document with
+     <link linkend="function.dom-domdocument-validate">DOMDocument->validate()</link> 
+     or <literal>DOMDocument::validateOnParse</literal> before using this function.
+    </para>
+    <example>
+     <title>DOMDocument->getElementById() Example</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+
+$doc = new DomDocument;
+
+// We need to validate our document before refering to the id
+$doc->validateOnParse = true;
+$doc->Load('book.xml');
+
+// We retrieve the attribute named id of the chapter element
+$attr = $doc->getElementsByTagName('chapter')->item(0)->getAttributeNode('id');
+
+var_dump($attr->isId()); // bool(true)
+
+?>
+]]>
+     </programlisting>
+    </example>
    </refsect1>
   </refentry>
 
diff --git a/reference/dom/functions/dom-domdocument-getelementbyid.xml b/reference/dom/functions/dom-domdocument-getelementbyid.xml
index 5a3ecc5940..1cc7b6d9b0 100644
--- a/reference/dom/functions/dom-domdocument-getelementbyid.xml
+++ b/reference/dom/functions/dom-domdocument-getelementbyid.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
   <refentry id="function.dom-domdocument-getelementbyid">
    <refnamediv>
     <refname>DOMDocument->getElementById</refname>
@@ -18,8 +18,40 @@
     <para>
      This function is similar to
      <link linkend="function.dom-domdocument-getelementsbytagname">DOMDocument->getElementsByTagName()</link> 
-     but searches for an element with a given id. According to the DOM standard 
-     this requires a DTD which defines the attribute ID to be of type ID.
+     but searches for an element with a given id.
+    </para>
+    <para>
+     According to the DOM standard this requires a DTD which defines the 
+     attribute ID to be of type ID. You need to validate your document with
+     <link linkend="function.dom-domdocument-validate">DOMDocument->validate()</link> 
+     or <literal>DOMDocument::validateOnParse</literal> before using this function.
+    </para>
+    <example>
+     <title>DOMDocument->getElementById() Example</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+
+$doc = new DomDocument;
+
+// We need to validate our document before refering to the id
+$doc->validateOnParse = true;
+$doc->Load('book.xml');
+
+echo "The element whose id is books is: " . $doc->getElementById('books')->tagName . "\n";
+
+?>
+]]>
+     </programlisting>
+     &example.outputs;
+     <screen>
+<![CDATA[
+The element whose id is books is: chapter
+]]>
+     </screen>
+    </example>
+    <para>
+     See also <link linkend="function.dom-domdocument-getelementsbytagname">DOMDocument->getElementsByTagName()</link>. 
     </para>
    </refsect1>
   </refentry>