Services¶
A service is a name for a content object that provides a service to application code. It looks just like any other content object, but services that are added to a site can be found by name using various Substance D APIs.
Services expose APIs that exist for the benefit of application developers. For
instance, the catalogs
service provides an API that allows a developer to
index and query for content objects using a structured query API. The
principals
service allows a developer to add and enumerate users and
groups.
A service is added to a folder via the
substanced.folder.Folder.add_service()
API.
An existing service can be looked up in one of two ways: using the
substanced.util.find_service()
API or the
substanced.folder.Folder.find_service()
API. They are functionally
equivalent. The latter exists only as a convenience so you don’t need to
import a function if you know you’re dealing with a folder.
Either variant of find_service
will look down the resource hierarchy
towards the root until it finds a parent folder that has had add_service
called on it. If the name passed in matches the service name, the object
will be returned, otherwise the search will continue down the tree.
Note that a content object may exist in the folder with the same name as
you’re looking for via find_service
, but if that object was not added via
add_service
(instead it’s just a “normal” content object), it won’t be
found by find_service
.
Here’s how to use substanced.util.find_service()
:
from substanced.util import find_service
principals = find_service(somecontext, 'principals')
somecontext
above is any resource in the resource tree.
For example, somecontext
could be a “document” object you’ve added to a
folder.
Here’s how to use substanced.folder.Folder.find_service()
:
principals = somefolder.find_service('principals')
somefolder
above is any substanced.folder.Folder
object (or any
object which inherits from that class) present in the resource tree.
There is also the find-multiple-services variants
substanced.util.find_services()
and
substanced.folder.Folder.find_services()
.