|
 |
Zend Framework 2 Documentation (Manual) |  |
|
File: /_sources/modules/zend.navigation.view.helper.sitemap.txt
| Size: | 12722 |
| Storage flags: | no_autoload,compress/gzip (19%) |
.. _zend.navigation.view.helper.sitemap:
View Helper - Sitemap
=====================
.. _zend.navigation.view.helpers.sitemap.introduction:
Introduction
------------
The Sitemap helper is used for generating *XML* sitemaps, as defined by the `Sitemaps XML format`_. Read more about
`Sitemaps on Wikipedia`_.
By default, the sitemap helper uses :ref:`sitemap validators <zend.validator.sitemap>` to validate each element
that is rendered. This can be disabled by calling *$helper->setUseSitemapValidators(false)*.
.. note::
If you disable sitemap validators, the custom properties (see table) are not validated at all.
The sitemap helper also supports `Sitemap XSD Schema`_ validation of the generated sitemap. This is disabled by
default, since it will require a request to the Schema file. It can be enabled with
*$helper->setUseSchemaValidation(true)*.
.. _zend.navigation.view.helper.sitemap.elements:
.. table:: Sitemap XML elements
+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|Element |Description |
+==========+======================================================================================================================================================================================================================================================================================================================================================================================================+
|loc |Absolute URL to page. An absolute URL will be generated by the helper. |
+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|lastmod |The date of last modification of the file, in W3C Datetime format. This time portion can be omitted if desired, and only use YYYY-MM-DD. The helper will try to retrieve the lastmod value from the page's custom property lastmod if it is set in the page. If the value is not a valid date, it is ignored. |
+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|changefreq|How frequently the page is likely to change. This value provides general information to search engines and may not correlate exactly to how often they crawl the page. Valid values are: alwayshourlydailyweeklymonthlyyearlynever The helper will try to retrieve the changefreq value from the page's custom property changefreq if it is set in the page. If the value is not valid, it is ignored.|
+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|priority |The priority of this URL relative to other URLs on your site. Valid values range from 0.0 to 1.0. The helper will try to retrieve the priority value from the page's custom property priority if it is set in the page. If the value is not valid, it is ignored. |
+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Methods in the sitemap helper:
- *{get|set}FormatOutput()* gets/sets a flag indicating whether *XML* output should be formatted. This corresponds
to the *formatOutput* property of the native ``DOMDocument`` class. Read more at `PHP: DOMDocument - Manual`_.
Default is ``FALSE``.
- *{get|set}UseXmlDeclaration()* gets/sets a flag indicating whether the *XML* declaration should be included when
rendering. Default is ``TRUE``.
- *{get|set}UseSitemapValidators()* gets/sets a flag indicating whether sitemap validators should be used when
generating the DOM sitemap. Default is ``TRUE``.
- *{get|set}UseSchemaValidation()* gets/sets a flag indicating whether the helper should use *XML* Schema
validation when generating the DOM sitemap. Default is ``FALSE``. If ``TRUE``.
- *{get|set}ServerUrl()* gets/sets server *URL* that will be prepended to non-absolute *URL*\ s in the ``url()``
method. If no server *URL* is specified, it will be determined by the helper.
- ``url()`` is used to generate absolute *URL*\ s to pages.
- ``getDomSitemap()`` generates a DOMDocument from a given container.
.. _zend.navigation.view.helper.sitemap.basic-usage:
Basic usage
-----------
This example shows how to render an *XML* sitemap based on the setup we did further up.
.. code-block:: php
:linenos:
// In a view script or layout:
// format output
$this->navigation()
->sitemap()
->setFormatOutput(true); // default is false
// other possible methods:
// ->setUseXmlDeclaration(false); // default is true
// ->setServerUrl('http://my.otherhost.com');
// default is to detect automatically
// print sitemap
echo $this->navigation()->sitemap();
Notice how pages that are invisible or pages with *ACL* roles incompatible with the view helper are filtered out:
.. code-block:: xml
:linenos:
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>http://www.example.com/</loc>
</url>
<url>
<loc>http://www.example.com/products</loc>
</url>
<url>
<loc>http://www.example.com/products/server</loc>
</url>
<url>
<loc>http://www.example.com/products/server/faq</loc>
</url>
<url>
<loc>http://www.example.com/products/server/editions</loc>
</url>
<url>
<loc>http://www.example.com/products/server/requirements</loc>
</url>
<url>
<loc>http://www.example.com/products/studio</loc>
</url>
<url>
<loc>http://www.example.com/products/studio/customers</loc>
</url>
<url>
<loc>http://www.example.com/products/studio/support</loc>
</url>
<url>
<loc>http://www.example.com/company/about</loc>
</url>
<url>
<loc>http://www.example.com/company/about/investors</loc>
</url>
<url>
<loc>http://www.example.com/company/news</loc>
</url>
<url>
<loc>http://www.example.com/company/news/press</loc>
</url>
<url>
<loc>http://www.example.com/archive</loc>
</url>
<url>
<loc>http://www.example.com/community</loc>
</url>
<url>
<loc>http://www.example.com/community/account</loc>
</url>
<url>
<loc>http://forums.example.com/</loc>
</url>
</urlset>
.. _zend.navigation.view.helper.sitemap.rendering-noacl:
Rendering using no *ACL* role
-----------------------------
Render the sitemap using no *ACL* role (should filter out /community/account):
.. code-block:: php
:linenos:
echo $this->navigation()
->sitemap()
->setFormatOutput(true)
->setRole();
.. code-block:: xml
:linenos:
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>http://www.example.com/</loc>
</url>
<url>
<loc>http://www.example.com/products</loc>
</url>
<url>
<loc>http://www.example.com/products/server</loc>
</url>
<url>
<loc>http://www.example.com/products/server/faq</loc>
</url>
<url>
<loc>http://www.example.com/products/server/editions</loc>
</url>
<url>
<loc>http://www.example.com/products/server/requirements</loc>
</url>
<url>
<loc>http://www.example.com/products/studio</loc>
</url>
<url>
<loc>http://www.example.com/products/studio/customers</loc>
</url>
<url>
<loc>http://www.example.com/products/studio/support</loc>
</url>
<url>
<loc>http://www.example.com/company/about</loc>
</url>
<url>
<loc>http://www.example.com/company/about/investors</loc>
</url>
<url>
<loc>http://www.example.com/company/news</loc>
</url>
<url>
<loc>http://www.example.com/company/news/press</loc>
</url>
<url>
<loc>http://www.example.com/archive</loc>
</url>
<url>
<loc>http://www.example.com/community</loc>
</url>
<url>
<loc>http://forums.example.com/</loc>
</url>
</urlset>
.. _zend.navigation.view.helper.sitemap.rendering-maxdepth:
Rendering using a maximum depth
-------------------------------
Render the sitemap using a maximum depth of 1.
.. code-block:: php
:linenos:
echo $this->navigation()
->sitemap()
->setFormatOutput(true)
->setMaxDepth(1);
.. code-block:: xml
:linenos:
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>http://www.example.com/</loc>
</url>
<url>
<loc>http://www.example.com/products</loc>
</url>
<url>
<loc>http://www.example.com/products/server</loc>
</url>
<url>
<loc>http://www.example.com/products/studio</loc>
</url>
<url>
<loc>http://www.example.com/company/about</loc>
</url>
<url>
<loc>http://www.example.com/company/about/investors</loc>
</url>
<url>
<loc>http://www.example.com/company/news</loc>
</url>
<url>
<loc>http://www.example.com/community</loc>
</url>
<url>
<loc>http://www.example.com/community/account</loc>
</url>
<url>
<loc>http://forums.example.com/</loc>
</url>
</urlset>
.. note::
**UTF-8 encoding used by default**
By default, Zend Framework uses *UTF-8* as its default encoding, and, specific to this case, ``Zend\View`` does
as well. So if you want to use another encoding with ``Sitemap``, you will have do three things:
1. Create a custom renderer and implement a ``getEncoding()`` method;
2. Create a custom rendering strategy that will return an instance of your custom renderer;
3. Attach the custom strategy in the ``ViewEvent``;
See the :ref:`example from HeadStyle documentation <zend.view.helpers.initial.headstyle.encoding.example>`
to see how you can achieve this.
.. _`Sitemaps XML format`: http://www.sitemaps.org/protocol.php
.. _`Sitemaps on Wikipedia`: http://en.wikipedia.org/wiki/Sitemaps
.. _`Sitemap XSD Schema`: http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd
.. _`PHP: DOMDocument - Manual`: http://php.net/domdocument
For more information about the PHK package format: http://phk.tekwire.net