child-pages.txt

== Child Pages ==
There are various methods to construct a page hierarchy which depends on the structure of the application and the complexity.

The simplest way is using the child_ specials
{{{
#!python

class ChildPage(rend.Page):
    addSlash = True

    docFactory = loaders.stan(tags.html[
        tags.body[
            'This is a child page'
        ]
    ])

class APage(rend.Page):
    addSlash = True

    child_aChild = ChildPage()

    docFactory = loaders.stan(tags.html[
        tags.head[
            tags.title['Child Example']
        ],
        tags.body[
            tags.a(href='/aChild/')['Go to child page']
        ]
    ])
}}}

This constructs a page with a child called ChildPage accessed via /aChild/.

This example can be extended further to demonstrate overriding the childFactory method

{{{
#!python

class ComplexChildren(rend.Page):
    addSlash = True
    docFactory = loaders.stan(tags.html[
        tags.body[
            'Another child'
        ]
    ])

class ChildPage(rend.Page):
    addSlash = True

    docFactory = loaders.stan(tags.html[
        tags.body[
            'A page'
        ]
    ])

    def childFactory(self, ctx, childSegment):
        if childSegment == 'myChild':
            return ComplexChildren()
        else:
            rend.Page.childFactory(self, ctx, childSegment)
}}}

This provides a convenient way to locate multiple children which might require different initialisation arguments. Note that childSegment is a string containing the resource that was requested. 

As an example if we wanted to allocate the same resource to a bunch of child resources, we can create a dictionary with references to the page resource and instantiate it with the child segment.
{{{
#!python
class ChildPage(rend.Page):
    myChildren = {
        'Dog': Animal,
        'Cat': Animal,
        'Zebra': Animal
    }

    def childFactory(self, ctx, childSegment):
        if childSegment in self.myChildren:
            return self.myChildren[childSegment](childSegment)
        else:
            rend.Page.childFactory(self, ctx, childSegment)
}}}

This is also a convenient way to provide REST style arguments.