Page

The page object represents pages within the "Content Management" or CMS section of Evance. A "page" variable containing a Page object is automatically instantiated on URLs governed by the CMS. 

A page variable containing a Page object is automatically instantiated on CMS driven pages.

Templates for pages should be located within a Theme's ~/theme/page directory. These templates will have access to the current page's properties and methods described on this page.

Properties of your page can be output using the existing page variable.

<div>
    <h1>{{ page.title }}</h1>
    <p>{{ page.description }}</p>
</div>


Programmatically finding Pages

You can also gain access to a page and its properties from any other template programmatically. 

If you need to find multiple pages you should use the PageSearch object instead - it's more efficient. 

We now recommend using the new find methods when fetching a single page:

The example below shows how you can find a page by its system ID. 

<?ev
    var myPage = new Page();
    
    if (myPage.findById(1234)) {
        print(myPage.title + ' was found');
    } else {
        print('Page was not found');
    }
?>


Instantiation

Finding page data may be done when instantiating a new Page object and supplying the page's URL or ID. However, we now recommend using the newer 'find' methods (as described above):


<?ev
    // new Page() class method
    var homepage = new Page('/');
?>

Note hard coding URLs in this manner can be open to error if the URL no longer exists.


Construct parameters
reference String | Url | Number

The page reference is either a String/Url representing the URL relative to root (e.g. / represents the homepage), or a Number representing the page.id. 

For international and multi-lingual sites you should use the default URL as the reference for the page and not the localised version. Evance will automatically correct the URL format for you once the Page object is retrieved.



Properties
aseets Object

An Object containing Assets for the page as defined in the Template Config. Each property within the object returned will be the same as the IDs of asset types assigned to the page template. The value of each property will be an Array containing an asset Object. 

Example: perhaps your homepage supports one or more banner images achieved with a slideshow asset defined in your config/templates.json file as:


{ 
    ...
    "home": {
            "title": "Homepage",
            "path": "/portal/web/gateway/theme/v4/page/home.evml",
            "assets": [
                {
                    "title": "Homepage Banner",
                    "asset": "slideshow",
                    "id": "banners"
                }
            ]
        }
    ...

The slideshow may be defined within the same file as:


    ...
    "assets": {
        "slideshow" : {
            "title": "Slideshow",
            "properties": [
                {
                    "title": "Image",
                    "id": "image",
                    "type": "image"
                }
            ]
        }
    }
    ...
}


Accessing the banner images may be done like this:


The first banner image URL is {{ page.assets.banners[0].image }}
author Contact

Author property is null if no author is set, or as a Contact object if a valid author is set.

averageRating Number

The average rating out of 5 the Page has received.

created Date

The date the page was created represented as a Date object.

description String

The short description for the page represented as a String. Pages do not have a single content block as they may have any number of editable regions. These are represented as fragments that should be rendered via the <ev:editable> tag.

downvotes Number

The total number of negative votes the Page has received from Users.

expires Date

The Date on which this page will expire, and cease to show on your website.

id Number

The page id represented as a Number.

hasChildren Boolean

A Boolean with a value of true if the page has child pages, or false if not.

metaDescription String

The <meta> description for the Page.

metaKeywords String

The <meta> keywords for the Page.

metaTitle String

The title used for the Page's <title> tag.

modified Date

The Date on which this page was last modified.

parentId Number

The ID for the parent page as a Number. To get the full parent page as an object use the Page.parent() method.

published Date

The Date on which this page was published. Pages do not appear on your website till this date, allowing you to schedule when pages appear.

settings Object

An Object containing page properties defined in the Template Config and their values represented as a String. Setting property labels correlate to the id of the setting and the property value represents the value of the setting. Values can be changed by users from within the CMS editor. 

The best way to visualise this is with an excerpt from config/templates.json settings file for a page with properties.


{ 
    ...
    "properties": [
        {
            "title": "Property 1",
            "id": "PROPERTY1",
            "type": "text",
            "value": "VALUE 1 (DEFAULT)"
        }
    ]
    ...
}

...and then the resulting setting object:


The setting is {{ page.settings.PROPERTY1 }}
tags Object

Contains an object whose properties are the tag type identifiers assigned to the page's Template within the Template Config file. By default Evance supports 'tag', but you may have any number of tag types. Each property contains a TagType object.

For example, tags assigned to a blog post might look like this in your config/templates.json file:


{ 
    ...
    "blog_post": {
        "title": "Blog Post",
        "path": "/portal/web/gateway/theme/v4/page/blog_post.evml",
        "parents": [
            "blog"
        ],
        "children": false,
        "url": "{{year}}/{{month}}",
        "thumbnail": "/portal/shared/theme/v1/cms/thumbnails/blog_post.png",
        "tags": [
            "tag"
        ]
    }
    ...
}

This results in page.tags having a 'tag' property containing a TagType object for a blog post, which could be accessed like this to show the TagType title and the titles of each Tag assigned to the page:


{{ page.tags.tag.title }}: 
{{ page.tags.tag.items.pluck('title').join(', ') }}
template Template

References the template of this page. When printed this property will output the reference of the template, but is in fact a Template object.

thumbnail Url

The image Url chosen to represent this page. This is called thumbnail for historic reasons, but may be of any size.

title String

Contains the title of the page represented as a String.

totalRatings Number

The total number of ratings out of 5 the Page has received.

upvotes Number

The total number of positive votes the Page has received from Users.

url Url

The Url of the page. If you have an international website this Url will represent the current Locale of your website.



Methods
ancestors() PageCollection

A synonym of parents()

archiveWithin() Array

.. of Objects containing month and year dates of descendant pages, useful for archive representation of your blog. Each Object within the Array returned has the following properties:

  • title : String
    The archive date e.g. August 2015

  • total : Number
    The total number of descendant pages for this archive date.

  • date: Date
    The archive date represented as a Date object. 

  • isActive : Boolean
    True if the current page is filtering descendant pages by this date.

authorsWithin() Array

...of authors as Contact objects for all descendant pages of the current Page. This is useful for obtaining all authors within a blog, for example. 

Each Contact object is populated with two additional properties:

  • isActive : Boolean
    This is only true if the author is filtered on the current page. For example if you filter a blog by author. 

  • total : Number
    The total number of articles the author has written. 

children([Number:limit]) PageSearch

...of child Page objects. If limit is not provided then all children are returned. The order of the children respects the sort order available in page.template.sort, which is defined in the Template Config file. If no sort order is defined the default order will reflect the sequence of pages as they appear within the CMS page hierarchy (sequence:asc). 


<?ev
    for(var i in page.children){
        var child = page.children[i];
?>
<li>
    <h3>{{ child.title }}</h3>
    <p>{{ child.description }}</p>
    <a href="{{ child.url }}">Read more</a>
</li>
<?ev } ?>

Please refrain from using the children() method without a limit for pages with numbers of child Page objects that would require pagination, such as Blog Posts. Such pages have other paginated mechanisms for showing child Page objects. However, obtaining the most recent Blog Post can be retrieved by supplying a limit of 1.


<p>Check out our latest blog post</p>
<?ev
    var blog = new Page('/blog');
    var latest = blog.children(1).get(0); // get(0) is the equivalent of [0]
?>
<a href="{{ latest.url }}">{{ latest.title }}</a>

descendants() PageSearch

All sub-pages recursively of the current Page - exclusive of the current Page. If you require a tree structure for a menu you may like to try the Page.tree() method.

findByAlias(String uri) Boolean

Find a page by its unique alias/URI. Returns true if the page was found, and false if not found.

<?ev
    var myPage = new Page();
    
    if (myPage.findByAlias('/my-page')) {
        // Page found
    } else {
        // Page not found
    }
?>


The alias supplied must be the URI path to the page (e.g. '/my-page'). If the path includes a locale prefix (e.g. '/en-gb/my-page') Evance will globalise the URI prior to lookup.

findById(Number id) Boolean

Find a page by its system ID. Returns true if the page was found, and false if not found.

<?ev
    var myPage = new Page();
    
    if (myPage.findById(1)) {
        // Page was found
    } else {
        // Page Not Found
    }
?>
fragment(String reference) PageFragment | null

Returns a PageFragment object which contains the HTML content for the fragment matching the given reference.

Returns null if the fragment was not found.

fragments() Object | null

Returns an object containing all available content fragments for the page.

hasFragment(String reference) Boolean

Returns true if a content fragment exists with the supplied reference.

next([Number:limit]) Page | PageCollection | null

When no argument is provided page.next() will return the next sibling Page object, or null if no next sibling is available. However, if a limit/number is provided the page.next() method will return a PageCollection of sibling pages. In either case this method respects the page.template.sort property defined in Template Config. Which, for example, means it is possible to show the next three blog posts in correct sequence when on a Blog Post.

parents() PageCollection

...of this page's parent Page objects in order of closest parent first.

prev([Number:limit]) Page | PageCollection | null

When no argument is provided page.prev() will return the previous sibling to the Page object, or null if no previous sibling is available. Sound familiar? Yep, this method is the opposite to page.next(). You guessed it, if a limit/number is provided the page.prev() method will return a PageCollection of previous sibling pages. In either case this method respects the page.template.sort property defined in Template Config. Which, for example, means it is possible to show the previous three blog posts in correct sequence when on a Blog Post.

previous([Number:limit]) Page | PageCollection | null

If you have a problem with shortening names then you can use the page.previous() method instead of page.prev(), because we're considerate like that.

relatedByTags() PageSearch

Returns a page search object to search all pages with the same tags as the current page without any additional conditions. This allows you to find related pages from different sections of a website, but also means you will need to apply additional limits and conditions if you require to search within the current or alternative section.

siblings() PageCollection

... of sibling pages and respects the page.template.sort property defined within the Template Config file.  

tagsWithin() Object

Does everything that the tags property does (above), but for all descendants of the current page recursively, excluding itself. This property is useful for blog pages where you wish to show all available tags for articles within the blog.

topAncestor() Page

The Page at the top of the tree for the current Page. Useful for knowing which section of a website you are within.

tree() PageCollection

All sub-pages recursively of and including the current Page. This is a useful property for use with menus e.g.


<ev:menu object="page.topAncestor.tree" />

Notice that methods that do not require parameters may be written in property format.
See <ev:menu> for more details. 

userHasRated() Boolean

Determines whether the current user has already rated this page.
Returns true or false value as appropriate. If a user is not logged in, a value of false is applied.

userHasVoted() Boolean

Determines whether the current user has given the current page a vote up or down.
Returns true or false value as appropriate. If a user is not logged in, a value of false is applied.

userHasVotedDown() Boolean

Determines whether the current user has given the current page a vote down.
Returns true or false value as appropriate. If a user is not logged in, a value of false is applied.

userHasVotedUp() Boolean

Determines whether the current user has given the current page a vote up.
Returns true or false value as appropriate. If a user is not logged in, a value of false is applied.