Using The API¶
Target group: Developers
Table of Contents
Introduction¶
With the extension’s API you can define the structured markup with PHP. For example, create a class which gets an Extbase model as input and defines the markup. Then instantiate the class in an action of your controller.
Each type model class in the PHP namespace Brotkrueml\Schema\Model\Type
inherits from the abstract class
Brotkrueml\Schema\Core\Model\AbstractType
which defines methods to set
and get the properties of a model.
There are currently over 600 models available.
Starting with an example¶
Let’s start with a simple example. Imagine you describe a person on a plugin’s detail page that you want to enrich with structured markup. First you have to create the schema model:
$person = \Brotkrueml\Schema\Type\TypeFactory::createType('Person')
The schema type Person
maps to the model Person
. You can
use every accepted type from the core vocabulary from schema.org. Also have a look into the
ClassesModelType
folder of this extension to get a general idea of the
available types.
If the type is not available a \DomainException
is thrown.
Every type implements the \Brotkrueml\Schema\Core\Model\TypeInterface
.
You will find a list of the available methods in the section
Available type model methods.
Surely you will need to add some properties:
$person
->setId('http://example.org/#person-42')
->setProperty('givenName', 'John')
->setProperty('familyName', 'Smith')
->setProperty('gender', 'http://schema.org/Male');
;
That was easy … let’s go on and define an event the person attends:
$event = \Brotkrueml\Schema\Type\TypeFactory::createType('Event')
->setProperty('name', 'Fancy Event')
->setProperty('image', 'https:/example.org/event.png')
->setProperty('url', 'https://example.org/')
->setProperty('isAccessibleForFree', true)
->setProperty('sameAs', 'https://twitter.com/fancy-event')
->addProperty('sameAs', 'https://facebook.com/fancy-event')
;
Now we have to connect the two types together:
$person->setProperty('performerIn', $event);
The defined models are ready to embed on the web page. The schema manager does that for you:
$schemaManager = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(
\Brotkrueml\Schema\Manager\SchemaManager::class
);
$schemaManager->addType($person);
That’s it … if you call the according page the structured markup is embedded automatically into the head section:
{
"@context": "http://schema.org",
"@type": "Person",
"@id": "http://example.org/#person-42",
"givenName": "John",
"familyName": "Smith",
"gender": "http://schema.org/Male",
"performerIn": {
"@type": "Event",
"name": "Fancy Event",
"image": "https://example.org/event.png",
"url": "https://example.org",
"isAccessibleForFree": "http://schema.org/True",
"sameAs": ["https://twitter.com/fancy-event", "https://facebook.com/fancy-event"]
}
}
The model in-depth¶
Each type model, like Thing
, Person
or Event
, must implement the interface
Brotkrueml\Schema\Core\Model\TypeInterface
. For convenience, a type
model can also extend the abstract class
Brotkrueml\Schema\Core\Model\AbstractType
which implements every needed
method.
Two other interfaces are available, they are used to “mark” a type model class as a “special type” and don’t require the implementation of additional methods:
Brotkrueml\Schema\Core\Model\WebPageTypeInterface
for a web page type.Brotkrueml\Schema\Core\Model\WebPageElementTypeInterface
for a web page element type.
These interfaces can be useful when you want to extend the vocabulary.
Each type model delivered with this extension extends the AbstractType
class.
Available type model methods¶
The type models implement Brotkrueml\Schema\Core\Model\TypeInterface
or extend Brotkrueml\Schema\Core\Model\AbstractType
and expose the
following methods:
-
setId(string
$id)
¶
The method sets the unique ID of the model. With the ID, you can cross-reference types on the same page or between different pages (and even between different web sites) without repeating all the properties.
It is common to use an IRI as ID like in the above example. Please keep in mind that the ID should be consistent between changes of the properties, e.g. if a person marries and the name is changed. The person is still the same, so the IRI should be.
The IRI is no URL, so it is acceptable to give a “404 Not Found” back if you call it in a browser.
- Parameter
string $id
: The unique id to set.- Return value
- Reference to the model itself.
-
getId()
¶
Gets the id of the type model.
- Parameter
- none
- Return value
- A previously set id or null (if not defined).
-
setProperty(string
$propertyName
,
$propertyValue)
¶
Call this method to set a property or overwrite a previously one.
- Parameters
string $propertyName
- The property name to set. If the property does not exist in the model, an exception is thrown.
string|array|bool|AbstractType|null $propertyValue
- The value of the property to set. This can be a string, a boolean, another model or an array of strings, booleans or models. Also null is possible to clear the property value.
- Return value
- Reference to the model itself.
-
addProperty(string
$propertyName
,
$propertyValue)
¶
Call this method if you want to add a value to an existing one. In the example
above, you can see that addProperty()
is used to add a second value to
the sameAs
property.
Calling the addProperty()
method on a property that has no value assigned
has the same effect as calling setProperty()
. So you can safely use it,
e.g. in a loop, to set some values on a property.
- Parameters
string $propertyName
- The property name to set. If the property does not exist in the model, an exception is thrown.
string|array|bool|AbstractType|null $propertyValue
- The value of the property to set. This can be a string, a boolean, another model or an array of strings, booleans or models. Also null is possible to clear the property value.
- Return value
- Reference to the model itself.
-
setProperties(array
$properties)
¶
Set multiple properties at once.
- Parameter
array $properties
- The properties to set. The key of the array is the property name, the
value is the property value. Allowed as values are the same as with the
method
->setProperty()
.
- Return value
- Reference to the model itself.
-
getProperty(string
$propertyName)
¶
Get the value of a property.
- Parameter
string $propertyName
- The property name to get the value from. If the property name does not exist in the model, an exception is thrown.
- Return value
- The value of the property (string, bool, model, array of strings, array of models, null).
-
hasProperty(string
$propertyName)
¶
Check whether the property name exists in a particular model.
- Parameter
string $propertyName
- The property name to check.
- Return value
true
, if the property exists andfalse
, otherwise.
-
clearProperty(string
$propertyName)
¶
Resets the value of the property (set it to null
).
- Parameter
string $propertyName
- The property name to set. If the property does not exist in the model, an exception is thrown.
- Return value
- Reference to the model itself.
-
getPropertyNames()
¶
Get the names of all properties of the model.
- Return value
- Array of all property names of the model.
Schema Manager¶
The Schema Manager (class Brotkrueml\Schema\Manager\SchemaManager
) –
well – manages the type models and prepares them for embedding into the web
page.
The class exposes the following methods:
-
addType(TypeInterface
$type)
¶
Adds the given type model to the Schema Manager for inclusion on the web page.
- Parameter
TypeInterface $type
- The type model class with the set properties. This can be also
“special” types, like a
WebPage
or aBreadcrumbList
.
- Return value
- Reference to itself.
-
hasWebPage()
¶
Checks, if a web page type is already available.
- Parameter
- none
- Return value
true
, if a web page type is available, otherwisefalse
-
addMainEntityOfWebPage(TypeInterface
$mainEntity)
¶
Adds a main entity to the web page.
- Parameter
TypeInterface $mainEntity
- The type model to be added.
- Return value
- Reference to itself.
Other useful APIs¶
Boolean data type¶
Boolean property values are mapped to the according schema terms
http://schema.org/True
or http://schema.org/False
. You can also use
the Brotkrueml\Schema\Model\DataType\Boolean
class yourself. It exposes
two public constants:
-
FALSE
¶
Provides the value http://schema.org/False
.
-
TRUE
¶
Provides the value http://schema.org/True
.
and one static method:
-
convertToTerm(bool
$value): string
¶
This method returns the according schema term.
List of types¶
If you need a list of the available types or a subset of them, you can call
methods on the Brotkrueml\Schema\Type\TypeRegistry
class. As this is
a singleton, instantiate the class with:
$typeRegistry = GeneralUtility::makeInstance(\Brotkrueml\Schema\Type\TypeRegistry::class);
or use dependency injection in TYPO3 v10+.
-
getTypes()
¶
Get all available type names.
- Parameter
- none
- Return value
- Array, sorted alphabetically by type name.
-
getWebPageTypes()
¶
Get the WebPage type and its descendants.
- Parameter
- none
- Return value
- Array, sorted alphabetically by type name.
-
getWebPageElementTypes()
¶
Get the WebPageElement type and its descendants.
- Parameter
- none
- Return value
- Array, sorted alphabetically by type name.
-
getContentTypes()
¶
The types useful for an editor are returned as an array, sorted alphabetically.
The following types are filtered out:
BreadcrumbList
WebPage
and descendantsWebPageElement
and descendantsWebSite
- Parameter
- none
- Return value
- Array, sorted alphabetically by type name.