Page resource

This resource allows you to retrieve page content from the CMS. By default it will include the rendered HTML of the primary component of the specified page. Or the component data can instead be requested using the _with_component argument.

This endpoint will also output data about the page including:

  • code
  • name
  • parent_code (what page does this appear under. 0 indicates it is a top level page).
  • title
  • image - the "Header image" for the page
  • intro - the "Header introduction"
  • render - the rendered HTML
  • hide - is the page set to hide on the website or not

Additionally, the following SEO related fields will be returned if they are set:

  • head_title - SEO title text
  • keywords - SEO keywords text
  • description - SEO meta description
  • priority - SEO priority setting
  • nofollow - is the page set to nofollow for search engines

Retrieving by code

You can retrieve a page by its code value by passing it as the "record" part of the endpoint. E.g. https://www.foo.nz/API/V3/Page/00512. This will attempt to retrieve page 00512.

To get the code for a page, there are a few options: - from the API result of another Page request - in the ZEST website admin, edit a page. Look at the URL & you will see e.g. .../admin/page-editor?item_id=00512. The item_id is the page code. - if you have access to the database - get it from there

Retrieving by path

Alternatively you can retrieve by path by searching the Page endpoint with a path querystring: e.g. https://www.foo.nz/API/V3/Page?path=services/lawn-mowers. Not the path should not contain the domain. Any leading forward slash, or trailing .html are ignored.

If the path contains spaces, you can use either + or a space to represent the space. E.g. https://www.foo.nz/API/V3/Page?path=Contact+Us or https://www.foo.nz/API/V3/Page?path=Contact Us

Rendering the page

When redering the HTML (default option), it will not render the website template (i.e. it will not render the inherit_from_id of the component), but it will render children related component (in content_component_rel - components that you have added to the page in website edit mode).

Requesting component data

Instead of rendering the component to HTML, you can instead request its data by passing the argument _with_component=1. If this argument is present, the <Page> component will contain a <component> node (instead of a <render> node) which then contains the values of any set content options.

Any component data fields that contain links or images will have them converted to full (absolute) URL paths. You can disable this (e.g. if you would rather retrieve the page code) for link fields by specifying export_raw: 1 in its component metadata for the relevant field.

Unsafe HTML

Most content is managed by a rich text editor, so we need to assume there could be unsafe HTML in it. However the API will scrub all content by default, removing potentially unsafe items such as scripts, CSS, iframes etc.

If you would really like the original content to be exported unscrubbed, you can pass the modifier _with_unsafe_html=1.

Links

Determining page links can be costly in terms of API load. It is not a problem for just a few pages, but if there are large amounts of pages being retrieved by the API, this can get problematic (lots of hits isn't a problem thanks to caching - just retrieving large amounts of content pages in a single request).

To mitigate this, by default retrieving the link for each page is disabled. If you would like it to be included in the request, include the querystring argument _with_links=1.

If this is included, an href attribute will be added to the <page> node - e.g. it will return <page href="https://www.foo.nz/Services/Lawnmowewrs.html">.

Children pages

You may want to retrieve the whole content tree below a specific page on the site. To do this pass _with_children=1 in the querystring. This will retrieve the requested page, and then the full tree of children below them (its children, grandchildren etc).

Be careful using this on large content websites as it does not currently paginate results.

Children Depth

By default ZEST will look up to 5 levels deep for pages. However you can override this by passing a _depth argument. E.g. _depth=1 will just look at immediate children, _depth=2 will include grandchildren & so on.

Full Page Render Example

The below example may be a GET request to https://www.foo.nz/API/V3/Page/00287?_with_children=1&_with_links=1 will retrieve XML similar to that below:

<ResultSet session="" xmlns="http://www.zeald.com">
    <Page href="https://www.foo.nz/about-us">
        <code>00287</code>
        <name>About Us</name>

        <!-- title may be the same as the name, or it may differ -->
        <title>About Us</title>

        <image>https://www.foo.nz/images/about-us.jpg</image>
        <intro>Header intro text</intro>

        <!-- top level page -->
        <parent_code>0</parent_code>
        <render>
            <!-- raw page html content in here -->
            &lt;h1&gt;About Us&lt;/h1&gt;
            &lt;div class=&quot;content_main&quot;&gt;Foo content&lt;/div&gt;
            <!-- etc -->
        </render>
        <hide>1</hide>
        <nofollow>1</nofollow>
        <type>ContentDisplay/Content</type>
    </page>

    <!-- child page has the parent code of the one above -->
    <page href="https://www.foo.nz/about-us/our-team">
        <code>00289</code>
        <name>Our Team</name>
        <title>About Our Team</title>
        <image>https://www.foo.nz/images/team.jpg</image>
        <intro>Check out our all star team.</intro>
        <parent_code>00287</parent_code>
        <render>
            &lt;div class=&quot;content_main&quot;&gt;Foo content&lt;/div&gt;
            <!-- etc -->
        </render>
        <hide>1</hide>
        <type>ContentDisplay/Content</type>
    </page>
</ResultSet>