Sections - The Website Structure¶

Goal¶

A website needs some basic structure, like folders on a computer. Metro Publisher currently supports a two-level navigational structure: sections and subsections.

We want to create the following navigational structure for our Metro Publisher instance:

Vacations
- Rome
- Paris
Bill's Website

We are also going to add a hidden section, i.e. a section that does not appear in the navigation on the public website:

Mike's Playground

Let's assume we've already uploaded an image that we can use as a feature image for the section 'Vacations':

an image
- title: Rome at Night
- UUID: ffffffff-ffff-ffff-ffff-ffffffffffff

Creating Sections¶

To add a section, we send a PUT request to the sections resource /{iid}/sections/{uuid}. This resource allows us to create a new section and set its basic information, such as the title, urlname and various meta_ attributes. We can also assign a feature image for the section which will appear at the top of the section's page.

>>> PUT("/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
...                       {'urlname': 'vacations',
...                        'title': 'Vacations',
...                        'meta_title': 'Vacations',
...                        'meta_description': 'Articles and other content concerning my vacations.',
...                        'meta_keywords': 'vacations, rome, paris, italy, france',
...                        'content_uuid': '11111111-1111-1111-1111-111111111111',
...                        'feature_image_uuid': 'ffffffff-ffff-ffff-ffff-ffffffffffff',
...                        'feature_image_caption': 'Rome at night is a sight to behold.',
...                        'auto_featured_stories': True,
...                        'number_stories': 10,
...                        'show_prev_next': True,
...                        'ord': 1})
{'url': 'https://api.metropublisher.com/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
 'uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'}

meta_* parameters

The meta_ attributes are used to construct the corresponding HTML Meta elements on the public website.

content_uuid and feature_image_* parameters

A section/subsection can have one content object assigned to it as its featured content. This is done by passing the content object's UUID in the parameter content_uuid. The featured content will appear at the top of the section's page and may have an image associated with it. The information for the featured image is defined using the feature_image_* parameters.

feature_image_uuid:	The UUID of the image.
feature_image_caption:	Short, descriptive text for the image.

auto_featured_stories and number_stories

A section page can either display a list of the latest issued content objects within that section or a manually selected list of content objects. By setting the auto_featured_stories parameter to True, we tell the system that we want the latest issued content objects to be displayed. The parameter number_stories defines how many content objects are to be displayed.

ord

This parameter specifies where the section is placed within its navigational level. In our example, we want the 'Vacations' section to be the first section within the top-level sections, so we give it an ord of 1.

show_prev_next

If this parameter is True, content pages within this section will show links to previous/next content (according to the content issue date).

Note

Even though the intuitive thing here would be to give this section the urlname 'blogs', we can't do that. 'blogs' is a restricted word because it is used for creating the urls to real blog pages and content associated with a blog (i.e. blog posts). So we use the urlname 'the-blogs' here instead.

Creating Sublevel Sections¶

Subsections are like top-level sections, but they have a section assigned to them as a parent. Creating a subsection is done the same way and via the same resource as a top-level section, with the added parameter parent_uuid

>>> PUT("/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-bbbbbbbbbbbb",
...                       {'urlname': 'rome',
...                        'title': 'Rome',
...                        'meta_title': 'Vacation in Rome',
...                        'meta_description': 'Articles and other content concerning my vacation in Rome in 2012.',
...                        'meta_keywords': 'vacations, rome',
...                        'parent_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
...                        'auto_featured_stories': True,
...                        'number_of_stories': 10,
...                        'ord': 1})
{'url': 'https://api.metropublisher.com/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-bbbbbbbbbbbb',
 'uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-bbbbbbbbbbbb'}

The top-level section 'Vacations' is supposed to have one other subsection: 'Paris'. Let's add it now:

>>> PUT("/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-cccccccccccc",
...                       {'urlname': 'paris',
...                        'title': 'Paris',
...                        'meta_title': 'Vacation in Paris',
...                        'meta_description': 'Articles and other content concerning a vacation in Paris.',
...                        'meta_keywords': 'vacations, paris',
...                        'parent_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
...                        'auto_featured_stories': True,
...                        'number_of_stories': 10,
...                        'ord': 2})
{'url': 'https://api.metropublisher.com/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-cccccccccccc',
 'uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-cccccccccccc'}

Note

Note that 'Paris' has the ord 2, i.e. it is supposed to be the second subsection of 'Vacations'.

Creating Non-Standard Sections¶

The last non-hidden section we want to add is a bit different than the ones we added above. The navigation item for this section ("Bill's Website") should direct the website visitor directly to the website of our friend Bill.

Bill's website is located at:

http://www.william-keith-johnson.com

To create a non-standard section, we can use the override functionality of a section's external_url attribute. The external_url attribute can be used both to link a navigation item to an internal object or to an external url, such as http://www.somedomain.com/interesting-page.html.

In our case, we'll use it to link to Bill's website:

>>> PUT("/123/sections/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
...                       {'urlname': "william-keith-johnson",
...                        'title': "Bill's Website",
...                        'external_url': 'http://www.william-keith-johnson.com',
...                        'ord': 2})
{'url': 'https://api.metropublisher.com/123/sections/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
 'uuid': 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'}

Creating Hidden Sections¶

We can create 'hidden' sections, i.e. sections that do not appear in the navigation of the public website. The parameter for this is called hide_in_nav and accepts the values True and False:

>>> PUT("/123/sections/cccccccc-cccc-cccc-cccc-cccccccccccc",
...                       {'urlname': 'mikes-playground',
...                        'title': "Mike's Playground",
...                        'hide_in_nav': True,
...                        'ord': 3})
{'url': 'https://api.metropublisher.com/123/sections/cccccccc-cccc-cccc-cccc-cccccccccccc',
 'uuid': 'cccccccc-cccc-cccc-cccc-cccccccccccc'}

This hidden section is just a place for "Mike" to put all his content. We don't want this to appear in the navigation though. Any published (and issued) content from within this hidden section is still available on the website and can be linked in like any other content object from one of the non-hidden sections.

Retrieving the Navigation¶

So, now we've added our two sections as well as three subsections and a hidden section, we can retrieve those sections by calling:

>>> GET("/123/sections?fields=title-parentid-ord-url-hide_in_nav")
{'items': [["Bill's Website",
            None,
            2,
            'https://api.metropublisher.com/123/sections/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
            False],
           ["Mike's Playground",
            None,
            3,
            'https://api.metropublisher.com/123/sections/cccccccc-cccc-cccc-cccc-cccccccccccc',
            True],
           ['Paris',
            'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
            2,
            'https://api.metropublisher.com/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-cccccccccccc',
            False],
           ['Rome',
            'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
            1,
            'https://api.metropublisher.com/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-bbbbbbbbbbbb',
            False],
           ['Vacations',
            None,
            1,
            'https://api.metropublisher.com/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
            False]]}

"Vacations", "Bill's Website" and "Mike's Playground" are top-level sections because their parent is 'None'. "Mike's Playground" is marked as a section that is to be hidden from the navigation.

"Rome" and "Paris" are sections inside 'Vacations', as their parent is the section 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa' (= the UUID of the section 'Vactions').

Note

It is currently not possible to order this list according to their parent and order number, i.e. you cannot retrieve a tree-like structure. You will have to build the tree structure yourself.

Without any filtering, the GET /{iid}/sections resource returns all available sections, i.e. top-level as well as sub-level sections. We can retrieve just the top-level sections by using the parents filter with the value 'root':

>>> GET("/123/sections?fields=title-parentid-url&parents=root")
{'items': [["Bill's Website",
            None,
            'https://api.metropublisher.com/123/sections/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'],
           ["Mike's Playground",
            None,
            'https://api.metropublisher.com/123/sections/cccccccc-cccc-cccc-cccc-cccccccccccc'],
           ['Vacations',
            None,
            'https://api.metropublisher.com/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa']]}

We can also get the top-level sections together with some of the sub-level sections by also passing a UUID of a section to the parents parameter:

>>> GET("/123/sections?fields=title-parentid-url&parents=root_aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")
{'items': [["Bill's Website",
            None,
            'https://api.metropublisher.com/123/sections/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'],
           ["Mike's Playground",
            None,
            'https://api.metropublisher.com/123/sections/cccccccc-cccc-cccc-cccc-cccccccccccc'],
           ['Paris',
            'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
            'https://api.metropublisher.com/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-cccccccccccc'],
           ['Rome',
            'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
            'https://api.metropublisher.com/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-bbbbbbbbbbbb'],
           ['Vacations',
            None,
            'https://api.metropublisher.com/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa']]}

As you can see, this returns:

the top-level sections:
- Vacations
- Bill's Website
- Mike's Playground
the sub-level sections inside 'Vacations':
- Rome
- Paris

Note

The parameter parents may contain more than one section UUID.

Section Featured Stories¶

Sections (may) have so called "Featured Stories". Featured stories are content objects that appear on a section's index page and can be set up for each section in two different ways:

automatic: This is the default setting for a section. The most recent articles, reviews, etc. from inside the section appear on the section index page. How many content objects appear depends on the limit set up for the section.
manual: With the 'manual' setting, the list of featured stories is comprised of manually selected content objects.

The resource GET /{iid}/sections/{uuid}/featured_stories returns a section's featured stories, independent on whether the section is set up for automatic or manual featured stories:

>>> GET("/123/sections/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/featured_stories")
{'items': [{'description': 'Last christmas I decided that this year I would finally take that trip to Rome that I had been thinking about for so many years.',
            'issued': '2012-08-12T10:00:00',
            'thumb_url': None,
            'title': 'My Last Trip to Rome',
            'type': 'content',
            'url': 'https://api.metropublisher.com/123/content/11111111-1111-1111-1111-111111111111',
            'uuid': '11111111-1111-1111-1111-111111111111'},
           {'description': None,
            'issued': '2012-08-13T08:00:00',
            'thumb_url': 'https://api.metropublisher.com/123/files/ffffffff-ffff-ffff-ffff-eeeeeeeeeeee/download/1345453200',
            'title': 'Great Food, Great Wine, Great Atmosphere',
            'type': 'content',
            'url': 'https://api.metropublisher.com/123/content/77777777-7777-7777-7777-777777777777',
            'uuid': '77777777-7777-7777-7777-777777777777'}]}

API Documentation

Sections - The Website Structure¶

Goal¶

Creating Sections¶

Creating Sublevel Sections¶

Creating Non-Standard Sections¶

Creating Hidden Sections¶

Retrieving the Navigation¶

Section Featured Stories¶

Table Of Contents

Previous topic

Next topic

Navigation

Sections - The Website Structure¶

Goal¶

Creating Sections¶

Creating Sublevel Sections¶

Creating Non-Standard Sections¶

Creating Hidden Sections¶

Retrieving the Navigation¶

Section Featured Stories¶

Table Of Contents

Previous topic

Next topic

Quick search

Navigation