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. 

<body>
    <div>
        <h1>{{ page.title }}</h1>
    </div>
</body>

You can gain access to any page within your CMS when creating a new Page instance.

<body>
    <div>
        <h1>{{ page.title }}</h1>
    </div>
    
    <?ev var blog = new Page('/blog'); ?>
    
    <h2>{{ blog.title }}</h2>
    <p>{{ blog.description }}</p>
</body>

Note: hard coding URLs in this manner can be open to error if URLs don't exist. If however the URL for a page did exist, but a user changed it within the CMS, Evance will attempt to load the page from its historical URL. A preferred method is to utilise a settings object allowing users to rectify or maintain such issues.

Instantiation

Accessing any Page in the CMS can be achieved from anywhere within your website and not just from CMS governed pages. This can be done by instantiating a new Page object and supplying the page's URL:


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


Construct parameters
reference

Type String, Url or 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
assets

Type 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

Type Contact

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

created

Type Date

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

description

Type 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.

expires

Type Date

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

id

Type Number

The page id represented as a Number.

hasChildren

Type Boolean

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

modified

Type Date

The Date on which this page was last modified.

parentId

Type Number

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

published

Type 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

Type 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

Type 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

Type 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

Type Url

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

title

Type String

Contains the title of the page represented as a String.

url

Type Url

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



Methods
ancestors()

A synonym of parents()

archiveWithin()

Returns 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()

Returns 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])

Returns PageCollection

...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()

Returns PageCollection

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 tree method.

next([Number:limit])

Returns 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()

Returns PageCollection

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

prev([Number:limit])

Returns 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])

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.

siblings()

Returns PageCollection

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

tagsWithin()

Returns 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()

Returns 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()

Returns 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.