', 'foo')->append('baz')->writeXML(); * @endcode * * The above will create a new document from the XML string, find the foo element, and then * append the bar element (complete with its text). Finally, the call to QueryPath::writeXML() will * print the entire finished XML document to standard out (usually the web browser). * * Here's an example using htmlqp(): * * @code * require 'QueryPath/QueryPath.php'; * * // URL to fetch: * $url = 'http://technosophos.com'; * * print htmlqp($url, 'title')->text(); * @endcode * * The above will fetch the HTML from the given URL and then find the title tag. It will extract * the text (QueryPath::text()) from the title and print it. * * For more examples, check out the #Examples namespace (start with {@link examples/html.php}). Also, read about the * qp() and htmlqp() functions. * * @subsection online_sources Online Sources * * - The official QueryPath site http://querypath.org * - The latest API docs http://api.querypath.org * - IBM DeveloperWorks Intro to QueryPath http://www.ibm.com/developerworks/web/library/os-php-querypath/index.html * - QueryPath articles at TechnoSophos.Com http://technosophos.com/qp/articles * - The QueryPath GitHub repository http://github.com/technosophos/querypath * * If you find a good online resource, please submit it as an issue in GitHub, and we will * most likely add it here. * * @subsection more_examples A Larger Example * * @include examples/html.php * * @page extensions Using and Writing Extensions * * Using an extension is as easy as including it in your code: * * @code * comment('This is an HTML comment.'); * ?> * @endcode * * Like jQuery, QueryPath provides a simple mechanism for writing extensions. * * Check out QPXSL and QPXML for a few easy-to-read extensions. QPDB provides an example of * a more complex extension. * * QueryPathExtension is the master interface for all extensions. * */ /** @page CSSReference CSS Selector Reference * QueryPath provides two query 'languages' that you can use to search through XML and HTML * documents. The main query language is an implementation of the CSS3 Selectors specification. This * is the query language that jQuery and CSS use -- and more recently, FireFox itself supports it * via its JavaScript API. CSS3 should be familiar to developers and designers who have worked with * HTML and stylesheets. * * QueryPath also allows XPath selectors, which can be executed using QueryPath::xpath(). While * fewer functions take XPath expressions, it is noless a powerful tool for querying DOM objects. * * @code * xpath('//foo'); * ?> * @endcode * * QueryPath provides a full CSS3 selector implementation, including all of the specified operators, * robost not() and has() support, pseudo-class/elements, and XML namespace support. * * Selectors can be passed into a number of QueryPath functions including qp(), htmlqp(), * QueryPath::find(), QueryPath::top(), QueryPath::children() and others. * @code * branch('p'); // Create another QP object that searches BODY for P tags. * $qp->find('strong>a'); // Find all of the A elements directly inside of STRONG elements. * $qp->top('head'); // Start over at the top of the document, and find the HEAD tag. * ?> * @endcode * * In all of the examples above, CSS selectors are used to locate specific things inside of the * document. * * @section selector_examples Example Selectors * Example selectors: * - p: Select all P elements in a document. * - strong a: Select any A elements that are inside (children or descendants of) a STRONG * element. * - strong>a: Select only A elements that are directly beneath STRONG elements. * - :root>head select HEAD elements that are directly beneath the document root. * - h1, h2: Select all H1's and H2's. * - a:link: Select all A tags that have hrefs * - div.content: Select all DIV elements that have the class=content set. * - #my-id: Select the element that has id=my-id. * - p:contains(Hello World): Select any P elements that have the text Hello World. * - p:not(.nav): Select any elements in P that do not have the nav class. * * @section pseudo_reference Pseudo-class and pseudo-element selectors * QueryPath provides an implementation of the CSS3 spec, including the CSS3 pseudo-classes and * pseudo-elements defined in the spec. Some of the CSS3 pseudo-classes require a user agent, and * so cannot be adequately captured on the server side, but all others have been implemented. * * Additionally, jQuery has added its own pseudo-classes, and jQuery users have come to expect those * to work. So for the sake of convenience, we have implemented those as well. These include the * form pseudo-classes, along with several others. * * Finally, QueryPath has added a couple of useful pseudo-classes, namely :x-root and * :contains-exactly. * * @subsection pseudoelement_ref Pseudo-Elements * * Pseudo-elements are new in CSS3, and are syntactically similar to pseudo-classes. To use a * pseudo-element in a selector, use the double-colon syntax: ::begins. The following pseudo- * elements are defined in QueryPath: * * - first-line: Selects the first line -- everything up to the first LF character (\ n). * - first-letter: Slects the first letter of the element. * * These throw exceptions because they cannot be implemented without a user agent: * - before * - after * - selection * * Pseudo-elements should be used with care, as they act like elements, but are not. * * @code * get(); * ?> * @endcode * * @subsection pseudoclass_reference Pseudo-Classes * * Pseudo-classes are more familiar to CSS and jQuery users. They use a single-colon syntax, and * are used to narrow the set of selected elements. * * The following pseudo-classes are supported: * - link: Matches anything with the href attribute. * - root: The root element of the document * - x-root: The root element that was passed into QueryPath's constructor * - x-reset: Same as above. * - even: All even elements in a set. First element is odd. * - odd: Odd elements in a set. First element is odd. * - nth-child: Every nth child in a set. * - nth-last-child: Every nth child in a set, counting from the end. * - nth-of-type: Every nth tag in a set. * - nth-last-of-type: Every nth tag in a set, counting from the end. * - first-child: The first child in a set. * - last-child: The last child in a set. * - first-of-type: The first child of the specified tag in a set. * - last-of-type: The last child of the specified tag in a set. * - only-child: Matches only if this is the only child in a set. * - only-of-type: Matches only if it is the only child of the given tag in a set. * - empty: Selects only empty elements. * - not: The negation operator, takes a CSS3 selector, e.g. :not(strong>a). * - lt: Items in a set whose index is less than the given integer, e.g. lt(3) * - gt: Items in a set whose index is greater than the given integer, e.g. gt(3) * - nth: The nth item in a set, e.g. nth(3) * - eq: The nth item in a set, e.g. eq(3) * - first: The first item in a set. * - last: The last item in a set. * - parent: Matches if the item is a parent of child elements. * - enabled: Matches (form) items that are enabled * - disabled: Matches form items that are disabled * - checked: Matches form items that are checked * - text: Matches form items that are text fields * - radio: Matches form items that are radio fields * - checkbox: Matches form items that are checkboxes. * - file: Matches form items that are file upload widgets. * - password: Mathces form items that are password entry boxes. * - submit: Matches submit buttons * - image: Matches image buttons * - reset: Matches reset buttons * - button: Matches buttons * - header: Matches header fields (h1-h6) * - has: Matches any items that have children that match the given selector, e.g. :has(strong>a) * - contains: Contains *text* that matches. This is a substring match. * - contains-exactly: Contains *exactly* the given text. This is NOT a substring match. * * These generate errors because they are not implemented: * - indeterminate * - lang * * These are quietly ignored because they require a user agent to be meaningful. * - visited * - hover * - active * - focus * - animated * - visible * - hidden * - target * * Examples: * @code * * @endcode * @section xml_namespaces XML Namespaces * QueryPath also supports the CSS3 namespace selection syntax. This is syntactically different * than the XML namespace tag format. To select a tag whose namespaced name is foo:bar, the * CSS element selector would be foo|bar (note the vertical bar instead of a colon). While * QueryPath does its best to resolve namespaces to short names, there is a possibility that a * malformed namespace will prevent specific namespace queries. * * You can also query across namespaces with *|tagname. * * @code * elements. * qp($xml, 'atom|entry > xmedia|video'); // Find all elements directly inside elements. * qp($xml, '*|entry'); // Find any namespaced tag that has `entry` as the tag name. * ?> * @endcode */