PX - All Methods

The PX Class

The project centers around a class named px, for PHP/XML. The px class represents a DOM XML document and all the nodes within the document.

There are two other classes of note: the px_nodes and px_method classes (like the px class) are subclasses of the pxObject class. Both are utility classes for implementation of a jQuery-like syntax.

In the documentation, the term "px object" is used specifically to mean an instance of the px class, while a pxObject is an object instance of any of the three. All three pxObject subclasses implement the same methods and can be used interchangeably, but px_nodes and px_method objects are created by and depend on the existence of an owning px object.

Understanding PX Objects is not really necessary unless you want to write your own plugins, but they are described in grueling detail on the PX Objects documentation page.

Creating a PX Object

You can create a pxObject using the px() function or the new operator.

			$px1 = px('Some html.');
			$px2 = new px('anHtmlFile.htm');
		

Unlike JQuery, which by default works with the XML (HTML) within the loaded document, the PX class needs for you to specify some XML that it should work with. In the example above, a short XML string is specified and this is the content the $px1 object will operate on. The $px2 object will operate on the xml contained in the anHtmlFile.htm file.

You can create a blank px object by passing no parameters, or you can pass one of the following types as an argument:
  • A string containing XML text
  • A string containing the file path to an XML file
  • A PHP DOMDocument object
  • A PHP DOMElement or DOMNode object
  • Another, previously created pxObject
Passing a DOMDocument associates that particular object with the px object being created. Passing any other parameter types (including another px object) will cause a new DOMDocument to be created and associated with the new px object.

Using a PX Object

Once you have a px object loaded with XML data, you can manipulate and display it using any available methods. The following sections show methods available in version 017 of the PX class.

Other methods may be available as plugins. Plugin use is exactly the same as normal method use, described below. Plugin documentation will be available soon.

html()

The html method returns the xml stored in the calling pxObject, formatted in such a way that empty xml tags are NOT condensed into one tag with a slash. For example, <textarea></textarea> is NOT changed to <textarea/>.

			$px = new px('<div><textarea></textarea></div>');
			echo $px->html();
		
Result:
<div>
  <textarea></textarea>
</div>

html( string )

Pass a string to the html() method to replace all child nodes of currently matched elements.

			$px = px('<div id="languages"><b>PHP</b><b>XML</b></div>');
			$px->xpath("/div")->html("<b>Hello, World!</b>");
			echo $px->html();
		
Result:
<b>Hello, World!</b>

xml()

The xml method returns the xml stored in the calling pxObject, formatted in such a way that empty xml tags ARE condensed into one tag with a slash. For example, <textarea></textarea> IS changed to <textarea/>.

			echo px('<div><empty></empty></div>')->xml();
		
Result:
<div>
  <empty/>
</div>

text()

The text method returns the text stored in matching nodes.

			// get some text
			$px1 = px('<div><someText>Hello, World!</someText></div>');
			echo $px1->xpath("//someText")->text();
			
			// compile all text from the b tags
			$pxMany = px('<div id="languages"><b>PHP</b><b>XML</b><b>JQuery</b></div>');
			echo "\n".$pxMany->xpath("//b")->text();
		
Result:
Hello, World!
PHPXMLJQuery

text( string )

Pass a string to the text() method to set the value as the text content of all matched nodes.

			$px = px('<div id="languages"><b>PHP</b><b>XML</b></div>');
			$px->xpath("/div")->text("Hello, World!");
			echo $px->html();
		
Result:
<div id="languages">Hello, World!</div>

val ( [ value ] )

With no argument, the val() method returns the node value of the first matched node. If a value is specified, the node value of all matching nodes is set.

			$px = px("<div><input name='x' value='X'></input><input name='y' value='Y'></input></div>");
			echo $px->xpath("//input")->val();
			echo "\n".$px->xpath("//input")->val('Z')->html();
		
Result:
X
<input name="x" value="Z"></input><input name="y" value="Z"></input>

doc( [ propertyName [ , propertyValue ] )

Provides access to the DOMDocument object.

Returns the DOMDocument object associated with any pxObject. Returns a named property value if one parameter is specified. If two parameters are specified, it sets the named property to the specified property value and returns the calling pxObject.

Note that some DOMDocument properties are "read only".

			$px = new px("<xml><Aa><Bb><Cc/></Bb></Aa></xml>");
			echo $px->doc("formatOutput",0)->html();
			echo "\n".$px->doc("formatOutput",1)->html();
		
Result:
<xml><Aa><Bb><Cc></Cc></Bb></Aa></xml>
<xml>
  <Aa>
    <Bb>
      <Cc></Cc>
    </Bb>
  </Aa>
</xml>

xpath( string )

The xpath method returns selected nodes from the pxObject's xml. Enter a string of xpath, then print the results using the html method.

			$px = px('
PHPXMLJQuery
'); echo $px->xpath("//b")->html();
Result:
<b>PHP</b><b>XML</b><b>JQuery</b>

It's important to understand that the affect of the xpath method apply only to objects it's result calls, not to the calling pxObject itself. If you apply an xpath filter on one line, then call the html method on the next line, the filter will not seem to have worked. It is possible, however, to store the filter by setting a variable and using that in later calls.

			$px = px('<div id="languages"><b>PHP</b><b>XML</b><b>JQuery</b></div>');
			
			// apply a filter, but do nothing with it
			$px->xpath("//b");
			echo "1) ". $px->html() . "\n";
			
			// save the filter in a variable
			$filteredNodes = $px->xpath("//b");
			echo "2) ". $filteredNodes->html();
		
Result:
1) <div id="languages">
  <b>PHP</b>
  <b>XML</b>
  <b>JQuery</b>
</div>
2) <b>PHP</b><b>XML</b><b>JQuery</b>

each( function )

The each method is used to execute a PHP function on every matching node. Pass a function as the parameter. Your function can accept one parameter, which will be a PX Node object wrapping a DOM Node.

	function myFunc () {
		echo "You Found a 'B' Tag! Bzzzzz!!!\n";
	}
	$px = px('<div id="languages"><b>PHP</b><b>XML</b></div>');
	$px->xpath("//b")->each(myFunc);
		
Result:
You Found a 'B' Tag! Bzzzzz!!!
You Found a 'B' Tag! Bzzzzz!!!

If you're running a version of PHP that supports Closures, you can define the function as a parameter:

	$px=px("<div><b>Hello</b> <i>World!</i> <b>Look at Me!</b> <i>Here I am!</i></div>");
	$px->xpath("//i")->each( function ($px, $i) {
		$px->index($i)->attr("style","color: red;");
	});
	echo $px->html();
Result:
<div>
  <b>Hello</b>
  <i style="color: red;">World!</i>
  <b>Look at Me!</b>
  <i style="color: red;">Here I am!</i>
</div>

get( [ elementIndex ] )

Provides access to matched DOMNode objects.

When given an integer, get() returns the DOMNode object associated with the pxObject. With no argument, an array of all matching DOMNode objects is returned.

			function aGetMethodExampleFn ($px) {
				echo $px->get(0)->nodeName . " = " . $px->text()."\n";
			}
			$px = new px("<div><b>Hello!</b><span>World</span></div>");
			$px->xpath("/div/*")->each(aGetMethodExampleFn);
Result:
b = Hello!World
b = Hello!World

index( [ elementIndex ] )

Provides access to a pxObject representing the element number specified by the argument. The argument is zero-based.

			$px = new px("<div><b>Hello!</b><span>World</span></div>");
			echo $px->xpath("/div/*")->index(0)->html();
			echo " ".$px->xpath("/div/*")->index(1)->html();
Result:
<b>Hello!</b> <span>World</span>




Attributes and Classes

attr( attributeName [, newValue] )

The attr method is used to get or set xml attributes. It would generally be used in combination with the xpath (or any other filtering methods) to get or set one or more specific nodes in the calling pxObject's xml.

When called with one argument, it returns a string - the value named by the argument - for the first node result from any previous xpath results.

When called with two arguments, it sets the value of the attribute named by the first argument to the value specified in the second argument for ALL matching nodes.

			$px = px('<div id="languages"><b>PHP</b><b>XML</b><b>JQuery</b></div>');
			echo $px->xpath("/div")->attr("id"); // returns "languages"
			$px->xpath("/div")->attr("class", "blue"); // sets class="blue"
			echo "\n".$px->html();
		
Result:
languages
<div id="languages" class="blue">
  <b>PHP</b>
  <b>XML</b>
  <b>JQuery</b>
</div>

removeAttr( attributeName )

Removes named attributes from all matching elements.

			$px = px('<div class="languages"><b class="b1 lang">PHP</b><b class="lang">XML</b></div>');
			$px->xpath("/div|//b")->removeAttr("class");
			echo $px->html();
		
Result:
<div>
  <b>PHP</b>
  <b>XML</b>
</div>

hasClass( className )

Returns true if any matching object has a class attribute matching the parameter.

			$px = px('<div id="lang"><b class="b1">PHP</b><b class="b2">XML</b></div>');
			echo $px->xpath("//b")->hasClass("b1") ? "Yes" : "No";
			echo "\n".($px->xpath("//b")->hasClass("lang") ? "Yes" : "No");
		
Result:
Yes
No

addClass( className )

Adds a class without removing any existing ones.

			$px = px('<div id="languages"><b class="php">PHP</b><b>XML</b></div>');
			$px->xpath("//b")->addClass("lang");
			echo $px->html();
		
Result:
<div id="languages">
  <b class="php lang">PHP</b>
  <b class="lang">XML</b>
</div>

addClass( function )

Adds a class without removing any existing ones.

Always wrap function names in a call to px::fn() so that they will be treated as a function, rather than a string.
			function fn_class($pxo,$i) {
				return "f_".time();
			}
			$px = px('<div id="languages"><b>PHP</b><b>XML</b><b>JQuery</b></div>');
			echo $px->xpath("//b[1]")->addClass(fn_class)->html()."\n";
			echo $px->xpath("//b[2]")->addClass("fn_class")->html()."\n";
			echo $px->xpath("//b[3]")->addClass(px::fn("fn_class"))->html()."\n";
		
Result:
<b class="fn_class">PHP</b>
<b class="fn_class">XML</b>
<b class="f_1495695430">JQuery</b>

removeClass( className )

Removes the classes specified in the parameter (a space-separated string) without removing classes not specified.

			$px = px('<div id="languages"><b class="b1 lang">PHP</b><b class="b2">XML</b></div>');
			$px->xpath("//b")->removeClass("b1 b2");
			echo $px->html();
		
Result:
<div id="languages">
  <b class="lang">PHP</b>
  <b>XML</b>
</div>

removeClass( function )

Removes the classes specified by the return value of the function specified in the parameter.

			function fn_removeClass($pxo,$i) {
				return $pxo->index($i)->text()==="XML" ? "lang" : "";
			}
			$px = px('<div id="languages"><b class="b1 lang">PHP</b><b class="b2 lang">XML</b></div>');
			$px->xpath("//b")->removeClass(px::fn(fn_removeClass));
			echo $px->html();
		
Result:
<div id="languages">
  <b class="b1 lang">PHP</b>
  <b class="b2">XML</b>
</div>

toggleClass( className )

Adds named class in each matching node where it does not exist, removes the class in matching nodes where it does exist.

			$px = px('<div id="languages"><b class="b1 lang">PHP</b><b class="b2">XML</b></div>');
			$px->xpath("//b")->toggleClass("lang");
			echo $px->html();
		
Result:
<div id="languages">
  <b class="b1">PHP</b>
  <b class="b2 lang">XML</b>
</div>

toggleClass( function )

Toggles the classes specified by the return value of the function specified by the parameter.

			function fn_toggleClass($pxo,$i) {
				return $pxo->index($i)->hasClass("b2") ? "lang" : "";
			}
			$px = px('<div id="languages"><b class="b1 lang">PHP</b><b class="b2 lang">XML</b></div>');
			$px->xpath("//b")->toggleClass(px::fn(fn_toggleClass));
			echo $px->html();
		
Result:
<div id="languages">
  <b class="b1 lang ">PHP</b>
  <b class="b2">XML</b>
</div>




DOM Element Manipulation

after( xml )

Use the after method to insert content after each matched element.

Pass a string of xml.

			$px = px('<div id="languages"><b>PHP</b></div>');
			$px->xpath("//b")->after("<b>JQuery</b>")->after("<b>XML</b>");
			echo $px->html();
		
Result:
<div id="languages">
  <b>PHP</b>
  <b>XML</b>
  <b>JQuery</b>
</div>

after( function )

Add xml returned by a specified function to after each matched element.

Pass a function that returns xml.

			function fn_after($pxo,$i) {
				return '<b class="generated">JQuery</b>';
			}
			$px = px('<div id="languages"><b>PHP</b><b>XML</b></div>');
			$px->xpath("//b[2]")->after(px::fn(fn_after));
			echo $px->html();
		
Result:
<div id="languages">
  <b>PHP</b>
  <b>XML</b>
  <b class="generated">JQuery</b>
</div>

append( xml )

Append specified xml to the end of matched elements child list.

Pass a string of xml.

			$px = px('<div id="languages"><b>PHP</b><b>XML</b></div>');
			$px->xpath("/div")->append("<b>JQuery</b>");
			echo $px->html();
		
Result:
<div id="languages">
  <b>PHP</b>
  <b>XML</b>
  <b>JQuery</b>
</div>
			$px = px("<numbers/>");
			for($i=0; $i<4; $i++)
				$px->append("<num>$i</num>");
			echo $px->html();
		
Result:
<numbers>
  <num>0</num>
  <num>1</num>
  <num>2</num>
  <num>3</num>
</numbers>

append( function )

Append xml returned by a specified function to the end of matched elements child list.

Pass a function that returns xml.

			function fn_append($pxo,$i) {
				return '<b class="generated">JQuery</b>';
			}
			$px = px('<div id="languages"><b>PHP</b><b>XML</b></div>');
			$px->xpath("/div")->append(px::fn(fn_append));
			echo $px->html();
		
Result:
<div id="languages">
  <b>PHP</b>
  <b>XML</b>
  <b class="generated">JQuery</b>
</div>

appendTo( xpath )

Move all currently matched nodes to the end of the nodes selected by the argument (an xpath string).

Pass a string, the xpath describing the target node(s).

			$px = new px('<body><b>PHP</b><b>XML</b><div></div></body>');
			$px->xpath("//b")->appendTo("//div");
			echo $px->html();
		
Result:
<body>
  <div>
    <b>PHP</b>
    <b>XML</b>
  </div>
</body>

before( xml )

Insert the given content before each matched element.

Pass a string of xml.

			$px = px('<div id="languages"><b>PHP</b><b>JQuery</b></div>');
			$px->xpath("//b[2]")->before("<b>XML</b>");
			echo $px->html();
		
Result:
<div id="languages">
  <b>PHP</b>
  <b>XML</b>
  <b>JQuery</b>
</div>

before( function )

Add xml returned by a specified function before each matched element.

Pass a function that returns xml.

			function fn_before($pxo,$i) {
				return '<b class="generated">PHP</b>';
			}
			$px = px('<div id="languages"><b>XML</b><b>JQuery</b></div>');
			$px->xpath("//b[2]")->before(px::fn(fn_before));
			echo $px->html();
		
Result:
<div id="languages">
  <b>XML</b>
  <b class="generated">PHP</b>
  <b>JQuery</b>
</div>

clone()

Use the clone method to copy all matched elements.

			$px = px('<div id="languages"><b>PHP</b><b>XML</b></div>');
			$clonedStuff = $px->xpath("//b")->clone();
			$px->xpath("//b")->addClass("original");
			echo $px->html()."\n".$clonedStuff->addClass("copied")->html();
		
Result:
<div id="languages">
  <b class="original">PHP</b>
  <b class="original">XML</b>
</div>
<b class="copied">PHP</b><b class="copied">XML</b>

detach()

Use the detach method to remove all matched elements but replace the set of matched elements with any removed nodes.

			$px = px('<div id="languages"><b>PHP</b><b>XML</b><span/></div>');
			$px->xpath("//b")->detach()->appendTo("//span");
			echo $px->html();
		
Result:
<div id="languages">
  <span>
    <b>PHP</b>
    <b>XML</b>
  </span>
</div>

empty()

Removes all child nodes (including text) from all currently matched nodes.

			$px = px('<div id="languages"><b>PHP</b><b>XML</b></div>');
			$px->xpath("/div")->empty();
			echo $px->html();
		
Result:
<div id="languages"></div>

insertAfter( xpath )

Use the insertAfter method to move all currently matched nodes end of the nodes selected by the argument (an xpath string).

Pass a string, the xpath describing the target node(s).

			$px = new px("<div><span> Jones</span><div><b>Bob</b><i>, and</i><b>Sue,</b></div></div>");
			$px->xpath("//span")->insertAfter("//b");
			echo $px->html();
		
Result:
<div>
  <div>
    <b>Bob</b>
    <span> Jones</span>
    <i>, and</i>
    <b>Sue,</b>
    <span> Jones</span>
  </div>
</div>

insertBefore( xpath )

Use the insertBefore method to insert all currently matched nodes to the beginning of nodes selected by the argument.

Pass a string, the xpath describing the target node(s).

			$px = px("<div><span>Dear</span><div><b>Bob</b><i>, and</i><b>Sue,</b></div></div>");
			$px->xpath("//span")->insertBefore("//b");
			echo $px->html();
		
Result:
<div>
  <div>
    <span>Dear</span>
    <b>Bob</b>
    <i>, and</i>
    <span>Dear</span>
    <b>Sue,</b>
  </div>
</div>

prepend( xml )

Prepend children to the beginning of matched elements.

Pass a string of xml.

			$px = px('<div id="languages"><b>PHP</b><b>XML</b></div>');
			$px->xpath("/div")->prepend("<b>JQuery</b>");
			echo $px->html();
		
Result:
<div id="languages">
  <b>JQuery</b>
  <b>PHP</b>
  <b>XML</b>
</div>

prepend( function )

Prepend xml returned by a specified function to the beginning of each matched element's child list.

Pass a function that returns xml.

			function fn_prepend($pxo,$i) {
				return '<b class="generated">PHP</b>';
			}
			$px = px('<div id="languages"><b>XML</b><b>JQuery</b></div>');
			$px->xpath("/div")->prepend(px::fn(fn_prepend));
			echo $px->html();
		
Result:
<div id="languages">
  <b class="generated">PHP</b>
  <b>XML</b>
  <b>JQuery</b>
</div>

replaceAll( xpath )

Use the replaceAll method to replace all elements matching the specified xpath argument with the contents of currently matched elements.

Pass a string of xml.

			$px = px('<div id="languages"><b>PHP</b><b>XML</b><i>Replace Them!</i></div>');
			echo $px->xpath("//b")->replaceAll("//i")->html();
			echo "\n".$px->html();
		
Result:
<b>PHP</b><b>XML</b>
<div id="languages">
  <i>Replace Them!</i>
  <i>Replace Them!</i>
</div>

replaceWith( xml )

Use the replaceWith method to replace all matched elements with the xml (a string) specified in the argument.

Pass a string of xml.

			$px = px('<div id="languages"><b>JQuery</b></div>');
			$px->xpath("//b")->replaceWith("<b>PHP</b>");
			echo $px->html();
		
Result:
<div id="languages">
  <b>PHP</b>
</div>

replaceWith( function )

Replace each matched element with the xml generated by a given function.

Pass a function that returns xml.

			function fn_replace($pxo,$i) {
				return "<i>".$pxo->index($i)->text()."</i>";
			}
			$px = px('<div id="languages"><b>PHP</b><b>XML</b><b>JQuery</b></div>');
			$px->xpath("//b")->replaceWith(px::fn(fn_replace));
			echo $px->html();
		
Result:
<div id="languages">
  <i>PHP</i>
  <i>XML</i>
  <i>JQuery</i>
</div>

remove()

Use the remove method to remove all matched elements.

			$px = px('<div id="languages"><b>PHP</b><b>XML</b></div>');
			$px->xpath("//b")->remove();
			echo $px->html();
		
Result:
<div id="languages"></div>

wrap( xml )

Use the wrap method to surround matched items in an xml element you specify in the argument.

			$px = new px('<div id="languages"><b>PHP</b><b>XML</b></div>');
			$px->xpath("//b")->wrap("<span/>");
			echo $px->html();
		
Result:
<div id="languages">
  <span>
    <b>PHP</b>
  </span>
  <span>
    <b>XML</b>
  </span>
</div>

wrap( function )

Wrap each matched element in a new parent tag specified by the xml generated by a given function.

Pass a function that returns xml.

			function fn_wrap($pxo,$i) {
				return "<i></i>";
			}
			$px = px('<div id="languages"><b>PHP</b><b>XML</b><b>JQuery</b></div>');
			$px->xpath("//b")->wrap(px::fn(fn_wrap));
			echo $px->html();
		
Result:
<div id="languages">
  <i>
    <b>PHP</b>
  </i>
  <i>
    <b>XML</b>
  </i>
  <i>
    <b>JQuery</b>
  </i>
</div>

wrapInner( string )

Wrap each child node of each matched element in the xml given in the argument.

			$px = px('<div id="languages"><b>PHP</b><b>XML</b></div>');
			$px->xpath("/div")->wrapInner("<i></i>");
			echo $px->html();
		
Result:
<div id="languages">
  <i>
    <b>PHP</b>
    <b>XML</b>
  </i>
</div>