Data types
Each client method returns a different data type.
ContentSet
The contentset_list method returns a list of
ContentSet objects.
A ContentSet object has of the following properties:
- contentset_id
- name
- description
- is_default
Refer to the API data types docs for more information on
these fields.
ArticleNode
The contentset(contentset_id) method returns a single ArticleNode.
This node represents the root of a tree of Articles.
An ArticleNode has the following properties:
- article
- The Article instance associated with this node
- children
- A list of ArticleNode instances of which the current node
is the parent.
It is possible to iterate over an article node. This will traverse the
entire tree in a depth first order. So, for example, to get a flat list
of all the articles in a tree one could do this:
tree = client.contentset(1)
articles = [node.article for node in tree if node.article]
To recurse over the tree use the children property:
def visit(node, parent=None):
"""
Visit each node in the tree.
"""
# do something with node, then recurse
for child in node.children:
visit(child, node)
tree = client.contentset(1)
visit(tree)
Article
The article(external_reference) method returns a single Article
instance. Another way to get an Article object is by accessing
the article property of an ArticleNode.
An Article has the following properties:
- external_reference
- short_title
- title
- article_text
- parent_reference
- position
- last_change_date
- canonicaltag
- tags
Refer to the API data types docs for more information on
these fields.
Note
The article_text of Articles retrieved from the
contentset endpoint can contain several placeholder strings.
This library provides a number of utilities
to deal with those.
In addition to these fields the Article object also
provides these properties:
- path
- The url of the article. This is identical to the canonicaltag
but the schema://domain prefix is stripped.
- slug
- The last element of the path. i.e. if path is '/foo/bar/'
then slug will be 'bar'.
Image
The image(image_id) method returns a single Image
instance.
- image_id
- data
- content_type
- name
- creation_date
Refer to the API data types docs for more information on
these fields.
Converting image data to binary
The Image object also provides an as_binary method.
This method converts to base64 encoded value of the data
property to binary. The return value of this method can be used
to store images on a file system.
Article utils
The article_text of Articles returned by the contentset
method can contain a number special placeholder strings.
opvoeden_api.article_utils provides functions to deal with
these placeholders.
Replace JGZ placeholders
To replace JGZ placeholders with appropriate strings use
replace_jgz.
By default these are the substitutions:
| Placeholder |
Substitution |
|---|
| jgz |
centrum voor Jeugd en Gezin (CJG) |
| Jgz |
Centrum voor Jeugd en Gezin (CJG) |
| jgzs |
CJG’s |
| Jgzs |
CJG’s |
| de jgzs |
de CJG’s |
| De jgzs |
De CJG’s |
| het jgz |
het Centrum voor Jeugd en Gezin (CJG) |
| Het jgz |
Het Centrum voor Jeugd en Gezin (CJG) |
To override any of the substitutions use the optional
substitutions argument to replace_jgz i.e.:
replace_jgz(article_text, substitutions={
'jgz': 'centrum voor Jeugd en Gezin'
})
Replace internal link placeholders
To replace internal link placeholders use replace_links
with a replacement callback.
The replacement callback is called with the external_id
and link_text for each placeholder in the article text.
If the replacement callback returns anything other than None
the link is replaced with the return value.
For example:
external_id_to_href = {
'1': '/example/',
'2': '/example/more/'
}
def get_link(external_id, link_text):
"""
Get the url for an article and return an HTML snippet
that links to this url with the given text.
"""
href = external_id_to_href.get(external_id, None)
if href:
return '<a href="{}">{}</a>'.format(href, link_text)
replace_links(article_text, get_link)
Replace image placeholders
To replace image placeholders use replace_images
with a replacement callback.
The replacement callback is called with the image_id
for each placeholder in the article text.
If the replacement callback returns anything other than None
the placeholder is replaced with the return value.
For example:
image_id_to_src = {
'1': '/media/1.gif',
'2': '/media/2.gif'
}
def get_image_tag(image_id):
src = image_id_to_src.get(image_id, None)
if src:
return '<img src="{}">'.format(src)
Hint
The replacement callback is an excellent place call the
image endpoint of the API.
Replace video placeholders
To replace YouTube video placeholders use replace_videos
with a replacement callback.
The replacement callback is called with the video_id, embed_url
and external_url for each placeholder in the article text.
If the replacement callback returns anything other than None
the placeholder is replaced with the return value.
Some examples:
def get_video_embed(video_id, embed_url, external_url):
"""Create an iframe to embed the video"""
return '<iframe src="{}">'.format(embed_url)
def get_video_link(video_id, embed_url, external_url):
"""Create a link to the video player on opvoeden.nl"""
return '<a href="{}" target="_blank">Watch the video</a>'.format(
external_url)
