Improve documentation for specific commands

GravityPDF · Apr 12, 2024 · c5f1174 · c5f1174
1 parent b4b2bd1
commit c5f1174
Show file tree

Hide file tree

Showing 2 changed files with 107 additions and 55 deletions.
diff --git a/examples/basic-manipulation-filter-and-retrieval/index.php b/examples/basic-manipulation-filter-and-retrieval/index.php
@@ -53,12 +53,11 @@
 	echo '<h2>Example 1</h2>';
 	echo 'Add the attribute <code>class="cell"</code> to all <code>&lt;td&gt;</code> elements:';
 
-	echo '<pre><code>
-&lt;?php 
+	echo '<pre><code>&lt;?php 
 
 echo html5qp($html, "td")
 -&gt;attr("class", "cell")
--&gt;top("table")
+-&gt;parents("table")
 -&gt;html()  
 </code></pre>';
 
@@ -69,13 +68,13 @@
 	echo htmlspecialchars(
 		html5qp($html, 'td')
 			->attr('class', 'cell')
-			->top('table') // jump back up the DOM to the table
-			->html() // get get HTML of the table
+			->parents('table') // traverse up the DOM until we match the table
+			->html() // get the HTML of the table
 	);
 
 	echo '</code></pre>';
 
-	echo 'If you want to output a valid HTML document, use <code>top()</code> without an argument:';
+	echo 'If you want to output a valid HTML document, replace <code>parents(\'table\')</code> with <code>top()</code>:';
 
 	echo '<pre><code>';
 
@@ -95,8 +94,7 @@
 		->find('#row2 > td:nth-child(2)')
 		->text();
 
-	echo '<pre><code>
-&lt;?php 
+	echo '<pre><code>&lt;?php 
 
 echo html5qp($html)
 -&gt;find("#row2 > td:nth-child(2)")
@@ -107,12 +105,11 @@
 
 	echo '<h2>Example 3</h2>';
 	echo 'Append an additional row at the end of the table:';
-	echo '<pre><code>
-&lt;?php 
+	echo '<pre><code>&lt;?php 
 
 echo html5qp($html, "td")
 -&gt;after("&lt;tr&gt;&lt;td&gt;seven&lt;/td&gt;&lt;td&gt;eight&lt;/td&gt;&lt;td&gt;nine&lt;/td&gt;&lt;/tr&gt;")
--&gt;top("table")
+-&gt;parents("table") // traverse up the DOM until we match the table
 -&gt;html()
 </code></pre>';
 
@@ -123,7 +120,7 @@
 	echo htmlspecialchars(
 		html5qp($html, 'tr:last')
 			->after("\n\n\t<tr>\n\t\t<td>seven</td>\n\t\t<td>eight</td>\n\t\t<td>nine</td>\n\t</tr>")
-			->top("table")
+			->parents('table')
 			->html()
 	);
 
@@ -136,12 +133,11 @@
 	echo '<h2>Example 1</h2>';
 	echo 'Add the attribute <code>class="item"</code> to all <code>&lt;desc&gt;</code> elements:';
 
-	echo '<pre><code>
-&lt;?php 
+	echo '<pre><code>&lt;?php 
 
 echo qp($xml, "desc")
 -&gt;attr("class", "item)
--&gt;top() // return to the &lt;categories&gt; tag
+-&gt;top() // return to the root node (&lt;categories&gt;)
 -&gt;xml(); // output a valid XML document.
 </code></pre>';
 
@@ -152,7 +148,7 @@
 	echo htmlspecialchars(
 		qp($xml, 'desc')
 			->attr('class', 'item')
-			->top() // return to the <categories> tag
+			->top() // return to the root node
 			->xml() // output a valid XML document
 	);
 
@@ -167,8 +163,7 @@
 		->find('categories > category:nth-child(3) desc')
 		->text();
 
-	echo '<pre><code>
-&lt;?php 
+	echo '<pre><code>&lt;?php 
 
 echo qp($xml)
 -&gt;find("categories > category:nth-child(3) desc")
@@ -179,8 +174,7 @@
 
 	echo '<h2>Example 3</h2>';
 	echo 'Append a category at the end of the group:';
-	echo '<pre><code>
-&lt;?php 
+	echo '<pre><code>&lt;?php 
 
 echo qp($xml, "category:last")
 -&gt;after("&lt;category name=\'Appended\'&gt;&lt;desc&gt;The appended node...&lt;/desc&gt;&lt;/category&gt;")

diff --git a/examples/create-html-document/index.php b/examples/create-html-document/index.php
@@ -16,43 +16,101 @@
 
 require_once __DIR__ . '/../../vendor/autoload.php';
 
+echo '<h1>Building a HTML Document with QueryPath</h1>';
+
+echo 'You can use QueryPath to build complex HTML documents using a simple jQuery-like API:';
+
+echo '<pre><code>&lt;?php 
+
+// Begin with an HTML5 stub document and navigate to the title.
+html5qp(\QueryPath\QueryPath::HTML5_STUB, "title")
+	// Add text to the title
+	-&gt;text("Example of QueryPath.")
+	// Traverse to the root of the document, then locate the body tag
+	-&gt;top("body")
+	// Inside the body, add a heading and paragraph.
+	-&gt;append("&lt;h1&gt;This is a test page&lt;/h1&gt;&lt;p&gt;Test text&lt;/p&gt;")
+	// Select the paragraph we just created inside the body
+	-&gt;children("p")
+	// Add a class attribute to the paragraph
+	-&gt;attr("class", "some-class")
+	// And an inline style to the paragraph
+	-&gt;css("background-color", "#eee")
+	// Traverse back up the DOM to the body
+	-&gt;parent()
+	// Add an empty table to the body, before the heading
+	-&gt;prepend("&lt;table id=\'my-table\'&gt;&lt;/table&gt;")
+	// Now go to the table...
+	-&gt;find("#my-table")
+	// Add a couple of empty rows
+	-&gt;append("&lt;tr&gt;&lt;/tr&gt;&lt;tr&gt;&lt;/tr&gt;")
+	// select the rows (both at once)
+	-&gt;children()
+	// Add a CSS class to both rows
+	-&gt;addClass("table-row")
+	// Get the first row (at position 0)
+	-&gt;eq(0)
+	// Add a table header in the first row
+	-&gt;append("&lt;th&gt;This is the header&lt;/th&gt;")
+	// Now go to the next row
+	-&gt;next()
+	// Add some data to this row
+	-&gt;append("&lt;td&gt;This is the data&lt;/td&gt;")
+	// Traverse to the root of the document
+	-&gt;top()
+	// Write it all out as HTML
+	-&gt;html();
+';
+
+echo '</code></pre>';
+
+echo '<h2>Results</h2>';
+
 try {
+	echo '<pre><code>';
+
+	echo htmlspecialchars(
 	// Begin with an HTML5 stub document and navigate to the title.
-	html5qp(\QueryPath\QueryPath::HTML5_STUB, 'title')
-		// Add some text to the title
-		->text('Example of QueryPath.')
-		// Now look for the <body> element
-		->top('body')
-		// Inside the body, add a title and paragraph.
-		->append('<h1>This is a test page</h1><p>Test text</p>')
-		// Now we select the paragraph we just created inside the body
-		->children('p')
-		// Add a 'class="some-class"' attribute to the paragraph
-		->attr('class', 'some-class')
-		// And add a style attribute, too, setting the background color.
-		->css('background-color', '#eee')
-		// Now go back to the paragraph again
-		->parent()
-		// Before the paragraph and the title, add an empty table.
-		->prepend('<table id="my-table"></table>')
-		// Now let's go to the table...
-		->top('#my-table')
-		// Add a couple of empty rows
-		->append('<tr></tr><tr></tr>')
-		// select the rows (both at once)
-		->children()
-		// Add a CSS class to both rows
-		->addClass('table-row')
-		// Now just get the first row (at position 0)
-		->eq(0)
-		// Add a table header in the first row
-		->append('<th>This is the header</th>')
-		// Now go to the next row
-		->next()
-		// Add some data to this row
-		->append('<td>This is the data</td>')
-		// Write it all out as HTML
-		->writeHTML5();
+		html5qp(\QueryPath\QueryPath::HTML5_STUB, 'title')
+			// Add text to the title
+			->text('Example of QueryPath.')
+			// Traverse to the root of the document, then locate the body tag
+			->top('body')
+			// Inside the body, add a heading and paragraph.
+			->append('<h1>This is a test page</h1><p>Test text</p>')
+			// Select the paragraph we just created inside the body
+			->children('p')
+			// Add a class attribute to the paragraph
+			->attr('class', 'some-class')
+			// And an inline style to the paragraph
+			->css('background-color', '#eee')
+			// Traverse back up the DOM to the body
+			->parent()
+			// Add an empty table to the body, before the heading
+			->prepend('<table id="my-table"></table>')
+			// Now let's go to the table...
+			->find('#my-table')
+			// Add a couple of empty rows
+			->append('<tr></tr><tr></tr>')
+			// select the rows (both at once)
+			->children()
+			// Add a CSS class to both rows
+			->addClass('table-row')
+			// Get the first row (at position 0)
+			->eq(0)
+			// Add a table header in the first row
+			->append('<th>This is the header</th>')
+			// Now go to the next row
+			->next()
+			// Add some data to this row
+			->append('<td>This is the data</td>')
+			// Traverse to the root of the document
+			->top()
+			// Write it all out as HTML
+			->html()
+	);
+
+	echo '</code></pre>';
 } catch (\QueryPath\Exception $e) {
 	die($e->getMessage());
 }