diff --git a/docs/ai/ai_actions/configure_ai_actions.md b/docs/ai/ai_actions/configure_ai_actions.md index 7222b52130..2dc910441c 100644 --- a/docs/ai/ai_actions/configure_ai_actions.md +++ b/docs/ai/ai_actions/configure_ai_actions.md @@ -22,7 +22,6 @@ Only then you can restart you application and start [working with the AI Actions The default OpenAI or the optional Google Gemini connectors can used by the [Taxonomy suggestions](taxonomy.md#taxonomy-suggestions) feature to generate embeddings for suggesting tags and product categories. After you configure the OpenAI connector, or set up the optional Google Gemini connector and [modify the default taxonomy suggestions settings](taxonomy.md#change-embeddings-provider-to-google-gemini), you can [create AI actions that use the Text to Taxonomy action type]([[= user_doc =]]/ai_actions/work_with_ai_actions/#create-ai-actions-that-control-taxonomy-suggestions). - You can also create [your own embedding provider](taxonomy.md#replace-the-embedding-provider). ## Configure access to OpenAI diff --git a/docs/content_management/content_api/browsing_content.md b/docs/content_management/content_api/browsing_content.md deleted file mode 100644 index 0d89a74fc4..0000000000 --- a/docs/content_management/content_api/browsing_content.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -description: Use PHP API to get content items and their information, content fields, location, and others. ---- - -# Browsing and viewing content - -To retrieve a content item and its information, you need to make use of the `ContentService`. - -The service should be [injected into the constructor of your command or controller]([[= symfony_doc =]]/service_container.html). - -!!! tip "Content REST API" - - To learn how to load content items using the REST API, see [REST API reference](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Objects/operation/api_contentobjects_contentId_get). - -!!! tip "Console commands" - - To learn more about commands in Symfony, refer to [Console Commands]([[= symfony_doc =]]/console.html). - -## Viewing content metadata - -### ContentInfo - -Basic content metadata is available through `ContentInfo` objects and their properties. -This value object provides primitive fields, such as `contentTypeId`, `publishedDate`, or `mainLocationId`, and methods for retrieving selected properties. - -You can also use it to request other content-related value objects from various services: - -``` php hl_lines="13" -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 1, 5) =]] - -// … -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 24, 25) =]] - // … -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 45, 46) =]] -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 53, 60) =]] -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 119) =]] -``` - -`ContentInfo` is loaded from the `ContentService` (line 13). -It provides you with basic content metadata such as modification and publication dates or main language code. - -!!! note "Retrieving content information in a controller" - - To retrieve content information in a controller, you also make use of the `ContentService`, but rendering specific elements (for example, content information or field values) is relegated to templates. - -### Locations - -To get the locations of a content item you need to make use of the `LocationService`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 63, 66, remove_indent=True) =]] -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 69, 69, remove_indent=True) =]] -``` - -`LocationService::loadLocations` uses `ContentInfo` to get all the locations of a content item. -This method returns an array of `Location` value objects. -For each location, the code above prints out its `pathString` (the internal representation of the path). - -#### URL Aliases - -The `URLAliasService` additionally enables you to retrieve the human-readable [URL alias](url_management.md#url-aliases) of each location. - -`URLAliasService::reverseLookup` gets the location's main URL alias: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 63, 65, remove_indent=True) =]] -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 67, 69, remove_indent=True) =]] -``` - -### Content type - -You can retrieve the content type of a content item through the `getContentType` method of the ContentInfo object: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 72, 73, remove_indent=True) =]] -``` - -### Versions - -To iterate over the versions of a content item, use the `ContentService::loadVersions` method, which returns an array of `VersionInfo` value objects. - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 76, 81, remove_indent=True) =]] -``` - -You can additionally provide the `loadVersions` method with the version status to get only versions of a specific status, for example: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 83, 83, remove_indent=True) =]] -``` - -!!! note - - Requesting version data may be impossible for an anonymous user. - Make sure to authenticate as a user with sufficient permissions. - -### Relations - -Content Relations are versioned. -To list Relations to and from your content, you can: - -- pass a `VersionInfo` object to the `ContentService::loadRelationList` method which returns a slice of the relation list thanks to pagination arguments -- use the `RelationListIteratorAdapter` - within a `BatchIterator` which allow traversing the whole relation list - -See [Processing large result sets](search_api.md#process-large-result-sets) for more information about the `BatchIterator`. - -You can get the current version's `VersionInfo` using `ContentService::loadVersionInfo`. - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 95, 105, remove_indent=True) =]] -``` - -You can also specify the version number as the second argument to get Relations for a specific version: - -``` php -/** - * @var \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo - * @var \Ibexa\Contracts\Core\Repository\ContentService $contentService - */ -$versionInfo = $contentService->loadVersionInfo($contentInfo, 2); -``` - -`loadRelationList` provides an iterable `RelationList` object -listing `Relation` objects. -`Relation` has two main properties: `destinationContentInfo`, and `sourceContentInfo`. -It also holds the [relation type](content_relations.md), and the optional field this relation is made with. - -### Owning user - -You can use the `getOwner` method of the `ContentInfo` object to load the content item's owner as a `User` value object. - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 108, 108, remove_indent=True) =]] -``` - -To get the creator of the current version and not the content item's owner, you need to use the `creatorId` property from the current version's `VersionInfo` object. - -### Section - -You can find the section to which a content item belongs through the `getSection` method of the ContentInfo object: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 111, 111, remove_indent=True) =]] -``` - -!!! note - - Requesting section data may be impossible for an anonymous user. - Make sure to authenticate as a user with sufficient permissions. - -### Object states - -You can retrieve [object states](object_states.md) of a content item using `ObjectStateService::getContentState`. -You need to provide it with the object state group. -All object state groups can be retrieved through `loadObjectStateGroups`. - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 114, 118, remove_indent=True) =]] -``` - -## Viewing field definitions of content types - -To retrieve the content type's field definitions of a selected content item, you can use the following command: - -``` php hl_lines="17-18 20-27" -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentCommand.php', 1, 7) =]] - -// … -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentCommand.php', 18, 19) =]] - // … -[[= include_code('code_samples/api/public_php_api/src/Command/ViewContentCommand.php', 36) =]] -``` - -Line 17 shows how `ContentService::loadContent` loads the content item provided to the command. -Line 18 makes use of the `ContentTypeService` to retrieve the content type of the requested item. - -Lines 20-27 iterate over fields defined by the content type. -For each field definition they print out its identifier, and then using `FieldTypeService` retrieve the field definition's value and print it out to the console. - -## Viewing content in different languages - -The repository is SiteAccess-aware, so languages defined by the SiteAccess are automatically taken into account when loading content. - -To load a specific language, provide its language code when loading the content item: - -``` php -/** - * @var int $contentId - * @var \Ibexa\Contracts\Core\Repository\ContentService $contentService - */ -$content = $contentService->loadContent($contentId, ['ger-DE']); -``` - -To load all languages as a prioritized list, use `Language::ALL`: - -``` php -use Ibexa\Contracts\Core\Repository\Values\Content\Language; - -/** - * @var \Ibexa\Contracts\Core\Repository\ContentService $contentService - * @var \Ibexa\Contracts\Core\Repository\Values\Content\Content $content - */ -$contentService->loadContent($content->id, Language::ALL); -``` - -## Getting all content in a subtree - -To go through all the content items contained in a subtree, you need to use the `LocationService`. - -``` php hl_lines="5 15" -[[= include_code('code_samples/api/public_php_api/src/Command/BrowseLocationsCommand.php', 32, 50, remove_indent=True) =]] -``` - -`loadLocation` (line 15) returns a value object, here a `Location`. - -`LocationService::loadLocationChildren` (line 5) returns a `LocationList` value object that you can iterate over. - -!!! note - - Refer to [Searching](search_api.md) for information on more complex search queries. - -## Getting parent location - -To get the parent location of content, you first need to determine which location is the main one, in case the content item has multiple locations. -You can do it through the `getMainLocation` method of the ContentInfo object. - -Next, use the `getParentLocation` method of the location object to access the parent location: - -``` php -/** @var \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo */ -$mainLocation = $contentInfo->getMainLocation(); -$parentLocation = $mainLocation?->getParentLocation(); -if ($parentLocation !== null) { - $message = 'Parent Location: ' . $parentLocation->pathString; -} -``` - -## Getting content from a location - -When dealing with location objects (and Trash objects), you can get access to content item directly using `$location->getContent`. -In Twig this can also be accessed by `location.content`. -This is a lazy property. -It triggers loading of content when first used. -In case of bulk of locations coming from Search or location Service, the content is also loaded in bulk for the whole location result set. - -## Comparing content versions - -You can compare two versions of a content item using the `VersionComparisonService`. -The versions must have the same language. - -For example, to get the comparison between the `name` field of two versions: - -``` php -/** - * @var \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo - * @var int $versionFromId - * @var int $versionToId - * @var \Ibexa\Contracts\Core\Repository\ContentService $contentService - * @var \Ibexa\Contracts\VersionComparison\Service\VersionComparisonServiceInterface $comparisonService - */ -$versionFrom = $contentService->loadVersionInfo($contentInfo, $versionFromId); -$versionTo = $contentService->loadVersionInfo($contentInfo, $versionToId); - -$nameComparison = $comparisonService->compare($versionFrom, $versionTo)->getFieldValueDiffByIdentifier('name')->getComparisonResult(); -``` - -`getComparisonResult` returns a `ComparisonResult` object, which depends on the field type being compared. -In the example of a Text Line (ibexa_string) field, it's an array of `StringDiff` objects. - -Each diff contains a section of the field to compare (for example, a part of a text line) and its status, which can be "unchanged", "added" or "removed". diff --git a/docs/content_management/content_api/creating_content.md b/docs/content_management/content_api/creating_content.md deleted file mode 100644 index bc43b77d83..0000000000 --- a/docs/content_management/content_api/creating_content.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -description: Create, publish, update and translate content items by using the PHP API. ---- - -# Creating content - -!!! note - - Creating most objects is impossible for an anonymous user. - Make sure to authenticate as a user with sufficient permissions. - -!!! tip "Content REST API" - - To learn how to create content items using the REST API, see [REST API reference](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Objects/operation/api_contentobjects_post). - -## Creating content item draft - -Value objects such as content items are read-only, so to create or modify them you need to use structs. - -`ContentService::newContentCreateStruct` -returns a new `ContentCreateStruct` object. - -``` php hl_lines="2-3 7" -[[= include_code('code_samples/api/public_php_api/src/Command/CreateContentCommand.php', 52, 60, remove_indent=True) =]] -``` - -This command creates a draft using `ContentService::createContent` (line 6). -This method must receive a `ContentCreateStruct` and an array of location structs. - -`ContentCreateStruct` (which extends `ContentStruct`) is created through `ContentService::newContentCreateStruct` (line 1), -which receives the content type and the primary language for the content item. -For information about translating a content item into other languages, see [Translating content](#translating-content). - -`ContentStruct::setField` (line 2) enables you to define the field values. -When the field accepts a simple value, you can provide it directly, as in the example above. -For some field types, for example [images](#creating-an-image), you need to provide an instance of a Value type. - -### Creating an image - -Image field type requires an instance of its Value type, which you must provide to the `ContentStruct::setField` method. -Therefore, when creating a content item of the Image type (or any other content type with an `image` field type), -the `ContentCreateStruct` is slightly more complex than in the previous example: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/CreateImageCommand.php', 52, 63, remove_indent=True) =]] -``` - -Value of the Image field type contains the path to the image file and other basic information based on the input file. - -### Creating content with RichText - -The RichText field accepts values in a custom flavor of [DocBook](https://github.com/docbook/wiki/wiki) format. -For example, to add a RichText paragraph, provide the following as input: - -``` xml -
Description of your content item.
-``` - -To learn more about the format and how it represents different elements of rich text, see -[RichText field type reference](richtextfield.md#custom-docbook-format). - -## Publishing a draft - -`ContentService::createContent` creates a content item with only one draft version. -To publish it, use `ContentService::publishVersion`. -This method must get the `VersionInfo` object of a draft version. - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/CreateContentCommand.php', 63, 63, remove_indent=True) =]] -``` - -## Updating content - -To update an existing content item, you need to prepare a `ContentUpdateStruct` -and pass it to `ContentService::updateContent`. -This method works on a draft, so to publish your changes you need to use `ContentService::publishVersion` as well: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/UpdateContentCommand.php', 45, 53, remove_indent=True) =]] -``` - -## Translating content - -Content [translations](languages.md#language-versions) are created per version. By default every version contains all existing translations. - -To translate a content item to a new language, you need to update it and provide a new `initialLanguageCode`: - -``` php -[[= include_file('code_samples/api/public_php_api/src/Command/TranslateContentCommand.php', 49, 55) =]] - -[[= include_file('code_samples/api/public_php_api/src/Command/TranslateContentCommand.php', 60, 62) =]] -``` - -You can also update content in multiple languages at once using the `setField` method's third argument. -Only one language can still be set as a version's initial language: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/TranslateContentCommand.php', 58, 58, remove_indent=True) =]] -``` - -### Deleting a translation - -You can delete a single translation from a content item's version using `ContentService::deleteTranslationFromDraft`. -The method must be provided with a `VersionInfo` object and the code of the language to delete: - -``` php -/** @var \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo $versionInfo */ -$languageCode = 'ger-DE'; -/** @var \Ibexa\Contracts\Core\Repository\ContentService $contentService */ -$contentService->deleteTranslationFromDraft($versionInfo, $languageCode); -``` diff --git a/docs/content_management/content_api/managing_content.md b/docs/content_management/content_api/managing_content.md deleted file mode 100644 index 2956dab468..0000000000 --- a/docs/content_management/content_api/managing_content.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -description: PHP API enables managing content Locations, content types, content in Trash, and Calendar events. -month_change: false ---- - -# Managing content - -## Locations - -You can manage [locations](locations.md) that hold content using `LocationService`. - -!!! tip "Location REST API" - - To learn how to manage locations using the REST API, see [REST API reference](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Objects/operation/api_contentobjects_contentIdlocations_post). - -### Adding a new location to a content item - -Every published content item must have at least one location. -One content item can have more that one location, which means it's presented in more than one place in the content tree. - -Creating a new location, like creating content, requires using a struct, because a location value object is read-only. - -To add a new location to existing content you need to create a `LocationCreateStruct` and pass it to the `LocationService::createLocation` method: - -``` php -[[= include_file('code_samples/api/public_php_api/src/Command/AddLocationToContentCommand.php', 46, 47) =]] -[[= include_file('code_samples/api/public_php_api/src/Command/AddLocationToContentCommand.php', 51, 53) =]] -``` - -`LocationCreateStruct` must receive the parent location ID. -It sets the `parentLocationId` property of the new location. - -You can also provide other properties for the location, otherwise they're set to their defaults: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/AddLocationToContentCommand.php', 49, 50, remove_indent=True) =]] -``` - -### Changing the main location - -When a content item has more that one location, one location is always considered the main one. -You can change the main location using `ContentService`, by updating the `ContentInfo` with a `ContentUpdateStruct` that sets the new main location: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/SetMainLocationCommand.php', 47, 51, remove_indent=True) =]] -``` - -### Hiding and revealing locations - -To hide or reveal (unhide) a location you need to make use of `LocationService::hideLocation` or `LocationService::unhideLocation`: - -``` php -[[= include_file('code_samples/api/public_php_api/src/Command/HideLocationCommand.php', 44, 45) =]] -[[= include_file('code_samples/api/public_php_api/src/Command/HideLocationCommand.php', 47, 48) =]] -``` - -See [location visibility](locations.md#location-visibility) for detailed information on the behavior of visible and hidden Locations. - -### Deleting a location - -You can remove a location either by deleting it, or sending it to Trash. - -Deleting makes use of `LocationService::deleteLocation()`. -It permanently deletes the location, together with its whole subtree. - -Content which has only this one location is permanently deleted as well. -Content which has more locations is still available in its other locations. -If you delete the [main location](#changing-the-main-location) of a content item that has more locations, another location becomes the main one. - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/DeleteContentCommand.php', 41, 43, remove_indent=True) =]] -``` - -To send the location and its subtree to Trash, use `TrashService::trash`. -Items in Trash can be later [restored, or deleted permanently](#trash). - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/TrashContentCommand.php', 51, 51, remove_indent=True) =]] -``` - -### Moving and copying a subtree - -You can move a location with its whole subtree using `LocationService::moveSubtree`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/MoveContentCommand.php', 45, 47, remove_indent=True) =]] -``` - -`LocationService::copySubtree` is used in the same way, but it copies the location and its subtree instead of moving it. - -!!! tip - - To copy a subtree you can also make use of the built-in `copy-subtree` command: `bin/console ibexa:copy-subtree `. - -!!! note - - [Copy subtree limit](back_office_configuration.md#copy-subtree-limit) only applies to operations in the back office. - It's ignored when copying subtrees using the PHP API. - -## Trash - -!!! tip "Trash REST API" - - To learn how to manage Trash using the REST API, see [REST API reference](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Trash). - -To empty the Trash (remove all locations in Trash), use `TrashService::emptyTrash`, which takes no arguments. - -You can recover an item from Trash using `TrashService::recover`. -You must provide the method with the ID of the object in Trash. -Trash location is identical to the origin location of the object. - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/TrashContentCommand.php', 61, 61, remove_indent=True) =]] -``` - -The content item is restored under its previous location. -You can also provide a different location to restore in as a second argument: - -``` php -/** - * @var \Ibexa\Contracts\Core\Repository\Values\Content\TrashItem $trashItem - * @var \Ibexa\Contracts\Core\Repository\LocationService $locationService - * @var \Ibexa\Contracts\Core\Repository\TrashService $trashService - */ -$locationId = 12345; -$newParent = $locationService->loadLocation($locationId); -$trashService->recover($trashItem, $newParent); -``` - -You can also search through Trash items and sort the results using several public PHP API Search Criteria and Sort Clauses that have been exposed for `TrashService` queries. -For more information, see [Search in trash](search_api.md#search-in-trash). - -## Content types - -!!! tip "Content type REST API" - - To learn how to manage content types using the REST API, see REST API reference for [content types](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Type) and [content type groups](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Type-Groups). - -### Adding content types - -To operate on content types, you need to make use of `ContentTypeService`. - -Adding a new content type, like creating content, must happen with the use of a struct, because a content type value object is read-only. -In this case you use `ContentTypeCreateStruct`. - -A content type must have at least one name, in the main language, and at least one field definition. - -``` php -[[= include_file('code_samples/api/public_php_api/src/Command/CreateContentTypeCommand.php', 56, 66) =]][[= include_file('code_samples/api/public_php_api/src/Command/CreateContentTypeCommand.php', 73, 82) =]] - -``` - -You can specify more details of the field definition in the create struct, for example: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/CreateContentTypeCommand.php', 65, 74, remove_indent=True) =]] -``` - -### Copying content types - -To copy a content type, use `ContentTypeService::copyContentType`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/CreateContentTypeCommand.php', 86, 88, remove_indent=True) =]] -``` - -The copy is automatically getting an identifier based on the original content type identifier and the copy's ID, for example: `copy_of_folder_21`. - -To change the identifier of the copy, use a `ContentTypeUpdateStruct`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/CreateContentTypeCommand.php', 88, 93, remove_indent=True) =]] -``` - -### Finding and filtering content types - -You can find content types that match specific criteria by using the `ContentTypeService::findContentTypes()` method. -This method accepts a `ContentTypeQuery` object that supports filtering and sorting by IDs, identifiers, group membership, and other criteria. - -!!! note "Criteria, sort clauses and REST APIs" - - For a full list of available criteria and sort clauses that you can use when finding and filtering content types, see [Content Type Search Criteria](content_type_criteria.md) and [Content Type Search Sort Clauses](content_type_sort_clauses.md) references. - - For the REST API, see [Filter content types](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Type/operation/api_contenttypesview_post). - -The following example shows how you can use the criteria to find content types: - -``` php hl_lines="28-38" -[[= include_code('code_samples/api/public_php_api/src/Command/FindContentTypeCommand.php') =]] -``` - -#### Query parameters - -When constructing a `ContentTypeQuery`, you can pass the following parameters: - -- `?CriterionInterface $criterion = null` — a filter to apply (use one or a combination of the criteria above) - -- `array $sortClauses = []` — list of sort clauses to order the results - -- `int $offset = 0` — starting offset (for pagination) - -- `int $limit = 25` — maximum number of results to return - -## Calendar events - -You can handle the calendar using `CalendarServiceInterface` (`Ibexa\Contracts\Calendar\CalendarServiceInterface`). - -!!! tip "Calendar REST API" - - To learn how to manage the Calendar using the REST API, see [REST API reference](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Calendar). - -### Getting events - -To get a list of events for a specified time period, use the `CalendarServiceInterface::getEvents` method. -You need to provide the method with an EventQuery, which takes a date range and a count as the minimum of parameters: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/CalendarCommand.php', 34, 44, remove_indent=True) =]] -``` - -You can also get the first and last event in the list by using the `first()` and `last()` methods of an `EventCollection` (`Ibexa\Contracts\Calendar\EventCollection`): - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/CalendarCommand.php', 46, 47, remove_indent=True) =]] -``` - -You can process the events in a collection using the `find(Closure $predicate)`, `filter(Closure $predicate)`, `map(Closure $callback)` or `slice(int $offset, ?int $length = null)` methods of `EventCollection`, for example: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/CalendarCommand.php', 49, 52, remove_indent=True) =]] -``` - -### Performing calendar actions - -You can perform a calendar action (for example, reschedule or unschedule calendar events) using the `CalendarServiceInterface::executeAction()` method. -You must pass an `Ibexa\Contracts\Calendar\EventAction\EventActionContext` instance as argument. -`EventActionContext` defines events on which the action is performed, and action-specific parameters, for example, a new date: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/CalendarCommand.php', 54, 57, remove_indent=True) =]] -``` diff --git a/docs/content_management/content_availability.md b/docs/content_management/content_availability.md index 9aaef5efe6..16cc887b32 100644 --- a/docs/content_management/content_availability.md +++ b/docs/content_management/content_availability.md @@ -21,8 +21,6 @@ corresponding to the current SiteAccess. There is currently no way in the back office to edit the Content availability flag for an already published content item. - - To do this via [PHP API](creating_content.md#updating-content), set the `alwaysAvailable` property of the Content metadata. The Default availability flag is used for the out-of-the box content types representing content that should always be visible to the user, such as media files or user content items. diff --git a/docs/content_management/content_management_api/bookmark_api.md b/docs/content_management/content_management_api/bookmark_api.md deleted file mode 100644 index dd50fe02ed..0000000000 --- a/docs/content_management/content_management_api/bookmark_api.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: You can use the PHP API to view the bookmark list, and add or remove content from it. ---- - -# Bookmark API - -`BookmarkService` enables you to read, add and remove bookmarks from content. - -!!! tip "Bookmark REST API" - - To learn how to manage bookmarks using the REST API, see [REST API reference](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Bookmark). - -To view a list of all bookmarks, use `BookmarkService::loadBookmarks`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/BookmarkCommand.php', 44, 50, remove_indent=True) =]] -``` - -You can add a bookmark to a content item by providing its Location object to the `BookmarkService::createBookmark` method: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/BookmarkCommand.php', 38, 40, remove_indent=True) =]] -``` - -You can remove a bookmark from a location with `BookmarkService::deleteBookmark`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/BookmarkCommand.php', 53, 53, remove_indent=True) =]] -``` diff --git a/docs/content_management/content_management_api/object_state_api.md b/docs/content_management/content_management_api/object_state_api.md deleted file mode 100644 index 5153f536af..0000000000 --- a/docs/content_management/content_management_api/object_state_api.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -description: You can manage object states via the PHP API, including creating object states and state groups and assigning them to content items. ---- - -# Object state API - -[Object states](object_states.md) enable you to set a custom state to any content. -States are grouped into object state groups. - -You can manage Object states by using the PHP API by using `ObjectStateService`. - -!!! tip "Object state REST API" - - To learn how to manage object states using the REST API, see [REST API reference](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Objects/operation/api_contentobjects_contentIdobjectstates_get). - -## Getting object state information - -You can use the `ObjectStateService` to get information about object state groups or object states. - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ObjectStateCommand.php', 45, 49, remove_indent=True) =]] -``` - -## Creating object states - -To create an object state group and add object states to it, you need to make use of the `ObjectStateService`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ObjectStateCommand.php', 54, 57, remove_indent=True) =]] -``` - -`ObjectStateService::createObjectStateGroup` takes as argument an `ObjectStateGroupCreateStruct`, in which you need to specify the identifier, default language and at least one name for the group. - -To create an object state inside a group, use `ObjectStateService::newObjectStateCreateStruct` and provide it with an `ObjectStateCreateStruct`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ObjectStateCommand.php', 60, 63, remove_indent=True) =]] -``` - -## Assigning object state - -To assign an object state to a content item, use `ObjectStateService::setContentState`. -Provide it with a `ContentInfo` object of the content item, the object state group and the object state: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/ObjectStateCommand.php', 74, 78, remove_indent=True) =]] -``` diff --git a/docs/content_management/content_management_api/section_api.md b/docs/content_management/content_management_api/section_api.md deleted file mode 100644 index fc88c8198e..0000000000 --- a/docs/content_management/content_management_api/section_api.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -description: PHP API enables you to create sections, assign content to them, and get various information about the section. ---- - -# Section API - -[Sections](sections.md) enable you to divide content into groups which can later be used, for example, as basis for permissions. - -You can manage sections by using the PHP API by using `SectionService`. - -!!! tip "Section REST API" - - To learn how to manage sections using the REST API, see [REST API reference](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Section). - -## Creating sections - -To create a new section, you need to make use of the `SectionCreateStruct` and pass it to the `SectionService::createSection` method: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/SectionCommand.php', 53, 56, remove_indent=True) =]] -``` - -## Getting section information - -You can use `SectionService` to retrieve section information such as whether it's in use: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/SectionCommand.php', 71, 75, remove_indent=True) =]] -``` - -## Listing content in a section - -To list content items assigned to a section you need to make a [query](search_api.md) for content belonging to this section, by applying the `SearchService`. -You can also use the query to get the total number of assigned content items: - -``` php -[[= include_file('code_samples/api/public_php_api/src/Command/SectionCommand.php', 63, 69) =]] -[[= include_file('code_samples/api/public_php_api/src/Command/SectionCommand.php', 77, 80) =]] - -``` - -## Assigning section to content - -To assign content to a section, use the `SectionService::assignSection` method. -You need to provide it with the `ContentInfo` object of the content item, and the `Section` object: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/SectionCommand.php', 59, 61, remove_indent=True) =]] -``` - -Assigning a section to content doesn't automatically assign it to the content item's children. diff --git a/docs/content_management/field_types/field_type_reference/addressfield.md b/docs/content_management/field_types/field_type_reference/addressfield.md index 94d7af2311..9b0e82b76d 100644 --- a/docs/content_management/field_types/field_type_reference/addressfield.md +++ b/docs/content_management/field_types/field_type_reference/addressfield.md @@ -10,9 +10,7 @@ It allows you to customize address fields per country. The Address field type is available via the Address Bundle provided by the `ibexa/fieldtype-address` package. -## PHP API field type - -### Inputs +## Inputs | Type | Description | Example | |----------|-----------------------------------------------|-------------------| @@ -20,29 +18,11 @@ provided by the `ibexa/fieldtype-address` package. | `string` | Country code in ISO 3166-1 alpha-2 format. | `PL` | | `array` | Additional fields, defined by address format. | see below | -### Example input - -``` php -use Ibexa\FieldTypeAddress\FieldType; - -new FieldType\Value( - 'My home address', - 'PL', - [ - 'city' => 'Warsaw', - 'region' => 'Masovian', - 'postal_code' => '11-123', - ] -); -``` - -### Validation +## Validation This field type validates whether `Country` and `Name` fields have been filled out. -### Value object - -#### Properties +### Properties | Property | Type | Description | |------------|----------|-----------------------------------------------| @@ -50,11 +30,7 @@ This field type validates whether `Country` and `Name` fields have been filled o | `$country` | `string` | Country code in ISO 3166-1 alpha-2 format. | | `$fields` | `array` | Additional fields, defined by address format. | -#### Constructor - -See above (Example input). - -### Formats +## Formats The following default configuration defines default fields for `personal` address type: @@ -69,7 +45,7 @@ formats: - postal_code ``` -#### Modifying field configuration +### Modifying field configuration ```yaml formats: @@ -84,7 +60,7 @@ formats: Adds (or alters) an address format for `DE` country of `billing_address` type. -### Field form types +## Field form types By default, each field is a simple text input with a label made of field identifier. To change the type of field, you need to listen to a specific event. @@ -96,42 +72,10 @@ ibexa.address.field.{FIELD_IDENTIFIER}.{ADDRESS_TYPE} ibexa.address.field.{FIELD_IDENTIFIER}.{ADDRESS_TYPE}.{COUNTRY_CODE} ``` -#### Example +### Example ```yaml ibexa.address.field.tax_number ibexa.address.field.tax_number.billing_address ibexa.address.field.tax_number.billing_address.DE ``` - -#### Example event listener - -An event listener can also provide validation by using either one of [constraints provided by Symfony]([[= symfony_doc =]]/validation.html#supported-constraints), -or a custom constraint. - -``` php -use Ibexa\Contracts\FieldTypeAddress\Event\MapFieldEvent; -use Symfony\Component\EventDispatcher\EventSubscriberInterface; -use Symfony\Component\Form\Extension\Core\Type\IntegerType; -use Symfony\Component\Validator\Constraints\Positive; - -class ExampleAddressSubscriber implements EventSubscriberInterface -{ - public static function getSubscribedEvents(): array - { - return [ - 'ibexa.address.field.tax_number.billing_address' => 'onBillingAddressTaxNumber', - ]; - } - - public function onBillingAddressTaxNumber(MapFieldEvent $event): void - { - $event->setLabel('VAT'); - $event->setType(IntegerType::class); - $event->setOptions([ - 'attr' => ['class' => 'some-tax-number'], - 'constraints' => [new Positive()], - ]); - } -} -``` diff --git a/docs/content_management/field_types/field_type_reference/authorfield.md b/docs/content_management/field_types/field_type_reference/authorfield.md index e43d8432e3..75953aaf2e 100644 --- a/docs/content_management/field_types/field_type_reference/authorfield.md +++ b/docs/content_management/field_types/field_type_reference/authorfield.md @@ -6,11 +6,7 @@ This field type allows the storage and retrieval of one or more authors. For eac |----------|----------------|----------------|----------| | `Author` | `ibexa_author` | mixed | `string` | -## PHP API field type - -### Value object - -#### Properties +## Properties | Attribute | Type | Description | Example | |-----------|------------------------------------------|------------------|-----------| @@ -18,55 +14,17 @@ This field type allows the storage and retrieval of one or more authors. For eac Example: -``` php -use Ibexa\Core\FieldType\Author; - -$authorList = new Author\Value([ - new Author\Author([ - 'id' => 1, - 'name' => 'Boba Fett', - 'email' => 'boba.fett@example.com', - ]), - new Author\Author([ - 'id' => 2, - 'name' => 'Darth Vader', - 'email' => 'darth.vader@example.com', - ]), -]); -``` - -#### Hash format +## Hash format The hash format mostly matches the value object. It has the following key `authors`. Example -``` php -[ - [ - 'id' => 1, - 'name' => 'Boba Fett', - 'email' => 'boba.fett@example.com', - ], - [ - 'id' => 2, - 'name' => 'Darth Vader', - 'email' => 'darth.vader@example.com', - ], -]; -``` - -#### String representation - -The string contains all the authors with their names and emails. - -Example: `John Doe john@doe.com` - -### Validation +## Validation This field type doesn't perform any special validation of the input value. -### Settings +## Settings The Field definition of this field type can be configured with a single option: @@ -80,13 +38,3 @@ Following `defaultAuthor` default value options are available as constants in |------------------------|-------------------------------------------| | `DEFAULT_VALUE_EMPTY` | Default value is empty. | | `DEFAULT_CURRENT_USER` | Default value uses currently logged user. | - -``` php -// Author field type example settings - -use Ibexa\Core\FieldType\Author\Type; - -$settings = [ - 'defaultAuthor' => Type::DEFAULT_VALUE_EMPTY, -]; -``` diff --git a/docs/content_management/field_types/field_type_reference/binaryfilefield.md b/docs/content_management/field_types/field_type_reference/binaryfilefield.md index 0eba44174e..6221805fe3 100644 --- a/docs/content_management/field_types/field_type_reference/binaryfilefield.md +++ b/docs/content_management/field_types/field_type_reference/binaryfilefield.md @@ -9,11 +9,7 @@ The maximum allowed file size is determined by the "Max file size" class attribu |--------------|--------------------|----------------|---------| | `BinaryFile` | `ibexa_binaryfile` | mixed | mixed | -## PHP API field type - -### Value object - -#### Properties +## Properties Both `BinaryFile` and `Media` Value and Type inherit from the `BinaryBase` abstract field type, and share common properties. @@ -29,36 +25,6 @@ Both `BinaryFile` and `Media` Value and Type inherit from the `BinaryBase` abstr | `downloadCount` | integer | Number of times the file was downloaded | 0 | | `inputUri` | string | Path to a local file when creating a field value, `null` when reading a field value | `path/to/document.pdf` | -#### Constructor's hash format - -The hash format mostly matches the value object. It has the following keys: - -| Key | Status | Type | Description | -|-----------------|------------|---------|------------------------------------------------------------------------------------------| -| `inputUri` | mandatory | string | Path to the local file to be uploaded into the field. | -| `id` | deprecated | string | Backward compatibility alias for `inputUri`. | -| `path` | deprecated | string | Backward compatibility alias for `inputUri`. | -| `fileName` | optional | string | Name of the file when downloaded. If not given, the basename of `inputUri` is used | -| `fileSize` | optional | integer | Size of the file in bytes. If not given, the size of the `inputUri` target file is used. | -| `downloadCount` | optional | integer | Number of times the file was downloaded. If not given, set to `0` (zero). | -| `mimeType` | ignored | | | -| `uri` | ignored | | | - -Example: - -``` php -/** @var \Ibexa\Contracts\Core\Repository\Values\Content\ContentCreateStruct $fileContentCreateStruct */ -$fileContentCreateStruct->setField('file', new Ibexa\Core\FieldType\BinaryFile\Value([ - 'fileName' => 'example.pdf', - 'inputUri' => '/tmp/example_for_website.pdf', -])); -``` - -The original local file name `example_for_website.pdf` is forgotten. -When downloaded, the filename is `example.pdf`. - -To use a remote file, you have to download it locally first, then remove it after it's used in `ContentService::createContent`. - ## REST API specifics Used in the REST API, a BinaryFile field mostly serializes the hash described above. However there are a couple specifics worth mentioning. diff --git a/docs/content_management/field_types/field_type_reference/checkboxfield.md b/docs/content_management/field_types/field_type_reference/checkboxfield.md index b5d673b004..b5247c97b8 100644 --- a/docs/content_management/field_types/field_type_reference/checkboxfield.md +++ b/docs/content_management/field_types/field_type_reference/checkboxfield.md @@ -6,44 +6,10 @@ The Checkbox field type stores the current status for a checkbox input, checked |------------|-----------------|---------------------| | `Checkbox` | `ibexa_boolean` | `boolean` | -## PHP API field type - -### Value object - -#### Properties +## Properties The Value class of this field type contains the following properties: | Property | Type | Default value | Description | |----------|-----------|---------------|--------------------------------------------------------------------------------| | `$bool` | `boolean` | `false` | This property is used for the checkbox status, represented by a boolean value. | - -``` php -//Value object content examples -use Ibexa\Core\FieldType\Checkbox; - -// Instantiates a checkbox value with a default state (false) -$checkboxValue = new Checkbox\Value(); - -// Checked -$checkboxValue->bool = true; - -// Unchecked -$checkboxValue->bool = false; -``` - -##### Constructor - -The `Checkbox\Value` constructor accepts a boolean value: - -``` php -// Constructor example -use Ibexa\Core\FieldType\Checkbox; - -// Instantiates a checkbox value with a checked state -$checkboxValue = new Checkbox\Value(true); -``` - -##### String representation - -As this field type isn't a string but a boolean, it returns "1" (true) or "0" (false) in cases where it's cast to string, and it's never considered empty. diff --git a/docs/content_management/field_types/field_type_reference/countryfield.md b/docs/content_management/field_types/field_type_reference/countryfield.md index 7acea36ab3..8e918219ad 100644 --- a/docs/content_management/field_types/field_type_reference/countryfield.md +++ b/docs/content_management/field_types/field_type_reference/countryfield.md @@ -6,30 +6,17 @@ This field type represents one or multiple countries. |-----------|-----------------|----------------| | `Country` | `ibexa_country` | `array` | -## PHP API field type - -### Input expectations +## Input expectations Example array: -``` php -[ - 'JP' => [ - 'Name' => 'Japan', - 'Alpha2' => 'JP', - 'Alpha3' => 'JPN', - 'IDC' => 81, - ], -]; -``` - When you set an array directly on a content field you don't need to provide all this information, the field type assumes it's a hash and in this case accepts a simplified structure described below under [Hash format](#hash-format). -### Validation +## Validation This field type validates whether multiple countries are allowed by the field definition, and whether the [Alpha2](https://www.iso.org/iso-3166-country-codes.html) is valid according to the countries configured in [[= product_name =]]. -### Settings +## Settings The field definition of this field type can be configured with one option: @@ -37,67 +24,17 @@ The field definition of this field type can be configured with one option: |--------------|-----------|---------------|--------------------------------------------------------------------------------------------| | `isMultiple` | `boolean` | `false` | This setting allows (if true) or prohibits (if false) the selection of multiple countries. | -``` php -// Country FieldType example settings -$settings = [ - 'isMultiple' => true, -]; -``` - -### Hash format +## Hash format The format used for serialization is simpler than the full format. It's also available when setting value on the content field, by setting the value to an array instead of the value object. Example of that shown below: -``` php -// Value object content example -/** @var \Ibexa\Contracts\Core\Repository\Values\Content\Content $content */ -$content->fields['countries'] = ['JP', 'NO']; -``` - The format used by the toHash method is the Alpha2 value, however the input is capable of accepting either Name, Alpha2, or Alpha3 value as shown below in the value object section. -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: | Property | Type | Description | |--------------|-----------|---------------------------------------------------------------------------------------| | `$countries` | `array[]` | This property is used for the country selection provided as input, as its attributes. | - -``` php -// Value object content example -/** @var \Ibexa\Core\FieldType\Country\Value $value */ -$value->countries = [ - 'JP' => [ - 'Name' => 'Japan', - 'Alpha2' => 'JP', - 'Alpha3' => 'JPN', - 'IDC' => 81, - ], -]; -``` - -##### Constructor - -The `Country\Value` constructor initializes a new value object with the value provided. -It expects an array as input. - -``` php -// Constructor example -use Ibexa\Core\FieldType\Country as Country; - -// Instantiates a Country Value object -$countryValue = new Country\Value( - [ - 'JP' => [ - 'Name' => 'Japan', - 'Alpha2' => 'JP', - 'Alpha3' => 'JPN', - 'IDC' => 81, - ], - ] -); -``` diff --git a/docs/content_management/field_types/field_type_reference/customergroupfield.md b/docs/content_management/field_types/field_type_reference/customergroupfield.md index c2e2f4cfa3..9653fd6903 100644 --- a/docs/content_management/field_types/field_type_reference/customergroupfield.md +++ b/docs/content_management/field_types/field_type_reference/customergroupfield.md @@ -6,11 +6,7 @@ This field type represents a customer group that a user belongs to. |------------------|------------------------|---------------------| | `Customer group` | `ibexa_customer_group` | `int` or null | -## PHP API field type - -### Value object - -#### Properties +## Properties The Value class of this field type contains the following properties: diff --git a/docs/content_management/field_types/field_type_reference/dateandtimefield.md b/docs/content_management/field_types/field_type_reference/dateandtimefield.md index ad05e91a2d..5d480b4b7a 100644 --- a/docs/content_management/field_types/field_type_reference/dateandtimefield.md +++ b/docs/content_management/field_types/field_type_reference/dateandtimefield.md @@ -6,9 +6,7 @@ This field type represents a full date and time information. |---------------|-------------------|---------------------| | `DateAndTime` | `ibexa_datetime` | mixed | -## PHP API field type - -### Input expectations +## Input expectations If input value is of type `string` or `integer`, it's passed directly to the [PHP's built-in `\DateTime` class constructor](https://www.php.net/manual/en/datetime.construct.php), therefore the same input format expectations apply. @@ -20,9 +18,7 @@ It's also possible to directly pass an instance of `\DateTime`. | `integer` | `1346149200` | | `\DateTime` | `new \DateTime()` | -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: @@ -30,27 +26,7 @@ The Value class of this field type contains the following properties: |----------|-------------|------------| | `$value` | `\DateTime` | The date and time value as an instance of `\DateTime`. | -##### Constructor - -The constructor for this value object initializes a new value object with the value provided. It accepts an instance of PHP's built-in `\DateTime` class. - -##### String representation - -String representation of the date value generates the date string in the format `D Y-d-m H:i:s` as accepted by [PHP's built-in `date()` function](https://www.php.net/manual/en/function.date.php). - -| Character | Description | Example | -|-----------|---------------------------------------------------------------------|---------| -| D | Three letter representation of a day, range Mon to Sun | Wed | -| Y | Four digit representation of a year | 2016 | -| d | Two digit representation of a day, range 01 to 31 | 22 | -| m | Two digit representation of a month, range 01 to 12 | 05 | -| H | Two digit representation of an hour, 24-hour format, range 00 to 23 | 12 | -| i | Two digit representation of minutes, range 00 to 59 | 19 | -| s | Two digit representation of seconds, range 00 to 59 | 18 | - -Example: `Wed 2016-22-05 12:19:18` - -### Hash format +## Hash format Hash value of this field type is an array with two keys: @@ -59,18 +35,11 @@ Hash value of this field type is an array with two keys: | `timestamp` | `integer` | Time information in [Unix format timestamp](https://en.wikipedia.org/wiki/Unix_time). | `1400856992` | | `rfc850` | `string` | Time information as a string in [RFC 850 date format](https://datatracker.ietf.org/doc/html/rfc850). As input, this has precedence over the timestamp value. | `"Friday, 23-May-14 14:56:14 GMT+0000"` | -``` php -$hash = [ - 'timestamp' => 1400856992, - 'rfc850' => 'Friday, 23-May-14 14:56:14 GMT+0000', -]; -``` - -### Validation +## Validation This field type doesn't perform any special validation of the input value. -### Settings +## Settings The field definition of this field type can be configured with several options: @@ -87,22 +56,3 @@ Following `defaultType` default value options are available as constants in the | `DEFAULT_EMPTY` | Default value is empty. | | `DEFAULT_CURRENT_DATE` | Default value uses current date. | | `DEFAULT_CURRENT_DATE_ADJUSTED` | Default value uses current date, adjusted by the interval defined in `dateInterval` setting. | - -``` php -// DateAndTime FieldType example settings - -use Ibexa\Core\FieldType\DateAndTime\Type; - -$settings = [ - 'useSeconds' => false, - 'defaultType' => Type::DEFAULT_EMPTY, - 'dateInterval' => null, -]; - -/** @var \Ibexa\Contracts\Core\Repository\ContentTypeService $contentTypeService */ -$dateAndTimeFieldCreateStruct = $contentTypeService->newFieldDefinitionCreateStruct( - 'my_date_and_time_field', - 'ibexa_datetime' -); -$dateAndTimeFieldCreateStruct->fieldSettings = $settings; -``` diff --git a/docs/content_management/field_types/field_type_reference/datefield.md b/docs/content_management/field_types/field_type_reference/datefield.md index 057ece589e..858e5abc43 100644 --- a/docs/content_management/field_types/field_type_reference/datefield.md +++ b/docs/content_management/field_types/field_type_reference/datefield.md @@ -6,9 +6,7 @@ This field type represents a date without time information. |--------|---------------|---------------------| | `Date` | `ibexa_date` | mixed | -## PHP API field type - -### Input expectations +## Input expectations If input value is in `string` or `integer` format, it's passed directly to [PHP's built-in `\DateTime` class constructor](https://www.php.net/manual/en/datetime.construct.php), therefore the same input format expectations apply. @@ -24,9 +22,7 @@ Time information is **not stored**. Before storing, the provided input value is set to the beginning of the day in the given or the environment timezone. -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: @@ -34,25 +30,7 @@ The Value class of this field type contains the following properties: |----------|-------------|---------------------------------------------| | `$date` | `\DateTime` | This property is used for the text content. | -##### String representation - -String representation of the date value generates the date string in the format "l d F Y" as accepted by [PHP's built-in `date()` function](https://www.php.net/manual/en/function.date.php). - -| Character | Description | Example | -|-----------|---------------------------------------------------------------------|-----------| -| l | Textual representation of a day of the week, range Monday to Sunday | Wednesday | -| d | Two digit representation of a day, range 01 to 31 | 22 | -| F | Textual representation of a month, range January to December | May | -| Y | Four digit representation of a year | 2016 | - -Example: `Wednesday 22 May 2016` - -##### Constructor - -The constructor for this value object initializes a new value object with the value provided. -It accepts an instance of [PHP's built-in `\DateTime` class](https://www.php.net/manual/en/datetime.construct.php). - -### Hash format +## Hash format Hash value of this field type is an array with two keys: @@ -61,19 +39,11 @@ Hash value of this field type is an array with two keys: | `timestamp` | `integer` | Time information in [Unix format timestamp](https://en.wikipedia.org/wiki/Unix_time). | `1400856992` | | `rfc850` | `string` | Time information as a string in [RFC 850 date format](https://datatracker.ietf.org/doc/html/rfc850). As input, this has higher precedence over the timestamp value. | `"Friday, 23-May-14 14:56:14 GMT+0000"` | -``` php -// Example of the hash value in PHP -$hash = [ - 'timestamp' => 1400856992, - 'rfc850' => 'Friday, 23-May-14 14:56:14 GMT+0000', -]; -``` - -### Validation +## Validation This field type doesn't perform any special validation of the input value. -### Settings +## Settings The field definition of this field type can be configured with a single option: @@ -87,13 +57,3 @@ Following `defaultType` default value options are available as constants in the |------------------------|----------------------------------| | `DEFAULT_EMPTY` | Default value is empty. | | `DEFAULT_CURRENT_DATE` | Default value uses current date. | - -``` php -// Date field type example settings - -use Ibexa\Core\FieldType\Date\Type; - -$settings = [ - 'defaultType' => Type::DEFAULT_EMPTY, -]; -``` diff --git a/docs/content_management/field_types/field_type_reference/emailaddressfield.md b/docs/content_management/field_types/field_type_reference/emailaddressfield.md index 06294cf899..04be7602e3 100644 --- a/docs/content_management/field_types/field_type_reference/emailaddressfield.md +++ b/docs/content_management/field_types/field_type_reference/emailaddressfield.md @@ -6,11 +6,7 @@ The EmailAddress field type represents an email address, in the form of a string |----------------|---------------|---------------------| | `EmailAddress` | `ibexa_email` | `string` | -## PHP API field type - -### Value object - -#### Properties +## Properties The `Value` class of this field type contains the following properties: @@ -18,49 +14,17 @@ The `Value` class of this field type contains the following properties: |----------|----------|-----------------------------------------------------------------------| | `$email` | `string` | This property is used for the input string provided as email address. | -``` php -// Value object content example - -use Ibexa\Core\FieldType\EmailAddress\Value; - -// Instantiates an EmailAddress Value object with default value (empty string) -$emailaddressValue = new Value(); - -// Email definition -$emailaddressValue->email = 'someuser@example.com'; -``` - -##### Constructor - -The `EmailAddress\Value` constructor initializes a new value object with the value provided. -It accepts a string as input. - -``` php -// Constructor example - -use Ibexa\Core\FieldType\EmailAddress\Value; - -// Instantiates an EmailAddress Value object -$emailaddressValue = new Value('someuser@example.com'); -``` - -##### String representation - -String representation of the field type's value object is the email address contained in it. - -Example: `someuser@example.com` - -### Hash format +## Hash format Hash value for this field type's Value is simply the email address as a string. Example: `someuser@example.com` -### Validation +## Validation This field type uses the `EmailAddressValidator` validator as a resource which tests the string supplied as input against a pattern, to make sure that a valid email address has been provided. If the validations fail, a `ValidationError` is thrown, specifying the error message. -### Settings +## Settings This field type doesn't support settings. diff --git a/docs/content_management/field_types/field_type_reference/floatfield.md b/docs/content_management/field_types/field_type_reference/floatfield.md index b8f36d8faa..1294c2358f 100644 --- a/docs/content_management/field_types/field_type_reference/floatfield.md +++ b/docs/content_management/field_types/field_type_reference/floatfield.md @@ -6,9 +6,7 @@ This field type stores numeric values which are provided as floats. |---------|---------------|----------------| | `Float` | `ibexa_float` | `float` | -## PHP API field type - -### Input expectations +## Input expectations The field type expects a number as input. Both decimal and integer numbers are accepted. @@ -17,9 +15,7 @@ The field type expects a number as input. Both decimal and integer numbers are a | `float` | `194079.572` | | `int` | `144` | -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: @@ -27,32 +23,7 @@ The Value class of this field type contains the following properties: |----------|---------|---------------------------------------------------------------| | `$value` | `float` | This property is used to store the value provided as a float. | -``` php -// Value object content example - -use Ibexa\Core\FieldType\Float\Value as FloatValue; - -// Instantiates a Float Value object -$floatValue = new FloatValue(); - -$floatValue->value = 284.773; -``` - -##### Constructor - -The `Float\Value` constructor initializes a new value object with the value provided. -It expects a numeric value with or without decimals. - -``` php -// Constructor example - -use Ibexa\Core\FieldType\Float\Value as FloatValue; - -// Instantiates a Float Value object -$floatValue = new FloatValue(284.773); -``` - -### Validation +## Validation This field type supports `FloatValueValidator`, defining maximum and minimum float value: @@ -61,22 +32,6 @@ This field type supports `FloatValueValidator`, defining maximum and minimum flo | `minFloatValue` | `float` | `null | This setting defines the minimum value this field type which is allowed as input. | | `maxFloatValue` | `float` | `null | This setting defines the maximum value this field type which is allowed as input. | -``` php -// Validator configuration example in PHP - -/** @var \Ibexa\Contracts\Core\Repository\Repository $repository */ -$contentTypeService = $repository->getContentTypeService(); -$floatFieldCreateStruct = $contentTypeService->newFieldDefinitionCreateStruct('float', 'ibexa_float'); - -// Accept only numbers between 0.1 and 203.99 -$floatFieldCreateStruct->validatorConfiguration = [ - 'FileSizeValidator' => [ - 'minFloatValue' => 0.1, - 'maxFloatValue' => 203.99, - ], -]; -``` - -### Settings +## Settings This field type doesn't support settings. diff --git a/docs/content_management/field_types/field_type_reference/imageassetfield.md b/docs/content_management/field_types/field_type_reference/imageassetfield.md index f32fcff453..3404833e35 100644 --- a/docs/content_management/field_types/field_type_reference/imageassetfield.md +++ b/docs/content_management/field_types/field_type_reference/imageassetfield.md @@ -18,8 +18,6 @@ Example array: | `string` | ID of the Asset content item. | `"150"` | | `integer` | ID of the Asset content item. | `150` | -## Value object - ### Properties Value object of `ibexa_image_asset` contains the following properties: @@ -29,32 +27,6 @@ Value object of `ibexa_image_asset` contains the following properties: | `destinationContentId` | `int` | Related content ID. | | `alternativeText` | `string` | The alternative image text (for example "Picture of an apple."). | -``` php -/** - * Value object content example. - * - * @var \Ibexa\Core\FieldType\ImageAsset\Value $imageAssetValue - * @var \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo - */ -$imageAssetValue->destinationContentId = $contentInfo->id; -$imageAssetValue->alternativeText = 'Picture of an apple.'; -``` - -#### Constructor - -The `ImageAsset\Value` constructor initializes a new value object with the value provided. -It expects an ID of a content item representing asset and the alternative text. - -``` php -// Constructor example - -use Ibexa\Core\FieldType\ImageAsset as ImageAsset; - -/** @var \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo */ -// Instantiates a ImageAsset Value object -$imageAssetValue = new ImageAsset\Value($contentInfo->id, 'Picture of an apple.'); -``` - ### Validation This field type validates if: diff --git a/docs/content_management/field_types/field_type_reference/imagefield.md b/docs/content_management/field_types/field_type_reference/imagefield.md index 51530e4b91..39e0f13219 100644 --- a/docs/content_management/field_types/field_type_reference/imagefield.md +++ b/docs/content_management/field_types/field_type_reference/imagefield.md @@ -8,13 +8,11 @@ The Image field type allows you to store an image file. A **variation service** handles the conversion of the original image into different formats and sizes through a set of preconfigured named variations, for example, large, small, medium, or black and white thumbnail. -## PHP API field type - -### Value object +## Field value The `value` property of an Image field returns an `Ibexa\Core\FieldType\Image\Value` object with the following properties: -#### Properties +### Properties | Property | Type | Example | Description | |-------------------|--------|------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -28,11 +26,11 @@ The `value` property of an Image field returns an `Ibexa\Core\FieldType\Image\Va | `width` | int | `960` | Original image width in pixels. | | `height` | int | `540` | Original image height in pixels. | -### Settings +## Settings This field type doesn't support settings. -### Image variations +## Image variations Using the variation Service, variations of the original image can be obtained. They're `Ibexa\Contracts\Core\Variation\Values\ImageVariation` objects with the following properties: @@ -50,7 +48,7 @@ They're `Ibexa\Contracts\Core\Variation\Values\ImageVariation` objects with the | `uri` | string | `var/storage/images/test/199-2-eng-GB/apple.png` | The variation's URI. Complete path with a name of image file. | | `lastModified` | DateTime | ``"2017-08-282 12:20 Europe/Berlin"`` | When the variation was last modified. | -### Field Definition options +## Field Definition options The Image field type supports one `FieldDefinition` option: the maximum size for the file. diff --git a/docs/content_management/field_types/field_type_reference/integerfield.md b/docs/content_management/field_types/field_type_reference/integerfield.md index 1315514313..d3368f09f1 100644 --- a/docs/content_management/field_types/field_type_reference/integerfield.md +++ b/docs/content_management/field_types/field_type_reference/integerfield.md @@ -6,17 +6,13 @@ This field type represents an integer value. |-----------|-----------------|----------------| | `Integer` | `ibexa_integer` | `integer` | -## PHP API field type - -### Input expectations +## Input expectations | Type | Example | |-----------|---------| | `integer` | `2397` | -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: @@ -24,38 +20,13 @@ The Value class of this field type contains the following properties: |----------|-------|------------| | `$value` | `int` | This property is used to store the value provided as an integer. | -``` php -// Value object content example -/** @var \Ibexa\Core\FieldType\Integer\Value $integer */ -$integer->value = 8; -``` - -#### Constructor - -The `Integer\Value` constructor initializes a new value object with the value provided. -It expects a numeric, integer value. - -``` php -// Constructor example -use Ibexa\Core\FieldType\Integer; - -// Instantiates a Integer Value object -$integerValue = new Integer\Value(8); -``` - -#### Hash format +### Hash format Hash value of this field type is an integer value as a string. Example: `"8"` -#### String representation - -String representation of the field type's value returns the integer value as a string. - -Example: `"8"` - -### Validation +## Validation This field type supports `IntegerValueValidator`, defining maximum and minimum float value: @@ -64,14 +35,6 @@ This field type supports `IntegerValueValidator`, defining maximum and minimum f |`minIntegerValue`|`int`|`0`|This setting defines the minimum value this field type which is allowed as input.| |`maxIntegerValue`|`int`|`null`|This setting defines the maximum value this field type which is allowed as input.| -``` php -// Example of validator configuration in PHP -$validatorConfiguration = [ - 'minIntegerValue' => 1, - 'maxIntegerValue' => 24, -]; -``` - -### Settings +## Settings This field type doesn't support settings. diff --git a/docs/content_management/field_types/field_type_reference/isbnfield.md b/docs/content_management/field_types/field_type_reference/isbnfield.md index 57cd27dd50..e9dca1aed1 100644 --- a/docs/content_management/field_types/field_type_reference/isbnfield.md +++ b/docs/content_management/field_types/field_type_reference/isbnfield.md @@ -6,11 +6,7 @@ This field type represents an ISBN string either an ISBN-10 or ISBN-13 format. |--------|---------------|---------------------| | `ISBN` | `ibexa_isbn` | `string` | -## PHP API field type - -### Value object - -#### Properties +## Properties The Value class of this field type contains the following properties: @@ -18,22 +14,7 @@ The Value class of this field type contains the following properties: |----------|----------|--------------------------------------------| | `$isbn` | `string` | This property is used for the ISBN string. | -#### String representation - -An ISBN's string representation is the `$isbn` property's value, as a string. - -#### Constructor - -The constructor for this value object initializes a new value object with the value provided. -It accepts a string as argument and sets it to the `isbn` attribute. - -### Validation +## Validation The input passed into this field type is subject of ISBN validation depending on the field settings in its FieldDefinition stored in the content type. An example of this field setting is shown below and controls if input is validated as ISBN-13 or ISBN-10: - -``` php -[ - 'isISBN13' => true, -]; -``` diff --git a/docs/content_management/field_types/field_type_reference/keywordfield.md b/docs/content_management/field_types/field_type_reference/keywordfield.md index a46f8bb677..d99ad66256 100644 --- a/docs/content_management/field_types/field_type_reference/keywordfield.md +++ b/docs/content_management/field_types/field_type_reference/keywordfield.md @@ -6,9 +6,7 @@ This field type stores one or several comma-separated keywords as a string or ar |-----------|-----------------|------------------------| | `Keyword` | `ibexa_keyword` | `string[]` or `string` | -## PHP API field type - -### Input expectations +## Input expectations | Type | Example | |------------|-----------------------------------------------------------| @@ -16,41 +14,10 @@ This field type stores one or several comma-separated keywords as a string or ar | `string` | `"php, Ibexa Platform, html5"` | | `string[]` | `[ "Ibexa", "Enterprise", "User Experience Management" ]` | -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: | Property | Type | Description | |-----------|------------|----------------------------------------| | `$values` | `string[]` | Holds an array of keywords as strings. | - -``` php -// Value object content example -use Ibexa\Core\FieldType\Keyword\Value; - -// Instantiates a Value object -$keywordValue = new Value(); - -// Sets an array of keywords as a value -$keywordValue->values = ['php', 'css3', 'html5', 'Ibexa Platform']; -``` - -#### Constructor - -The `Keyword\Value` constructor initializes a new value object with the value provided. - -It expects a list of keywords, either comma-separated in a string or as an array of strings. - -``` php -// Constructor example -use Ibexa\Core\FieldType\Keyword\Value; - -// Instantiates a Value object with an array of keywords -$keywordValue = new Value(['php5', 'css3', 'html5']); - -// Instantiates a Value object with a list of keywords in a string -// This is equivalent to the example above -$keywordValue = new Value('php5,css3,html5'); -``` diff --git a/docs/content_management/field_types/field_type_reference/maplocationfield.md b/docs/content_management/field_types/field_type_reference/maplocationfield.md index a655f069c8..1d339edb55 100644 --- a/docs/content_management/field_types/field_type_reference/maplocationfield.md +++ b/docs/content_management/field_types/field_type_reference/maplocationfield.md @@ -11,17 +11,13 @@ As input it expects three values: |---------------|-----------------------|----------------| | `MapLocation` | `ibexa_gmap_location` | `mixed` | -## PHP API field type - -### Input expectations +## Input expectations | Type | Example | |---------|---------------------------------------------------------------------------------------| | `array` | `[ 'latitude' => 59.928732, 'longitude' => 10.777888, 'address' => "Ibexa Nordics" ]` | -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: @@ -30,22 +26,3 @@ The Value class of this field type contains the following properties: | `$latitude` | `float` | This property stores the latitude value of the map location reference. | | `$longitude` | `float` | This property stores the longitude value of the map location reference. | | `$address` | `string` | This property stores the address of map location. | - -#### Constructor - -The `MapLocation\Value` constructor initializes a new value object with values provided as hash. -Accepted keys are `latitude` (`float`), `longitude` (`float`), `address` (`string`). - -``` php -// Constructor example -use Ibexa\Core\FieldType\MapLocation as MapLocation; - -// Instantiates a MapLocation Value object -$MapLocationValue = new MapLocation\Value( - [ - 'latitude' => 59.928732, - 'longitude' => 10.777888, - 'address' => 'Ibexa Nordics', - ] -); -``` diff --git a/docs/content_management/field_types/field_type_reference/matrixfield.md b/docs/content_management/field_types/field_type_reference/matrixfield.md index 276ffb5684..673b4438b2 100644 --- a/docs/content_management/field_types/field_type_reference/matrixfield.md +++ b/docs/content_management/field_types/field_type_reference/matrixfield.md @@ -8,9 +8,7 @@ This field represents and handles a table of rows and columns of data. The Matrix field type is available via the Matrix Bundle provided by the [ibexa/fieldtype-matrix](https://github.com/ibexa/fieldtype-matrix) package. -## PHP API field type - -### Input expectations +## Input expectations | Type | Description | Example | |---------|----------------------------------------------------------------------------------------|-----------| @@ -18,17 +16,7 @@ The Matrix field type is available via the Matrix Bundle provided by the [ibexa/ Example of input: -``` php -use Ibexa\FieldTypeMatrix\FieldType; - -new FieldType\Value([ - new FieldType\Value\Row(['col1' => 'Row 1, Col 1', 'col2' => 'Row 1, Col 2']), - new FieldType\Value\Row(['col1' => 'Row 2, Col 1', 'col2' => 'Row 2, Col 2']), - new FieldType\Value\Row(['col1' => 'Row 3, Col 1', 'col2' => 'Row 3, Col 2']), -]); -``` - -### Value object +## Field value `Ibexa\FieldTypeMatrix\FieldType\Value` offers the following properties: @@ -36,7 +24,7 @@ new FieldType\Value([ |------|------|------| |`rows`|`RowsCollection`|Array of `Row` objects containing an array of cells (`Row::getCells()` returns array `['col1' => 'Value 1', /* ... */]`).| -### Validation +## Validation The minimum number of rows is set on content type level for each field. @@ -47,168 +35,3 @@ Empty rows are removed. If, after removing empty rows, the number of rows doesn't fulfill the configured `Minimum number of rows`, the field doesn't validate. For example, the following input doesn't validate if `Minimum number of rows` is set to 3, because the second row is empty: - -``` php -use Ibexa\FieldTypeMatrix\FieldType; - -new FieldType\Value([ - new FieldType\Value\Row(['col1' => 'Row 1, Col 1', 'col2' => 'Row 1, Col 2']), - new FieldType\Value\Row(['col1' => '', 'col2' => '']), - new FieldType\Value\Row(['col1' => 'Row 3, Col 1', 'col2' => 'Row 3, Col 2']), -]); -``` - -## GraphQL field type operations - -To get a field of the Matrix field type with GraphQL, you need to specify a content ID, a content type, and a field type. - -The types that are returned are named after the Type and the field: - -- `{TypeIdentifier}{FieldIdentifier}Row` - -The example below shows a GraphQL query for a Recipe content item (belonging to a content type with a Matrix field added), that has two fields: - -- `name`: `ibexa_string` -- `ingredients`: `ibexa_matrix` with two columns: `ingredient` and `quantity` - -```graphql -{ - content { - recipe(id: 123) { - name - ingredients { - ingredient - quantity - } - } - } -} -``` - -The Type returned for the Matrix field exposes columns defined in the field definition: - -```json -{ - "data": { - "content": { - "recipe": { - "name": "Cake ingredients", - "ingredients": [ - { - "ingredient": "Butter", - "quantity": "200 grams" - }, - { - "ingredient": "Sugar", - "quantity": "100 grams" - } - ] - } - } - } -} -``` - -### Query for the field type and field definition's details - -With this query you can inspect details of specific content type. -In case of a Matrix field, you can ask for the list of columns, their names, and identifiers. - -```graphql -{ - content { - _types { - recipe { - ingredients { - settings { - minimumRows - columns { - name - identifier - } - } - } - } - } - } -} -``` - -The response lists the exposed field type settings: - -- minimumRows -- columns - - name - - identifier - -Example response: - -```json -{ - "data": { - "content": { - "_types": { - "recipe": { - "ingredients": { - "settings": { - "minimumRows": 1, - "columns": [ - { - "name": "ingredient", - "identifier": "ingredient" - }, - { - "name": "quantity", - "identifier": "quantity" - } - ] - } - } - } - } - } - } -} -``` - -### Mutation - -To create a Matrix field type you need to define field type and field definition identifiers. -The types that are used for input are named after the Type and the field: - -- `{TypeIdentifier}{FieldIdentifier}RowInput`, for example, `dish.nutritionFacts`, `event.agenda`: `DishNutritionFactsRowInput`, `EventAgendaRowInput` - -The example below shows how to create a Recipe content item (belonging to a content type with a Matrix field type added) that has two fields: - -- `name`: `"Cake Ingredient List"` -- `ingredients`: `ibexa_matrix` with two columns: `ingredient` and `quantity` - -```graphql - mutation AddRecipe { - createRecipe( - language: eng_GB - parentLocationId: 2, - input: { - name: "Cake Ingredient List", - ingredients: [ - {ingredient: "sugar", quantity: "100 grams"} - {ingredient: "butter", quantity: "200 grams"} - ] - } - ) { - name - } -} -``` - -The response confirms creation of the new Recipe field: - -```json -{ - "data": { - "createRecipe": { - "name": "Cake Ingredient List" - } - } -} -``` diff --git a/docs/content_management/field_types/field_type_reference/measurementfield.md b/docs/content_management/field_types/field_type_reference/measurementfield.md index f4a9b5bdc2..c0081875c9 100644 --- a/docs/content_management/field_types/field_type_reference/measurementfield.md +++ b/docs/content_management/field_types/field_type_reference/measurementfield.md @@ -7,9 +7,7 @@ It stores the unit of measure, and either a single measurement value, or a pair |---------------|---------------------|----------------------------------------------------| | `Measurement` | `ibexa_measurement` | `Ibexa\Contracts\Measurement\Value\ValueInterface` | -## PHP API field type - -### Input expectations +## Input expectations To create a value, you use a service that implements `Ibexa\Contracts\Measurement\MeasurementServiceInterface`. You must inject the service directly with [dependency injection]([[= symfony_doc =]]/service_container.html). @@ -25,9 +23,7 @@ Assuming that the service exists as `$measurementService`, the expected input ex |`\Ibexa\Contracts\Measurement\Value\SimpleValueInterface`| `$measurementService->buildSimpleValue('length', 2.5, 'centimeter')` | |`\Ibexa\Contracts\Measurement\Value\RangeValueInterface` | `$measurementService->buildRangeValue('length', 1.2, 4.5, 'inch')` | -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: @@ -35,53 +31,11 @@ The Value class of this field type contains the following properties: |----------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `$value` | `Ibexa\Contracts\Measurement\Value\ValueInterface` | Stores the Measurement API Value, which can be either an instance of `Ibexa\Contracts\Measurement\Value\SimpleValueInterface` or `Ibexa\Contracts\Measurement\Value\RangeValueInterface`. | -#### Constructor - -The `Measurement\Value` constructor for this value object initializes a new value object with the value provided. -As its first argument it accepts an object of `Ibexa\Contracts\Measurement\Value\ValueInterface` type. - -Depending on the selected input type, the object resembles the following examples: - -``` php -// Simple input (single value) example - -use Ibexa\Measurement\FieldType\MeasurementValue; - -/** @var \Ibexa\Contracts\Measurement\MeasurementServiceInterface $measurementService */ - -// Instantiates a Measurement Value object -$measurementValue = new MeasurementValue( - $measurementService->buildSimpleValue( - 'length', - 13.5, - 'centimeter' - ) -); -``` - -``` php -// Range input value example - -use Ibexa\Measurement\FieldType\MeasurementValue; - -/** @var \Ibexa\Contracts\Measurement\MeasurementServiceInterface $measurementService */ - -// Instantiates a Measurement Value object -$measurementValue = new MeasurementValue( - $measurementService->buildRangeValue( - 'volume', - 0.5, - 0.7, - 'liter' - ) -); -``` - -### Validation +## Validation The Measurement field type validates measurement types and units passed within the value object against a list of the ones that the system supports, which can be found in the `vendor/ibexa/measurement/src/bundle/Resources/config/builtin_units.yaml` file. -### Modify and add Measurement types and units +## Modify and add Measurement types and units You can extend the default list of Measurement types and units by modifying the existing entries or adding new ones. To do this, you modify the YAML configuration. diff --git a/docs/content_management/field_types/field_type_reference/mediafield.md b/docs/content_management/field_types/field_type_reference/mediafield.md index 22dfae749c..82f857796f 100644 --- a/docs/content_management/field_types/field_type_reference/mediafield.md +++ b/docs/content_management/field_types/field_type_reference/mediafield.md @@ -16,18 +16,14 @@ It's capable of handling the following types of files: |---------|---------------|----------------| | `Media` | `ibexa_media` | mixed | -## PHP API field type - -### Input expectations +## Input expectations | Type | Description | Example | |------------------------------------|------------------------------------------------------------------------------------------|-------------------------------| | `string` | Path to the media file. | `/Users/jane/butterflies.mp4` | | `Ibexa\Core\FieldType\Media\Value` | Media field type value object with path to the media file as the value of `id` property. | See below. | -### Value object - -#### Properties +### Properties `Ibexa\Core\FieldType\Media\Value` offers the following properties. @@ -47,7 +43,7 @@ Both `Media` and `BinaryFile` Value and Type inherit from the `BinaryBase` abstr | `width` | int | Width of the media. | 400 | | `path` | string | **deprecated** | | -### Hash format +## Hash format The hash format mostly matches the value object. It has the following keys: @@ -63,7 +59,7 @@ The hash format mostly matches the value object. It has the following keys: - `height` - `width` -### Validation +## Validation The field type supports `FileSizeValidator`, defining maximum size of media file in bytes: @@ -71,24 +67,7 @@ The field type supports `FileSizeValidator`, defining maximum size of media file |------|------|------|------| |`maxFileSize`|`int`|`false`|Maximum size of the file in bytes.| -``` php -// Example of using Media field type validator in PHP - -use Ibexa\Core\FieldType\Media\Type; - -/** @var \Ibexa\Contracts\Core\Repository\Repository $repository */ -$contentTypeService = $repository->getContentTypeService(); -$mediaFieldCreateStruct = $contentTypeService->newFieldDefinitionCreateStruct('media', 'ibexa_media'); - -// Setting maximum file size to 5 megabytes -$mediaFieldCreateStruct->validatorConfiguration = [ - 'FileSizeValidator' => [ - 'maxFileSize' => 5 * 1024 * 1024, - ], -]; -``` - -### Settings +## Settings The field type supports the `mediaType` setting, defining how the media file should be handled in output. @@ -107,18 +86,3 @@ List of all available `mediaType` constants is defined in the `Ibexa\Core\FieldT | `TYPE_WINDOWSMEDIA` | Microsoft Windows Media | | `TYPE_HTML5_VIDEO` | HTML5 Video | | `TYPE_HTML5_AUDIO` | HTML5 Audio | - -``` php -// Example of using Media field type settings in PHP - -use Ibexa\Core\FieldType\Media\Type; - -/** @var \Ibexa\Contracts\Core\Repository\Repository $repository */ -$contentTypeService = $repository->getContentTypeService(); -$mediaFieldCreateStruct = $contentTypeService->newFieldDefinitionCreateStruct('media', 'ibexa_media'); - -// Setting Adobe Flash as the media type -$mediaFieldCreateStruct->fieldSettings = [ - 'mediaType' => Type::TYPE_FLASH, -]; -``` diff --git a/docs/content_management/field_types/field_type_reference/pagefield.md b/docs/content_management/field_types/field_type_reference/pagefield.md index 0c3f9af16a..d39278c597 100644 --- a/docs/content_management/field_types/field_type_reference/pagefield.md +++ b/docs/content_management/field_types/field_type_reference/pagefield.md @@ -22,10 +22,6 @@ Layout defines how a page is divided into zones. The placement of zones is defined in a template which is a part of the layout configuration. You can modify the template to define your own zone layout. -## Blocks - -For information on how to create and configure new blocks for the page, see [Create custom Page block](create_custom_page_block.md). - ## Rendering pages Page rendering takes place while editing or viewing. diff --git a/docs/content_management/field_types/field_type_reference/relationfield.md b/docs/content_management/field_types/field_type_reference/relationfield.md index 78be9fe561..4daf423e15 100644 --- a/docs/content_management/field_types/field_type_reference/relationfield.md +++ b/docs/content_management/field_types/field_type_reference/relationfield.md @@ -6,18 +6,14 @@ This field type makes it possible to store and retrieve the value of a relation |------------|-------------------------|----------------| | `Relation` | `ibexa_object_relation` | mixed | -## PHP API field type - -### Input expectations +## Input expectations | Type | Example | |-----------|---------| | `string` | `"150"` | | `integer` | `150` | -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: @@ -25,34 +21,11 @@ The Value class of this field type contains the following properties: |------------------------|-----------------------------|-------------------------------------------------------------------------------------------| | `$destinationContentId` | `string`, `int`, or `null` | This property is used to store the value provided, which represents the related content. | -``` php -/** - * Value object content example. - * - * @var \Ibexa\Core\FieldType\Relation\Value $relation - * @var \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo - */ -$relation->destinationContentId = $contentInfo->id; -``` - -#### Constructor - -The `Relation\Value` constructor initializes a new value object with the value provided. It expects a mixed value. - -``` php -// Constructor example -use Ibexa\Core\FieldType\Relation as Relation; - -/** @var \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo */ -// Instantiates a Relation Value object -$relationValue = new Relation\Value($contentInfo->id); -``` - -### Validation +## Validation This field type validates whether the provided relation exists, but before that it checks that the value is either a string or an int. -### Settings +## Settings The field definition of this field type can be configured with three options: @@ -61,15 +34,3 @@ The field definition of this field type can be configured with three options: | `selectionMethod` | `int` | `Relation\Type::SELECTION_BROWSE` | *This setting is not implemented yet, only one selection method is available.* | | `selectionRoot` | `string` | `null` | This setting defines the selection root. | | `selectionContentTypes` | `array` | `[]` | An array of content type IDs that are allowed for related Content. | - -``` php -// Relation FieldType example settings - -use Ibexa\Core\FieldType\Relation\Type; - -$settings = [ - 'selectionMethod' => 1, - 'selectionRoot' => null, - 'selectionContentTypes' => [], -]; -``` diff --git a/docs/content_management/field_types/field_type_reference/relationlistfield.md b/docs/content_management/field_types/field_type_reference/relationlistfield.md index a98d9adca0..3d728972dd 100644 --- a/docs/content_management/field_types/field_type_reference/relationlistfield.md +++ b/docs/content_management/field_types/field_type_reference/relationlistfield.md @@ -6,9 +6,7 @@ This field type makes it possible to store and retrieve values of a relation to |----------------|------------------------|----------------| | `RelationList` | `ibexa_object_relation_list` | `mixed` | -## PHP API field type - -### Input expectations +## Input expectations |Type|Description|Example| |------|------|------| @@ -17,9 +15,7 @@ This field type makes it possible to store and retrieve values of a relation to |`Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo`|ContentInfo instance of the related Content|n/a| |`Ibexa\Core\FieldType\RelationList\Value`|RelationList field type value object|See below.| -### Value Object - -#### Properties +### Properties `Ibexa\Core\FieldType\RelationList\Value` contains the following properties: @@ -27,45 +23,7 @@ This field type makes it possible to store and retrieve values of a relation to |------|------|------|------| |`destinationContentIds`|`array`|An array of related Content IDs|`[ 24, 42 ]`| -``` php -/** - * Value object content example. - * - * @var \Ibexa\Core\FieldType\RelationList\Value $relationList - * @var \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo1 - * @var \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo2 - */ -$relationList->destinationContentIds = [ - $contentInfo1->id, - $contentInfo2->id, - 170, -]; -``` - -#### Constructor - -The `RelationList\Value` constructor initializes a new value object with the value provided. -It expects a mixed array as value. - -``` php -//Constructor example -use Ibexa\Core\FieldType\RelationList as RelationList; - -/** - * @var \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo1 - * @var \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo2 - */ -// Instantiates a RelationList Value object -$relationListValue = new RelationList\Value( - [ - $contentInfo1->id, - $contentInfo2->id, - 170, - ] -); -``` - -### Validation +## Validation This field type validates if: @@ -78,7 +36,7 @@ This field type validates if: The dropdown selection method isn't implemented yet. -### Settings +## Settings The field definition of this field type can be configured with the following options: @@ -95,26 +53,8 @@ Following selection methods are available: | `SELECTION_BROWSE` | Selection uses browse mode.| | `SELECTION_DROPDOWN` | *Not implemented yet* | -### Validators +## Validators |Name|Type|Default value|Description| |------|------|------|------| |`RelationListValueValidator[selectionLimit]`|`integer`|`0`|The number of content items that can be selected in the field. When set to 0, any number can be selected.| - -``` php -// Example of using settings and validators configuration in PHP - -use Ibexa\Core\FieldType\RelationList\Type; - -$fieldSettings = [ - 'selectionMethod' => Type::SELECTION_BROWSE, - 'selectionDefaultLocation' => null, - 'selectionContentTypes' => [], - ]; - -$validators = [ - 'RelationListValueValidator' => [ - 'selectionLimit' => 0, - ], -]; -``` diff --git a/docs/content_management/field_types/field_type_reference/richtextfield.md b/docs/content_management/field_types/field_type_reference/richtextfield.md index 1c91af55ab..f5408beffe 100644 --- a/docs/content_management/field_types/field_type_reference/richtextfield.md +++ b/docs/content_management/field_types/field_type_reference/richtextfield.md @@ -8,9 +8,7 @@ This field type validates and stores structured rich text in [DocBook](https://d |------------|------------------|----------------| | `RichText` | `ibexa_richtext` | mixed | -## PHP API field type - -### Value object +## Field value `Ibexa\FieldTypeRichText\FieldType\RichText\Value` offers the following properties: @@ -18,7 +16,7 @@ This field type validates and stores structured rich text in [DocBook](https://d |----------|---------------|--------------------------------------------------------| | `xml` | `DOMDocument` | Internal format value as an instance of `DOMDocument`. | -### Input expectations +## Input expectations | Type | Description | |----------------------------------------------------|----------------------------------------------------------------------------------| @@ -26,13 +24,13 @@ This field type validates and stores structured rich text in [DocBook](https://d | `DOMDocument` | XML document in one of the field type's input formats as a `DOMDocument` object. | | `Ibexa\FieldTypeRichText\FieldType\RichText\Value` | An instance of the field type's `Value` object. | -### Input formats +## Input formats The field type expects an XML value as input, in the form of a string, `DOMDocument` object, or field type's `Value` object. The field type's `Value` object must hold the value in the field type's [internal format](#internal-format). For a string of a `DOMDocument` object, if the input doesn't conform to this format, it's converted into it. -#### Internal format +### Internal format As its internal format, the RichText field type uses a [custom flavor of the DocBook format](#custom-docbook-format). @@ -48,7 +46,7 @@ As its internal format, the RichText field type uses a [custom flavor of the Doc ``` -#### XHTML5 edit format +### XHTML5 edit format The XHTML5 format is used by the Online Editor. @@ -66,31 +64,7 @@ The XHTML5 format is used by the Online Editor. The custom DocBook format described below is subject to change and isn't covered by backwards compatibility promise. -You can use the [[= product_name_base =]] flavor of the DocBook format in PHP API and in REST API requests by providing the DocBook content as a string. - -The following example shows how to pass DocBook content to a [create struct](creating_content.md#creating-content-item-draft): - -``` php -/** - * @var \Ibexa\Contracts\Core\Repository\ContentService $contentService - * @var \Ibexa\Contracts\Core\Repository\Values\ContentType\ContentType $contentType - */ -$contentCreateStruct = $contentService->newContentCreateStruct($contentType, 'eng-GB'); - -$inputString = << -
- This is a title. - This is a paragraph. -
-DOCBOOK; - -$contentCreateStruct->setField('description', $inputString); -``` +You can use the [[= product_name_base =]] flavor of the DocBook format in REST API requests by providing the DocBook content as a string. When creating RichText content with the REST API, use the `xml` key of the `fieldValue` tag: diff --git a/docs/content_management/field_types/field_type_reference/selectionfield.md b/docs/content_management/field_types/field_type_reference/selectionfield.md index 8d76e61b6e..750530adf5 100644 --- a/docs/content_management/field_types/field_type_reference/selectionfield.md +++ b/docs/content_management/field_types/field_type_reference/selectionfield.md @@ -6,17 +6,13 @@ The Selection field type stores single selections or multiple choices from a lis |-------------|-------------------|---------------------| | `Selection` | `ibexa_selection` | mixed | -## PHP API field type - -### Input expectations +## Input expectations | Type | Example | |---------|------------| | `array` | `[ 1, 2 ]` | -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: @@ -24,65 +20,19 @@ The Value class of this field type contains the following properties: |--------------|---------|-------------------------------------------------------------------------------------------------------------------| | `$selection` | `int[]` | This property is used for the list of selections, which is a list of integer values, or one single integer value. | -``` php -// Value object content examples - -/** @var \Ibexa\Core\FieldType\Selection\Value $value */ -// Single selection -$value->selection = [1]; - -// Multiple selection -$value->selection = [1, 4, 5]; -``` - -#### Constructor - -The `Selection\Value` constructor accepts an array of selected element identifiers. - -``` php -// Constructor example -use Ibexa\Core\FieldType\Selection as Selection; - -// Instanciates a selection value with items #1 and #2 selected -$selectionValue = new Selection\Value([1, 2]); -``` - -#### String representation - -String representation of this field type is its list of selections as a string, concatenated with a comma. - -Example: `"1,2,24,42"` - -#### Hash format +### Hash format Hash format of this field type is the same as value object's `selection` property. -``` php -// Example of value in hash format - -$hash = [1, 2]; -``` - -### Validation +## Validation This field type validates the input, verifying if all selected options exist in the field definition and checks if multiple selections are allowed in the field definition. If any of these validations fail, a `ValidationError` is thrown, specifying the error message. When option validation fails, a list with the invalid options is also presented. -### Settings +## Settings | Name | Type | Default value | Description| |--------------|-----------|---------------|------------| | `isMultiple` | `boolean` | `false` | Used to allow or prohibit multiple selection from the option list. | | `options` | `hash` | `[]` | Stores the list of options defined in the field definition. | - -``` php -// Selection field type example settings - -use Ibexa\Core\FieldType\Selection\Type; - -$settings = [ - 'isMultiple' => true, - 'options' => [1 => 'One', 2 => 'Two', 3 => 'Three'], -]; -``` diff --git a/docs/content_management/field_types/field_type_reference/taxonomyentryassignmentfield.md b/docs/content_management/field_types/field_type_reference/taxonomyentryassignmentfield.md index 5eb93397af..f4c28884ac 100644 --- a/docs/content_management/field_types/field_type_reference/taxonomyentryassignmentfield.md +++ b/docs/content_management/field_types/field_type_reference/taxonomyentryassignmentfield.md @@ -14,9 +14,7 @@ To be able to assign tags to the content, first, you need to add a `TaxonomyEntr |---------------------------|-----------------------------------|--------------------------------------------------| | `TaxonomyEntryAssignment` | `ibexa_taxonomy_entry_assignment` | array with `taxonomyEntries` and `taxonomy` keys | -## PHP API field type - -### Input expectations +## Input expectations | Type | Description | Example | |---------|---------------------------------------------------------------------------------------------------------------------------------------------|-----------| @@ -24,67 +22,27 @@ To be able to assign tags to the content, first, you need to add a `TaxonomyEntr Example using an `Ibexa\Taxonomy\FieldType\TaxonomyEntryAssignment\Value` object: -``` php -use Ibexa\Contracts\Taxonomy\Service\TaxonomyServiceInterface; - -/** @var TaxonomyServiceInterface $taxonomyService */ -$taxonomyEntry1 = $taxonomyService->loadEntryByIdentifier('example_entry', 'tags'); -$taxonomyEntry2 = $taxonomyService->loadEntryByIdentifier('example_entry_2', 'tags'); -new \Ibexa\Taxonomy\FieldType\TaxonomyEntryAssignment\Value( - [ - $taxonomyEntry1, - $taxonomyEntry2, - // ... - ], - 'tags', -); -``` - Example using array: -``` php -use Ibexa\Contracts\Taxonomy\Value\TaxonomyEntry; - -/** - * @var TaxonomyEntry $taxonomyEntry - * @var TaxonomyEntry $taxonomyEntry2 - */ -return [ - 'taxonomy_entries' => [$taxonomyEntry, $taxonomyEntry2], // load entries using TaxonomyService - 'taxonomy' => 'tags', -]; -``` - -### Value object - -#### Properties +### Properties |Property|Type|Description| |--------|----|-----------| |`taxonomyEntry`|array of `Ibexa\Contracts\Taxonomy\Value\TaxonomyEntry`|Stores selected taxonomy entry.| |`taxonomy`|`string`|Stores the taxonomy identifier, all `taxonomyEntries` have to be assigned to this taxonomy and the identifier has to match the settings of the field type in content type configuration.| -#### Constructor - -The constructor accepts `taxonomyEntries` and `taxonomy` as described above. - -#### String representation - -If the field has no entries - empty string. -If the field has entries (for example: "Cars and 5 more") - a string displaying the first taxonomy entry and the number of rest of the entries. - -#### Hash format +### Hash format An array of: - `taxonomy_entries` with numerical IDs of entries. - `taxonomy` string identifier of a taxonomy. -#### Validation +### Validation The field type validates if all Taxonomy Entries from the value are assigned to the configured taxonomy. -#### Settings +### Settings | Name | Type | Default value | Description | |------------|----------|---------------|--------------------------------------| diff --git a/docs/content_management/field_types/field_type_reference/taxonomyentryfield.md b/docs/content_management/field_types/field_type_reference/taxonomyentryfield.md index ac1daa0e7b..1be37256bb 100644 --- a/docs/content_management/field_types/field_type_reference/taxonomyentryfield.md +++ b/docs/content_management/field_types/field_type_reference/taxonomyentryfield.md @@ -6,9 +6,7 @@ TaxonomyEntry is a field type that stores information about the parent entry in |----------------|-----------------------|----------------| | `TaxonomyEntry`| `ibexa_taxonomy_entry`| `array`| -## PHP API field type - -### Input expectations +## Input expectations A `TaxonomyEntry` field accepts an array with an `Ibexa\Contracts\Taxonomy\Value\TaxonomyEntry` object. @@ -18,63 +16,23 @@ A `TaxonomyEntry` field accepts an array with an `Ibexa\Contracts\Taxonomy\Value Example using an `Ibexa\Taxonomy\FieldType\TaxonomyEntry\Value` object: -``` php -use Ibexa\Contracts\Taxonomy\Service\TaxonomyServiceInterface; - -/** @var TaxonomyServiceInterface $taxonomyService */ -$taxonomyEntry = $taxonomyService->loadEntryByIdentifier('example_entry', 'tags'); -$taxonomyEntryField = new \Ibexa\Taxonomy\FieldType\TaxonomyEntry\Value($taxonomyEntry); -``` - Example using array: -``` php -use Ibexa\Contracts\Taxonomy\Value\TaxonomyEntry; - -/** @var TaxonomyEntry $taxonomyEntry */ -return [ - 'taxonomy_entry' => $taxonomyEntry, // load Entry using TaxonomyService -]; -``` - -### Value object - -#### Properties +### Properties |Property|Type|Description| |--------|----|-----------| |`taxonomyEntry`|`?Ibexa\Contracts\Taxonomy\Value\TaxonomyEntry`|Stores selected taxonomy entry.| -#### Constructor - -The constructor accepts an `Ibexa\Contracts\Taxonomy\Value\TaxonomyEntry` object. - -``` php -// Constructor example -use Ibexa\Contracts\Taxonomy\Service\TaxonomyServiceInterface; -use Ibexa\Taxonomy\FieldType\TaxonomyEntry; - -// Fetches TaxonomyEntry from TaxonomyService -/** @var TaxonomyServiceInterface $taxonomyService */ -$taxonomyEntry = $taxonomyService->loadEntryByIdentifier('example_entry', 'tags'); - -// Instantiates a taxonomy entry value -$taxonomyEntryFieldTypeValue = new TaxonomyEntry\Value($taxonomyEntry); -``` - -#### String representation - -`taxonomyEntry` string identifier or empty string if no Taxonomy Entry is selected. - -#### Hash format +### Hash format An array with `taxonomy_entry` key containing `Ibexa\Contracts\Taxonomy\Value\TaxonomyEntry` object or `null`. -#### Validation +### Validation No validation. -#### Settings +### Settings The field definition of this field type can be configured with the following options: diff --git a/docs/content_management/field_types/field_type_reference/textblockfield.md b/docs/content_management/field_types/field_type_reference/textblockfield.md index 62c3b2be6c..521596f0b4 100644 --- a/docs/content_management/field_types/field_type_reference/textblockfield.md +++ b/docs/content_management/field_types/field_type_reference/textblockfield.md @@ -6,17 +6,13 @@ The field type handles a block of multiple lines of unformatted text. It's capab |-------------|---------------|---------------------| | `TextBlock` | `ibexa_text` | `string` | -## PHP API field type - -### Input expectations +## Input expectations | Type | Example | |----------|-----------------------------------------| | `string` | `"This is a block of unformatted text"` | -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: @@ -24,20 +20,11 @@ The Value class of this field type contains the following properties: |----------|----------|---------------------------------------------| | `$text` | `string` | This property is used for the text content. | -##### String representation - -A TextBlock's string representation is the `$text` property's value, as a string. - -##### Constructor - -The constructor for this value object initializes a new value object with the value provided. -It accepts a string as argument and imports it to the `$text` attribute. - -### Validation +## Validation This field type doesn't perform any special validation of the input value. -### Settings +## Settings Settings contain only one option: diff --git a/docs/content_management/field_types/field_type_reference/textlinefield.md b/docs/content_management/field_types/field_type_reference/textlinefield.md index abb5912f8c..4fd5991c5e 100644 --- a/docs/content_management/field_types/field_type_reference/textlinefield.md +++ b/docs/content_management/field_types/field_type_reference/textlinefield.md @@ -7,11 +7,7 @@ It's capable of handling up to 255 characters. |------------|---------------|---------------------| | `TextLine` | `ibexa_string` | `string` | -## PHP API field type - -### Value object - -#### Properties +## Properties The Value class of this field type contains the following properties: @@ -19,27 +15,9 @@ The Value class of this field type contains the following properties: |----------|----------|---------------------------------------------| | `$text` | `string` | This property is used for the text content. | -##### String representation - -A TextLine's string representation is the `$text` property's value, as a string. - -##### Constructor - -The constructor for this value object initializes a new value object with the value provided. -It accepts a string as argument and imports it to the `$text` attribute. - -### Validation +## Validation The input passed into this field type is subject to validation by the `StringLengthValidator`. The length of the string provided must be between the minimum length defined in `minStringLength` and the maximum defined in `maxStringLength`. The default value for both properties is 0, which means that the validation is disabled by default. To set the validation properties, the `validateValidatorConfiguration()` method needs to be inspected, which receives an array with `minStringLength` and `maxStringLength` like in the following representation: - -``` php -[ - 'StringLengthValidator' => [ - 'maxStringLength' => 60, - 'minStringLength' => 1, - ], -]; -``` diff --git a/docs/content_management/field_types/field_type_reference/timefield.md b/docs/content_management/field_types/field_type_reference/timefield.md index 14d3c58b33..6e86329a15 100644 --- a/docs/content_management/field_types/field_type_reference/timefield.md +++ b/docs/content_management/field_types/field_type_reference/timefield.md @@ -10,9 +10,7 @@ What is stored is the number of seconds, calculated from the beginning of the da |--------|---------------|---------------------| | `Time` | `ibexa_time` | mixed | -## PHP API field type - -### Input expectations +## Input expectations If input value is of type `string` or `integer`, it's passed directly to the [PHP's built-in `\DateTime` class](https://www.php.net/manual/en/datetime.construct.php) constructor, therefore the same input format expectations apply. @@ -24,9 +22,7 @@ It's also possible to directly pass an instance of `\DateTime`. | `integer` | `1346149200` | | `\DateTime` | `new \DateTime()` | -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: @@ -34,34 +30,17 @@ The Value class of this field type contains the following properties: |----------|---------------------|-----------------------------------------------------------------------------------| | `$time` | `integer` or `null` | Holds the time information as a number of seconds since the beginning of the day. | -#### Constructor - -The constructor for this value object initializes a new value object with the value provided. -It accepts an integer representing the number of seconds since the beginning of the day. - -#### String representation - -String representation of the date value generates the date string in the format "H:i:s" as accepted by [PHP's built-in `date()` function](https://www.php.net/manual/en/function.date.php). - -| Character | Description | Example | -|-----------|---------------------------------------------------------------------|---------| -| H | Two digit representation of an hour, 24-hour format, range 00 to 23 | 12 | -| i | Two digit representation of minutes, range 00 to 59 | 14 | -| s | Two digit representation of seconds, range 00 to 59 | 56 | - -Example: `"12:14:56"` - -#### Hash format +### Hash format Value in hash format is an integer representing a number of seconds since the beginning of the day. Example: `36000` -### Validation +## Validation This field type doesn't perform validation of the input value. -### Settings +## Settings The Field definition of this field type can be configured with several options: @@ -69,12 +48,3 @@ The Field definition of this field type can be configured with several options: |---------------|--------------------------------------------------|-----------------------|-----------------------------------------------------------------------------------| | `useSeconds` | `boolean` | `false` | Used to control displaying of seconds in the output. | | `defaultType` | `Type::DEFAULT_EMPTY Type::DEFAULT_CURRENT_TIME` | `Type::DEFAULT_EMPTY` | The constant used here defines default input value when using back-end interface. | - -``` php -// Time field type example settings -use Ibexa\Core\FieldType\Time\Type; - -$settings = [ - 'defaultType' => Type::DEFAULT_EMPTY, -]; -``` diff --git a/docs/content_management/field_types/field_type_reference/urlfield.md b/docs/content_management/field_types/field_type_reference/urlfield.md index 065d2c8a34..ee179ee000 100644 --- a/docs/content_management/field_types/field_type_reference/urlfield.md +++ b/docs/content_management/field_types/field_type_reference/urlfield.md @@ -7,18 +7,14 @@ It's formed by the combination of a link and the respective text. |-------|---------------|----------------| | `Url` | `ibexa_url` | `string` | -## PHP API field type - -### Input expectations +## Input expectations | Type | Description | Example | |----------|-----------------------------------------------|------------------------| | `string` | Link content provided to the value. | "https://www.ibexa.co" | | `string` | Text content that represents the stored link. | "Ibexa" | -### Value object - -#### Properties +### Properties The Value class of this field type contains the following properties: @@ -27,48 +23,19 @@ The Value class of this field type contains the following properties: | `$link` | `string` | This property stores the link provided to the value of this field type. | | `$text` | `string` | This property stores the text to represent the stored link provided to the value of this field type. | -``` php -// Value object content example - -/** @var \Ibexa\Core\FieldType\Url\Value $url */ -$url->link = 'https://www.ibexa.co'; -$url->text = 'Ibexa'; -``` - -#### Constructor - -The `Url\Value` constructor initializes a new value object with the provided value. -It expects two comma-separated strings, corresponding to the link and text. - -``` php -// Constructor example -use Ibexa\Core\FieldType\Url; - -// Instantiates an Url Value object -$UrlValue = new Url\Value('https://www.ibexa.co/', 'Ibexa'); -``` - -### Hash format +## Hash format | Key | Type | Description | Example | |--------|----------|---------------|-------------------------| | `link` | `string` | Link content. | "https://www.ibexa.co/" | | `text` | `string` | Text content. | "Ibexa" | -``` php -// Example of the hash value in PHP -$hash = [ - 'link' => 'https://www.ibexa.co/', - 'text' => 'Ibexa', -]; -``` - -### Validation +## Validation This field type doesn't perform validation. But some validation can be made afterward, see [External URL validation](url_management.md#external-url-validation) for more information. -### Settings +## Settings This field type doesn't have settings. diff --git a/docs/content_management/field_types/field_type_reference/userfield.md b/docs/content_management/field_types/field_type_reference/userfield.md index 8a470d803d..2394929f8b 100644 --- a/docs/content_management/field_types/field_type_reference/userfield.md +++ b/docs/content_management/field_types/field_type_reference/userfield.md @@ -6,9 +6,7 @@ This field type validates and stores information about a user. |--------|---------------|----------------| | `User` | `ibexa_user` | ignored | -## PHP API field type - -### Value object +## Field value | Property | Type | Description | Example | |--------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------| @@ -20,7 +18,7 @@ This field type validates and stores information about a user. | `passwordHashType` | `mixed` | Algorithm user for generating password hash as a `PASSWORD_HASH_*` constant defined in `Ibexa\Contracts\Core\Repository\Values\User\User` class. | `User::PASSWORD_HASH_PHP_DEFAULT` | | `maxLogin` | `int` | Maximum number of concurrent logins. | `1000` | -#### Available password hash types +### Available password hash types | Constant | Description | |-------------------------------------------------------------------------------|---------------------------------------------------------------------------| diff --git a/docs/content_management/field_types/field_type_search.md b/docs/content_management/field_types/field_type_search.md deleted file mode 100644 index 3381a2049e..0000000000 --- a/docs/content_management/field_types/field_type_search.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -description: To be searchable, a field type must implement the Indexable interface. ---- - -# Field type searching - -Fields, or a custom field type, might contain or maintain data relevant for user searches. -To make the search engine aware of the data in your field type you need to implement an additional interface and register the implementation. - -## `Indexable` interface - -The `Ibexa\Contracts\Core\FieldType\Indexable` interface defines the methods below which are required if the field type provides data relevant to search engines. - -### `getIndexData(Field $field, FieldDefinition $fieldDefinition)` - -This method returns the actual index data for the provided `Ibexa\Contracts\Core\Persistence\Content\Field`. -The index data consists of an array of `Ibexa\Contracts\Core\Search\Field` instances. -They're described below in further detail. - -### `getIndexDefinition()` - -To be able to query data properly an indexable field type also is required to return search specification. You must return an associative array of `Ibexa\Contracts\Core\Search\FieldType` instances from this method, which could look like: - -``` php -use Ibexa\Contracts\Core\Search; - -return [ - 'url' => new Search\FieldType\StringField(), - 'text' => new Search\FieldType\StringField(), -]; -``` - -This example from the `Url` field type shows that the field type always returns two indexable values, both strings. -They have the names `url` and `text` respectively. - -### `getDefaultMatchField()` - -This method retrieves the name of the default field to be used for matching. -As field types can index multiple fields (see [MapLocation](maplocationfield.md) field type's implementation of this interface), this method is used to define the default field for matching. -Default field is typically used by the [`Field` Search Criterion](field_criterion.md). - -### `getDefaultSortField()` - -This method gets name of the default field to be used for sorting. -As field types can index multiple fields (see [MapLocation](maplocationfield.md) field type's implementation of this interface), this method is used to define default field for sorting. -Default field is typically used by the [`Field` Sort Clause](field_sort_clause.md). - -## Register `Indexable` implementations - -Implement `Ibexa\Contracts\Core\FieldType\Indexable` as an extra service and register this Service using the `ibexa.field_type.indexable` tag. -Example from [`indexable_fieldtypes.yaml`](https://github.com/ibexa/core/blob/6.0/src/lib/Resources/settings/indexable_fieldtypes.yml): - -``` yaml -Ibexa\Core\FieldType\Keyword\SearchField: - class: Ibexa\Core\FieldType\Keyword\SearchField - tags: - - {name: ibexa.field_type.indexable, alias: ibexa_keyword} -``` - -The `alias` should be the same as field type ID. - -## Search field values - -The search field values returned by the `getIndexData` method are simple value objects consisting of the following properties: - -|Property|Description| -|--------|-----------| -|`$name`|The name of the field| -|`$value`|The value of the field| -|`$type`|An `Ibexa\Contracts\Core\Search\FieldType` instance, describing the type information of the field.| - -## Search field types - -There are many available search field types which are handled by search backend configuration. -When using them, there is no need to adapt, for example, the Solr configuration in any way. -You can always use custom field types, but these might require re-configuration of the search backend. For Solr this would mean adapting the `schema.xml` file. - -The default available search field types that can be found in the `Ibexa\Contracts\Core\Search\FieldType` namespace are: - -|Field type|Description| -|--------|-----------| -|`BooleanField`|Boolean values.| -|`CustomField`|Custom field, for custom search data types. Probably requires additional configuration in the search backend.| -|`DateField`|Date field. Can be used for date range queries.| -|`DocumentField`|Document field| -|`FloatField`|Field for floating point numbers.| -|`FullTextField`|Represents full text searchable value of the field which can be indexed by the legacy search engine. Some full text fields are stored as an array of strings.| -|`GeoLocationField`|Field used for Geo location.| -|`IdentifierField`|Field used for IDs. Basically acts like the string field, but it's not queried by full-text searches| -|`IntegerField`|Field for integer numbers.| -|`MultipleBooleanField`|Multiple boolean values.| -|`MultipleIdentifierField`|Multiple IDs values.| -|`MultipleIntegerField`|Multiple integer numbers.| -|`MultipleStringField`|Multiple string values.| -|`PriceField`|Field for price values. Currency conversion might be applied by the search backends. Might require careful configuration.| -|`StringField`|Standard string values. It's also queried by full text searches.| -|`TextField`|Standard text values. It's queried by full text searches. Configured text normalizations in the search backend apply.| - -## Configuring Solr - -As mentioned before, if you use the standard type definitions, there is no need to configure the search backend in any way. -The field definitions are handled using `dynamicField` definitions in Solr, for example. - -If you want to configure the handling of your field, you can always add a special field definition to the Solr `schema.xml`. -For fields, the field type names used by the Solr search backend look like this: `//_`. -You can define custom `dynamicField` definitions to match, for example, on your custom `_` definition. - -You could also define a custom field definition for certain fields, like for the name field in an article: - -```xml - -``` - diff --git a/docs/content_management/field_types/field_type_storage.md b/docs/content_management/field_types/field_type_storage.md deleted file mode 100644 index e8d8a9d5a9..0000000000 --- a/docs/content_management/field_types/field_type_storage.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -description: To be able to store the data saved to a field, you must configure storage conversion for the field type. ---- - -# Field type storage - -## Storage conversion - -If you want to store field values in regular [[= product_name =]] database tables, -the `FieldValue` must be converted to the storage-specific format used by the Persistence SPI: -`Ibexa\Contracts\Core\Persistence\Content\FieldValue`. -After restoring a field of the field type, you must reverse the conversion. - -The following methods of the field type are responsible for that: - -|Method|Description| -|------|-----------| -|`toPersistenceValue()`|This method receives the value of a field of the field type and returns an SPI `FieldValue`, which can be stored.| -|`fromPersistenceValue()`|This method receives an SPI `FieldValue` and reconstructs the original value of the field from it.| - -The SPI `FieldValue` struct has properties which the field type can use: - -|Property|Description| -|--------|-----------| -|`$data`|The data to be stored in the database. This may be a scalar value, an associative array or a simple, serializable object.| -|`$externalData`|The arbitrary data stored in this field isn't touched by any of the [[= product_name =]] components directly, but is available for [Storing data externally](#storing-data-externally).| -|`$sortKey`|A value which can be used to sort content by this field.| - -### Legacy storage engine - -The Legacy storage engine uses the `ibexa_content_field` table to store field values, -and `ibexa_content_type_field_definition` to store field definition values. -They're both based on the same principle. - -Each row represents a field or a field definition, and offers several free fields of different types, where the type can store its data. - -- `ibexa_content_field` offers: - - `data_int` - - `data_text` - - `data_float` -- `ibexa_content_type_field_definition` offers: - - four `data_int` (`data_int1` to `data_int4`) fields - - four `data_float` (`data_float1` to `data_float4`) ones - - five `data_text` (`data_text1` to `data_text5`) - -Each type is free to use those fields in any way it requires. - -The default Legacy storage engine cannot store arbitrary value information as provided by a field type. -This means that using this storage engine requires a conversion. -Converters map a field's semantic values to the fields described above, for both settings (validation and configuration) and value. - -The conversion takes place through the `Ibexa\Core\Persistence\Legacy\Content\FieldValue\Converter` interface, -which you must implement in your field type. -The interface contains the following methods: - -|Method|Description| -|------|-----------| -|`toStorageValue()`|Converts a Persistence `Value` into a Legacy storage specific value.| -|`toFieldValue()`|Converts the other way around.| -|`toStorageFieldDefinition()`|Converts a Persistence `FieldDefinition` to a storage specific one.| -|`toFieldDefinition`|Converts the other way around.| -|`getIndexColumn()`|Returns the storage column which is used for indexing either `sort_key_string` or `sort_key_int`.| - -Just like a Type, a Legacy Converter needs to be registered and tagged in the [service container]([[= symfony_doc =]]/service_container.html). - -#### Registering a converter - -The registration of a `Converter` currently works through the `$config` parameter of [`Ibexa\Core\Persistence\Legacy\Handler`](https://github.com/ibexa/core/blob/6.0/src/lib/Persistence/Legacy/Handler.php). - -Those converters also need to be correctly exposed as services and tagged with `ibexa.field_type.storage.legacy.converter`: - -``` yaml -services: - Ibexa\Core\Persistence\Legacy\Content\FieldValue\Converter\TextLine: - tags: - - {name: ibexa.field_type.storage.legacy.converter, alias: ibexa_string} -``` - -The tag has the following attribute: - -| Attribute name | Usage | -|----------------|-------| -| `alias` | Represents the `fieldTypeIdentifier` (like for the [field type service](type_and_value.md#registration)). | - -!!! tip - - Converter configuration for built-in field types is located in [`ibexa/core/src/lib/Resources/settings/fieldtype_external_storages.yml`](https://github.com/ibexa/core/blob/6.0/src/lib/Resources/settings/fieldtype_external_storages.yml). - -## Storing data externally - -A field type may store arbitrary data in external data sources. -External storage can be, for example, a web service, a file in the file system, another database or even the [[= product_name =]] database itself (in form of a non-standard table). - -To store data in external storage, the field type interacts with the Persistence SPI through the `Ibexa\Contracts\Core\FieldType\FieldStorage` interface. - -Accessing the internal storage of a content item that includes a field of the field type calls one of the following methods to also access the external data: - -|Method|Description| -|------|-----------| -|`hasFieldData()`|Returns whether the field type stores external data at all.| -|`storeFieldData()`|Called right before a field of the field type is stored. The method stores `$externalData`. It returns `true` if the call manipulated internal data of the given field, so that it's updated in the internal database.| -|`getFieldData()`|Called after a field has been restored from the database to restore `$externalData`.| -|`deleteFieldData()`|Must delete external data for the given field, if exists.| -|`getIndexData()`|Returns the actual index data for the provided `Ibexa\Contracts\Core\Persistence\Content\Field`. For more information, see [search service](field_type_search.md#search-field-values).| - -Each of the above methods (except `hasFieldData`) receives a `$context` array with information on the underlying storage and the environment. -To retrieve and store data in the [[= product_name =]] data storage, but outside of the normal structures (for example, a custom table in an SQL database), use [Gateway-based storage](#gateway-based-storage) with properly injected Doctrine Connection. - -The field type must take care on its own for being compliant with different data sources and that third parties can extend the data source support. - -### Gateway-based storage - -To allow the usage of a field type that uses external data with different data storages, it's recommended to implement a gateway infrastructure and a registry for the gateways. -To make this easier, the Core implementation of field types provides corresponding interfaces and base classes. -They can also be used for custom field types. - -The interface `Ibexa\Contracts\Core\FieldType\StorageGateway` is implemented by gateways, to be handled correctly by the registry. It has one method: - -|Method|Description| -|------|-----------| -|`setConnection()`|The registry mechanism uses this method to set the SPI storage connection (for example, the database connection to the Legacy Storage database) into the gateway, which might be used to store external data. The connection is retrieved from the `$context` array automatically by the registry.| - -The Gateway implementation itself must take care of validating that it received a usable connection. If it doesn't, it should throw a `RuntimeException`. - -The registry mechanism is realized as a base class for `FieldStorage` implementations: `Ibexa\Core\FieldType\GatewayBasedStorage`. For managing `StorageGateway`s, the following methods are already implemented in the base class: - -|Method|Description| -|------|-----------| -|`addGateway()`|Allows the registration of additional `StorageGateway`s from the outside. Furthermore, an associative array of `StorageGateway`s can be given to the constructor for basic initialization. This array should originate from the dependency injection mechanism.| -|`getGateway()`|This protected method is used by the implementation to retrieve the correct `StorageGateway` for the current context.| - -!!! tip - - Refer to the built-in Keyword, URL and User field types for usages of such infrastructure. - -### Registering external storage - -To use external storage, you need to define a service implementing the `Ibexa\Contracts\Core\FieldType\FieldStorage` interface -and tag it as `ibexa.field_type.storage.external.handler` to be recognized by the repository. - -Here is an example for the `myfield` field type: - -``` yaml -services: - _defaults: - autowire: true - autoconfigure: true - public: false - - App\FieldType\MyField\Storage\MyFieldStorage: - tags: - - {name: ibexa.field_type.storage.external.handler, alias: myfield} -``` - -The configuration requires providing the `ibexa.field_type.storage.external.handler` tag, with the `alias` attribute being the *fieldTypeIdentifier*. You also have to inject the gateway in `arguments`, [see Gateway-based storage](#gateway-based-storage). - -External storage configuration for basic field types is located in [`ibexa/core/src/lib/Resources/settings/fieldtype_external_storages.yml`](https://github.com/ibexa/core/blob/6.0/src/lib/Resources/settings/fieldtype_external_storages.yml). - -Using gateway-based storage requires another service implementing `Ibexa\Core\FieldType\StorageGateway` to be injected into the [external storage handler](#storing-data-externally)). - -``` yaml -services: - _defaults: - autowire: true - autoconfigure: true - public: false - - App\FieldType\MyField\Storage\Gateway\DoctrineStorage: ~ -``` - -The `ibexa.api.storage_engine.legacy.connection` is of type `Doctrine\DBAL\Connection`. If your gateway still uses an implementation of `eZ\Publish\Core\Persistence\Database\DatabaseHandler` (`eZ\Publish\Core\Persistence\Doctrine\ConnectionHandler`), instead of the `ibexa.api.storage_engine.legacy.connection`, you can pass the `ibexa.api.storage_engine.legacy.dbhandler` service. - -Also there can be several gateways per field type (one per storage engine). -In this case it's recommended to either create base implementation which each gateway can inherit or create interface which each gateway must implement and reference it instead of specific implementation when type-hinting method arguments. - -!!! tip - - Gateway configuration for built-in field types is located in [`core/src/lib/Resources/settings/storage_engines/`](https://github.com/ibexa/core/tree/6.0/src/lib/Resources/settings/storage_engines). - -## Storing field type settings externally - -Just like in the case of data, storing [field type settings](type_and_value.md#field-type-settings) in content item tables may prove insufficient. -It's not a problem if your setting specifies, for example, the allowed number of characters in a text field. -However, the field type may represent a more complex object, for example, it may consist of two or more other fields, such as the name, product code (SKU), and price, and there can be a set of default values instead of just one. -Once you add validation rules for these field values, then it becomes an issue. - -You can overcome this obstacle: -When you create a new field type, you can move field type settings to external storage. - -!!! note - - Another benefit of an external storage is that there can be database relations to other objects/entities, and the database itself can maintain the integrity of data. - -First, create a class that implements the `Ibexa\Contracts\Core\FieldType\FieldConstraintsStorage` interface. - -Then, register the External Storage as a service and tag it with `ibexa.field_type.external_constraints_storage`. -Make sure that the alias you use matches the identifier of the new field type: - -``` yaml -services: - App\FieldType\Example\ExternalStorage: - tags: - - { name: ibexa.field_type.external_constraints_storage, alias: } -``` diff --git a/docs/content_management/field_types/field_type_validation.md b/docs/content_management/field_types/field_type_validation.md deleted file mode 100644 index 35229d2e11..0000000000 --- a/docs/content_management/field_types/field_type_validation.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Field type validation allows you to validate if data entered stored in the field conforms to the schema. ---- - -# Field type validation - -## Validator schema - -The schema for validator configuration should have a similar format to the [settings schema](type_and_value.md#field-type-settings), -except it has an additional level, to group settings for a certain validation mechanism: - -- The key on the 1st level is a string, identifying a validator -- Assigned to that is an associative array (2nd level) of settings -- This associative array has a string key for each setting of the validator -- It's assigned to a 3rd level associative array, the setting description -- This associative array should have the same format as for normal settings - -For example, for the `ibexa_string` type, the validator schema could be: - -``` php -[ - 'stringLength' => [ - 'minStringLength' => [ - 'type' => 'int', - 'default' => 0, - ], - 'maxStringLength' => [ - 'type' => 'int', - 'default' => null, - ], - ], -]; -``` diff --git a/docs/content_management/field_types/field_types.md b/docs/content_management/field_types/field_types.md index 64fc5f1106..8ea35e4549 100644 --- a/docs/content_management/field_types/field_types.md +++ b/docs/content_management/field_types/field_types.md @@ -13,56 +13,3 @@ Field types are responsible for: - Validating input data - Making the data searchable (if applicable) - Displaying fields of this type - -## Custom data - -[[= product_name =]] can support custom data to be stored in the fields of a content item. -To do so, you need to create a custom field type. - -A custom field type must implement the **FieldType Service Provider Interfaces** -available in the [`Ibexa\Core\FieldType`](https://github.com/ibexa/core/tree/6.0/src/lib/FieldType) namespace. - -!!! note "Registration" - - Remember that all your custom field types must be registered in `config/services.yml`. - For more information, see [Registration](type_and_value.md#registration). - -To provide custom functionality for a field type, the SPI interacts with multiple layers of the [[= product_name =]] architecture: - -![Field type Overview](field_type_overview.png) - -On the top layer, the field type needs to provide conversion from and to a simple PHP hash value to support the **REST API**. The generated hash value may only consist of scalar values and hashes. It must not contain objects or arrays with numerical indexes that aren't sequential and/or don't start with zero. - -[[= include_file('docs/snippets/simple_hash_value_caution.md') =]] - -Below that, the field type must support the **public PHP API** implementation regarding: - -- Settings definition for `FieldDefinition` -- Value creation and validation -- Communication with the Persistence SPI - -On the bottom level, a field type can additionally hook into the **Persistence SPI** to store data from a `FieldValue` in an external service. -All non-standard [[= product_name =]] database tables (for example, `ibexa_url`) are treated as [external storage](field_type_storage.md#storing-data-externally). - -The following sequence diagrams visualize the process of creating and publishing new content across all layers, especially focused on the interaction with a field type. - -## Creating content - -![Create content sequence](create_content_sequence.png) - -## Publishing content - -!!! note "indexLocation()" - - For **Solr** locations are indexed during Content indexing. - For **Legacy/SQL** indexing isn't required as location data already exists in a database. - -![Publish content sequence](publish_content_sequence.png) - -## Updating content - -![Update content sequence](update_content_sequence.png) - -## Loading content - -![Load content sequence](load_content_sequence.png) diff --git a/docs/content_management/field_types/type_and_value.md b/docs/content_management/field_types/type_and_value.md deleted file mode 100644 index 69f80ecb47..0000000000 --- a/docs/content_management/field_types/type_and_value.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -description: The basis of all field types are their Type and Value classes, containing, respectively, the logic and the data for the fields. ---- - -# Type and Value - -A field type must contain a Type class which contains the logic of the field type, for example, validating data, transforming from various formats, or describing the validators. -A Type class must implement `Ibexa\Core\FieldType\FieldType` ("field type interface"). -All native field types also extend the `Ibexa\Core\FieldType\FieldType` abstract class that implements this interface and provides implementation facilities through a set of abstract methods of its own. - -You should also provide a value object class for storing the custom field value provided by the field type. -The Value is used to represent an instance of the field type within a content item. -Each field presents its data using an instance of the Type's Value class. -A Value class must implement the `Ibexa\Contracts\Core\FieldType` interface. -It may also extend the `Ibexa\Core\FieldType\Value` abstract class. -It's meant to be stateless and as lightweight as possible. -This class must contain as little logic as possible, because the logic is handled by the Type class. - -## Type class - -The Type class of a field type provides an implementation of the `Ibexa\Contracts\Core\FieldType\FieldType` interface. - -### Field Definition handling - -A custom field type is used in a field definition of a custom content type. -You can additionally provide [settings for the field type](#field-type-settings) and a [validator configuration](field_type_validation.md). -Since the public PHP API cannot know anything about these, their handling is delegated to the field type itself through the following methods: - -#### `getFieldTypeIdentifier()` - -Returns a unique identifier for the custom field type which is used to assign the type to a field definition. -By convention it should be prefixed by a unique vendor shortcut (for example, `ibexa` for [[= product_name =]]). - -#### `getSettingsSchema()` - -This method retrieves via public PHP API a schema for the field type settings. -A typical setting would be, for example, default value. -The settings structure defined by this schema is stored in the `FieldDefinition`. -Since it's not possible to define a generic format for such a schema, the field type is free to return any serializable data structure from this method. - -#### `getValidatorConfigurationSchema()` - -In addition to normal settings, the field type should provide schema settings for its validation process. -The schema describes what kind of validation can be performed by the field type and which settings the user can specify to these validation methods. -For example, the `ibexa_string` type can validate minimum and maximum length of the string. -It therefore provides a schema to indicate to the user that they might specify the corresponding restrictions, when creating a `FieldDefinition` with this type. -The schema doesn't underlie any regulations, except for that it must be serializable. - -#### `validateFieldSettings()` - -The type is asked to validate the settings (provided by the user) before the public PHP API stores those settings for the field type in a `FieldDefinition`. -As a result, the field type must return if the given settings comply to the schema defined by `getSettingsSchema()`. - -#### `validateValidatorConfiguration()` - -As in `validateFieldSettings()`, this method verifies that the given validator configuration complies to the schema provided by `getValidatorConfigurationSchema()`. - -It's important to know that the schema definitions of the field type can be both of arbitrary and serializable format. -It's highly recommended to use a simple hash structure. - -!!! note - - Since it's not possible to enforce a schema format, the code using a specific field type must basically know all field types it deals with. - -This also applies to all user interfaces and the REST API, which therefore must provide extension points to register handling code for custom field type. -These extensions aren't defined yet. - -### Field type name - -The content item name is retrieved by the `Ibexa\Core\FieldType\FieldType::getName` method which must be implemented. -To generate content item name or URL alias the field type name must be a part of a name schema or a URL schema. - -## Value handling - -A field type needs to deal with the custom value format provided by it. -In order for the public PHP API to work properly, it delegates working with such custom field values to the corresponding field type. -The `Ibexa\Core\FieldType\FieldType` interface therefore provides the following methods: - -### `acceptValue()` - -This method is responsible for accepting and converting user input for the field. -It checks the input structure by accepting, building, and returning a different structure holding the data. - -For example: a user provides an HTTP link as a string, `acceptValue()` converts the link to a URL field type value object. -Unlike the `FieldType\Value` constructor, it's possible to make this method aware of multiple input types (object or primitive). - -!!! note - - `acceptValue()` asserts structural consistency of the value, but doesn't validate plausibility of the value. - -### `getEmptyValue()` - -The field type can specify that the user may define a default value for the `Field` of the type through settings. -If no default value is provided, the field type is asked for an "empty value" as the final fallback. - -The value chain for filling a specific field of the field type is as follows: - -1. Is a value provided by the filling user? -2. If not, is a default value provided by the`FieldDefinition`? -3. If not, take the empty value provided by the `FieldType`. - -### `validate()` - -In contrast to `acceptValue()` this method validates the plausibility of the given value. -It's based on the field type settings and validator configuration and stored in the corresponding `FieldDefinition`. - -## Serialization - -When [REST API](rest_api_usage.md) is used, conversion needs to be done for field type values, settings, and validator configurations. -These are converted to and from a simple hash format that can be encoded in REST payload. -As conversion needs to be done both when transmitting and receiving data through REST, field type implements the following pairs of methods: - -|Method|Description| -|------|-----------| -|`toHash()`|Converts field type Value into a simple hash format.| -|`fromHash()`|Converts the other way around.| -|`fieldSettingsToHash()`|Converts field type settings to a simple hash format.| -|`fieldSettingsFromHash()`|Converts the other way around.| -|`validatorConfigurationToHash()`|Converts field type validator configuration to a simple hash format.| -|`validatorConfigurationFromHash()`|Converts the other way around.| - -[[= include_file('docs/snippets/simple_hash_value_caution.md') =]] - -## Registration - -The field type must be registered in `config/services.yml`: - -``` yaml -services: - Ibexa\FieldTypeMatrix\FieldType\Type: - parent: Ibexa\Core\FieldType\FieldType - tags: - - {name: ibexa.field_type, alias: ibexa_matrix} -``` - -### `parent` - -As described in the [Symfony service container documentation]([[= symfony_doc =]]/service_container/advanced_definitions.html#parent-services), the `parent` config key indicates that you want your service to inherit from the parent's dependencies, including constructor arguments and method calls. -This helps to avoid repetition in your field type configuration and keeps consistency between all field types. -If you need to inject other services into your Type class, skip using the `parent` config key. - -### `tags` - -Like most API components, field types use the [Symfony service tag mechanism]([[= symfony_doc =]]/service_container/tags.html). - -A service can be assigned one or several tags, with specific parameters. -When the [service container]([[= symfony_doc =]]/service_container.html) is compiled into a PHP file, tags are read by `CompilerPass` implementations that add extra handling for tagged services. -Each service tagged as `ibexa.field_type` is added to a [registry](https://martinfowler.com/eaaCatalog/registry.html) using the `alias` key as its unique `fieldTypeIdentifier`, for example, `ibexa_string`. -Each field type must also inherit from the abstract `ibexa.field_type` service. -This ensures that the initialization steps shared by all field types are executed. - -!!! tip - - The configuration of built-in field types is located in [`core/src/lib/Resources/settings/fieldtypes.yml`](https://github.com/ibexa/core/blob/6.0/src/lib/Resources/settings/fieldtypes.yml). - -### Indexing - -To make the search engine aware of the data stored in a field type, register it as [indexable](field_type_search.md) - -## Field type settings - -It's recommended to use a simple associative array format for the settings schema returned by `Ibexa\Contracts\Core\FieldType\FieldType::getSettingsSchema()`, which follows these rules: - -- The key of the associative array identifies a setting (for example, `default`) -- Its value is an associative array describing the setting using: - - `type` to identify the setting type (for example, `int` or `string`) - - `default` containing the default setting value - -An example schema could look like this: - -``` php -[ - 'backupData' => [ - 'type' => 'bool', - 'default' => false, - ], - 'defaultValue' => [ - 'type' => 'string', - 'default' => 'Default Value', - ], -]; -``` - -!!! note - - You can store field type settings internally, or, when the schema becomes too complex, move them to [external storage](field_type_storage.md#storing-field-type-settings-externally). - -## Extensibility points - -Some field types require additional processing, for example a field type storing a binary file, or one having more complex settings, or validator configuration. -For this purpose specific implementations of an abstract class `Ibexa\Contracts\Rest\FieldTypeProcessor` are used. - -This class provides the following methods: - -|Method|Description| -|------|-----------| -|`preProcessValueHash()`|Performs manipulations on a received value hash, so that it conforms to the format expected by the `fromHash()` method described above.| -|`postProcessValueHash()`|Performs manipulations on a outgoing value hash, previously generated by the `toHash()` method described above.| -|`preProcessFieldSettingsHash()`|Performs manipulations on a received settings hash, so that it conforms to the format expected by the `fieldSettingsFromHash()` method described above.| -|`postProcessFieldSettingsHash()`|Performs manipulations on a outgoing settings hash, previously generated by the `fieldSettingsToHash()` method described above.| -|`preProcessValidatorConfigurationHash()`|Performs manipulations on a received validator configuration hash, so that it conforms to the format expected by the `validatorConfigurationFromHash()` method described above.| -|`postProcessValidatorConfigurationHash()`|Performs manipulations on a outgoing validator configuration hash, previously generated by the `validatorConfigurationToHash()` method described above.| - -Base implementations of these methods return the given hash, so you can implement only the methods your field type requires. -Some built-in field types already implement processors and you're encouraged to take a look at them. diff --git a/docs/content_management/file_management/file_management.md b/docs/content_management/file_management/file_management.md index f0b5fec1ce..e450ab2d16 100644 --- a/docs/content_management/file_management/file_management.md +++ b/docs/content_management/file_management/file_management.md @@ -4,19 +4,6 @@ description: Configurations and management of binary files. # File management -## Access binary files - -To access binary files from the PHP API, use the `Ibexa\Core\IO\IOServiceInterface::loadBinaryFile()` method: - -``` php -/** - * @var \Ibexa\Contracts\Core\Repository\Values\Content\Field $field - * @var \Ibexa\Core\IO\IOServiceInterface $ioService - */ -$file = $ioService->loadBinaryFile($field->value->id); -$fileContent = $ioService->getFileContents($file); -``` - ## Handling binary files [[= product_name =]] supports multiple binary file handling mechanisms by means of an `IOHandler` interface. This feature is used by the [BinaryFile](imagefield.md) field types. @@ -126,4 +113,3 @@ To learn how to configure other adapters, see the [bundle's online documentation For clustering, the platform provides a custom metadata handler that stores metadata about your assets in the database. This is faster than accessing the remote NFS or S3 instance to read metadata. - diff --git a/docs/content_management/forms/form_api.md b/docs/content_management/forms/form_api.md deleted file mode 100644 index e12bbe7ab3..0000000000 --- a/docs/content_management/forms/form_api.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -description: You can use PHP API to get, create and delete form submissions. ---- - -# Form API - -## Form submissions - -To manage form submissions created in the [Form Builder](form_builder_guide.md), use `FormSubmissionServiceInterface`. - -### Getting form submissions - -To get existing form submissions, use `FormSubmissionServiceInterface::loadByContent()` (which takes a `ContentInfo` object as parameter), or `FormSubmissionServiceInterface::loadById()`. - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/FormSubmissionCommand.php', 50, 50, remove_indent=True) =]] -``` - -Through this object, you can get information about submissions, such as their total number, and submission contents. - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/FormSubmissionCommand.php', 52, 60, remove_indent=True) =]] -``` - -### Creating form submissions - -To create a form submission, use the `FormSubmissionServiceInterface::create()` method. - -This method takes: - -- the `ContentInfo` object of the content item containing the form -- the language code -- the value of the field containing the form -- the array of form field values - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/FormSubmissionCommand.php', 36, 48, remove_indent=True) =]] -``` - -### Deleting form submissions - -You can delete a form submission by using the `FormSubmissionServiceInterface::delete()` method. - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/FormSubmissionCommand.php', 62, 63, remove_indent=True) =]] -``` diff --git a/docs/content_management/forms/form_builder_guide.md b/docs/content_management/forms/form_builder_guide.md index 01e309354b..68407f71f7 100644 --- a/docs/content_management/forms/form_builder_guide.md +++ b/docs/content_management/forms/form_builder_guide.md @@ -82,12 +82,6 @@ Using the buttons in the right corner, you can also edit, move, copy, hide, or s ![Forms management](img/forms_management.png) -### Form API - -To manage form submissions created in the Form Builder, use `FormSubmissionServiceInterface`. -You can get existing form submission and create or delete one. -Detailed instruction of getting, creating and deleting form submissions, you can find in [[= product_name_base =]] Developer Documentation in [Form API page](form_api.md). - ### View results You can preview the results of each published form. diff --git a/docs/content_management/forms/forms.md b/docs/content_management/forms/forms.md index 0dcc87be89..fa7e56fbe0 100644 --- a/docs/content_management/forms/forms.md +++ b/docs/content_management/forms/forms.md @@ -10,5 +10,4 @@ Forms are a type of content item that you can use to improve the functionality o [[= cards([ "content_management/forms/form_builder_guide", "content_management/forms/work_with_forms", - "content_management/forms/form_api", -], columns=3) =]] +], columns=2) =]] diff --git a/docs/content_management/forms/work_with_forms.md b/docs/content_management/forms/work_with_forms.md index d5cc68ff50..0198a37ab6 100644 --- a/docs/content_management/forms/work_with_forms.md +++ b/docs/content_management/forms/work_with_forms.md @@ -6,10 +6,6 @@ description: Form Builder enables creating dynamic forms to use in surveys, ques You can build forms consisting of different fields in the Form Builder. -!!! tip - - To learn how to get, create, and delete form submissions by using the PHP API, see [Form API](form_api.md). - [[% include 'snippets/forms_caution.md' %]] ## Existing Form fields @@ -36,24 +32,6 @@ The example configuration above resizes the Captcha image (line 3), changes the For information about available options, see [Gregwar/CaptchaBundle's documentation](https://github.com/Gregwar/CaptchaBundle#options). -## Form submission purging - -You can purge all submissions of a given form. -To do this, run the following command, where `form-id` stands for Content ID of the form for which you want to purge data: - -```bash -php bin/console ibexa:form-builder:purge-form-submissions [options] [--] -``` - -The following table lists some of the available options and their meaning: - -| Switch | Option | Description | -|--------------|------------|------------| -| `-l` | `--language-code=LANGUAGE-CODE` | Passes a language code, for example, "eng-GB". | -| `-u` | `--user[=USER]` | Passes a repository username. By default it's "admin". | -| `-c` | `--batch-size[=BATCH-SIZE]` | Passes a number of URLs to check in a single iteration. Set it to avoid using too much memory. By default it's set to 50. | -| | `--siteaccess[=SITEACCESS]` | Passes a SiteAccess to use for operations. If not provided, the default SiteAccess is used. | - ## Form-uploaded files You can use Forms to enable the user to upload files. diff --git a/docs/content_management/images/add_image_asset_from_dam.md b/docs/content_management/images/add_image_asset_from_dam.md index 08bde697f7..320e50fea9 100644 --- a/docs/content_management/images/add_image_asset_from_dam.md +++ b/docs/content_management/images/add_image_asset_from_dam.md @@ -21,9 +21,7 @@ ibexa: The configuration for each connector depends on the requirements of the specific DAM system. -You can use the provided example DAM connector for [Unsplash](https://unsplash.com/), or [extend DAM support by creating a connector of your choice](#extend-dam-support-by-adding-custom-connector). - -To add the Unsplash connector to your system, add the `ibexa/connector-unsplash` bundle to your installation. +[[= product_name =]] provides a connector for [Unsplash](https://unsplash.com/). ## Add Image Asset in Page Builder @@ -82,122 +80,3 @@ In the **Content** group, create a content type for DAM images, which includes t Now, when you use the Embed block in the Page Builder, you should see a DAM Image. For more information about block customization (defined templates, variations), see [Page blocks](../pages/page_blocks.md). - -## Extend DAM support by adding custom connector - -To extend the DAM support built into [[= product_name =]], you must create a custom handler and transformation factory. - -!!! note "Wikimedia Commons licensing" - - Before you use Wikimedia Commons assets in a production environment, ensure that you comply with their [license requirements](https://commons.wikimedia.org/wiki/Commons:Reusing_content_outside_Wikimedia#How_to_comply_with_a_file's_license_requirements). - -### Create DAM handler - -This class handles searching through Wikimedia Commons for images and fetching image assets. - -In `src/Connector/Dam/Handler` folder, create the `WikimediaCommonsHandler.php` file that resembles the following example, -which implements `search()` to query the server -and `fetchAsset()` to return asset objects: - -``` php -[[= include_code('code_samples/back_office/images/src/Connector/Dam/Handler/WikimediaCommonsHandler.php') =]] -``` - -Then, in `config/services.yaml`, register the handler as a service: - -```yaml -[[= include_file('code_samples/back_office/images/config/services.yaml', 9, 12) =]] -``` - -The `source` parameter passed in the tag is an identifier of this new DAM connector and is used in other places to glue elements together. - -### Create transformation factory - -The transformation factory maps [[= product_name =]]'s image variations to corresponding variations from Wikimedia Commons. - -In `src/Connector/Dam/Transformation` folder, create the `WikimediaCommonsTransformationFactory.php` file that resembles the following example, -which implements the `TransformationFactory` interface: - -``` php -[[= include_code('code_samples/back_office/images/src/Connector/Dam/Transformation/WikimediaCommonsTransformationFactory.php') =]] -``` - -Then register the transformation factory as a service: - -```yaml -[[= include_file('code_samples/back_office/images/config/services.yaml', 13, 16) =]] -``` - -### Register variations generator - -The variation generator applies map parameters coming from the transformation factory to build a fetch request to the DAM. -The solution uses the built-in `URLBasedVariationGenerator` class, which adds all the map elements as query parameters to the request. - -For example, for an asset with the ID `Ibexa_Logo.svg`, the handler generates the Asset with `AssetUri's URL` equal to: - -`https://commons.wikimedia.org/w/index.php?title=Special:Redirect/file/Ibexa_Logo.svg` - -When the user requests a specific variation of the image, for example, "large", the variation generator modifies the URL and returns it in the following form: - -`https://commons.wikimedia.org/w/index.php?title=Special:Redirect/file/Ibexa_Logo.svg&width=300` - -For this to happen, register the variations generator as a service available for the custom `commons` connector: - -```yaml -[[= include_file('code_samples/back_office/images/config/services.yaml', 17, 21) =]] -``` - -### Configure tab for "Select from DAM" modal - -To enable selecting an image from the DAM system, a modal window pops up with tabs and panels that contain different search interfaces. - -In this example, the search only uses the main text input. -The tab and its corresponding panel are a service created by combining existing components, like in the case of other back office tabs. - -The `commons_search_tab` service uses the `GenericSearchTab` class as a base, and the `GenericSearchType` form for search input. -It is linked to the `commons` DAM source and uses the identifier `commons`. -The DAM search tab is registered in the `connector-dam-search` tab group using the `ibexa.admin_ui.tab` tag. - -```yaml -[[= include_file('code_samples/back_office/images/config/services.yaml', 22, 33) =]] -``` - -### Create Twig template - -The template defines how images that come from Wikimedia Commons are displayed. - -In `templates/themes/standard/`, add the `commons_asset_view.html.twig` file that resembles the following example: - -```html+twig -[[= include_file('code_samples/back_office/images/templates/themes/standard/commons_asset_view.html.twig') =]] -``` - -Then, register the template and a fallback template in configuration files. -Replace `` with an [appropriate value](siteaccess_aware_configuration.md) that designates the SiteAccess or SiteAccess group, for example, `default` to use the template everywhere, including the back office: - -```yaml -[[= include_file('code_samples/back_office/images/config/packages/views.yaml') =]] -``` - -### Provide back office translation - -When the image asset field is displayed in the back office, a table of metadata follows. -This example uses new fields, so you need to provide translations for their labels, for example, in `translations/ibexa_fieldtypes_preview.en.yaml`: - -```yaml -[[= include_file('code_samples/back_office/images/translations/ibexa_fieldtypes_preview.en.yaml') =]] -``` - -### Add Wikimedia Commons connection to DAM configuration - -You can now configure a connection with Wikimedia Commons under the `ibexa.system..content.dam` key using the source identifier `commons`: - -```yaml -ibexa: - system: - default: - content: - dam: [ commons ] -``` - -Once you clear the cache, you can search for images to see whether images from the newly configured DAM are displayed correctly, including their variations. diff --git a/docs/content_management/images/configure_image_editor.md b/docs/content_management/images/configure_image_editor.md index ebbca8eed9..2cacae045a 100644 --- a/docs/content_management/images/configure_image_editor.md +++ b/docs/content_management/images/configure_image_editor.md @@ -64,25 +64,3 @@ Keep this in mind when configuring blur strength for environments that handle hi Each image can be accompanied by additional information that isn't visible to the user. By default, additional information stores the coordinates of the [focal point]([[= user_doc =]]/image_management/edit_images/#focal-point), but you can use this extension point to pass various parameters of custom features that you add by extending the Image Editor. - -To modify the value of additional information programmatically, you can set a value of the `Image` field by using the PHP API, for example: - -``` php -use Ibexa\Core\FieldType\Image\Value as FieldValue; - -$value = new FieldValue([ - 'data' => [ - 'width' => '100', - 'height' => '200', - 'alternativeText' => 'test', - 'mime' => 'image/png', - 'id' => 1, - 'fileName' => 'image.png', - 'additionalData' => [ - 'focalPointX' => 50, - 'focalPointY' => 100, - 'author' => 'John Smith', - ], - ], - ]); -``` diff --git a/docs/content_management/images/fastly_io.md b/docs/content_management/images/fastly_io.md index 63d5ca26f6..c68f06ec29 100644 --- a/docs/content_management/images/fastly_io.md +++ b/docs/content_management/images/fastly_io.md @@ -79,13 +79,7 @@ so you aren't able to reflect your original filters accurately with Fastly. The script below helps you find replacement filters within Fastly configuration for the basic filters. For more optimization options on Fastly side, see [Fastly IO reference](https://www.fastly.com/documentation/reference/io/). -To generate your original image configuration run: - -```bash -php bin/console ibexa:fastly:migrate-configuration -``` - -Paste the following configuration to define the same variations for Fastly IO: +The following configuration defines the same variations for Fastly IO: ```yaml ibexa: diff --git a/docs/content_management/images/images.md b/docs/content_management/images/images.md index bc4f414014..723d19b70c 100644 --- a/docs/content_management/images/images.md +++ b/docs/content_management/images/images.md @@ -25,27 +25,6 @@ For an ImageAsset field to be reused, you must publish it. Only then is notification triggered, which states that an image has been published under the location and can now be reused. After you establish a media library, you can create [Relations](content_relations.md) between the image content item and the main content item that uses it. -## Normalizing image file names - -If you use image files with unprintable UTF-8 characters in file names, you may come across a problem with images not displaying. -Run the following command to normalize image file names: - -``` bash -php bin/console ibexa:images:normalize-paths -``` - -Next, clear the cache: - -```bash -php bin/console cache:clear -``` - -and run the following: - -```bash -php bin/console liip:imagine:cache:remove -``` - ## Configuring image variations With image variations (image aliases) you can define and use different versions of the same image. @@ -70,44 +49,6 @@ For more information, see the [bundle's documentation](https://symfony.com/bundl - Images may contain specially crafted flaws that exploit vulnerabilities in common image libraries like GD or Imagick, leading to code execution. It's important to keep these libraries up to date with security updates. -### Image URL resolution - -You can use LiipImagine's `liip:imagine:cache:resolve` command to resolve the path to image variations that are generated from the original image, with one or more paths as arguments. -Paths to repository images must be relative to the `var//storage/images` directory, for example: `7/4/2/0/247-1-eng-GB/test.jpg`. - -For more information, see [LiipImagineBundle documentation](https://symfony.com/bundles/LiipImagineBundle/current/basic-usage.html#resolve-with-the-console). - -## Resizing images - -You can resize all original images of a chosen content type with the following command. - -``` bash -php bin/console ibexa:images:resize-original -f -``` - -You must provide the command with: - -- identifier of the image content type -- identifier of the field that you want to affect -- name of the image variation to apply to the images - -For example: - -``` bash -php bin/console ibexa:images:resize-original image photo -f small_image -``` - -You can also pass two additional parameters: - -- `iteration-count` is the number of images to be recreated in a single iteration, to reduce memory use. - The default value is `25`. -- `user` is the identifier of a User with proper permission who performs the operation (`read`, `versionread`, `edit` and `publish`). - The default value is `admin`. - -!!! caution - - The `resize-original` command publishes a new version of each content item it modifies. - ## Generating placeholder images With a placeholder generator you can download or generate placeholder images for any missing image. @@ -186,50 +127,6 @@ If there is no configuration assigned to the `binary_handler`, the placeholder g [[= include_file('code_samples/back_office/images/config/packages/images_live.yaml') =]] ``` -## Support for SVG images - -You cannot store SVG images in [[= product_name =]] by using the Image or ImageAsset field type. -However, you can work things around by relying on the File field type and implementing a custom extension that lets you display and download files in your templates. - -!!! caution - - SVG images may contain JavaScript, so they may introduce XSS or other security vulnerabilities. - Make sure end users aren't allowed to upload SVG images, and be restrictive about which editors are allowed to do so. - -First, enable adding SVG files to content by removing them from the blacklist of allowed MIME types. - -To do it, overwrite `ibexa.site_access.config.default.io.file_storage.file_type_blacklist` defined in `Core/Resources/config/default_settings.yml` so that `svg` is removed from the blacklist. -You can do it per SiteAccess or SiteAccess group by using [SiteAccess-aware configuration](siteaccess_aware_configuration.md). - -Then, add a download route to the `config/routes.yaml` file: - -```yaml -[[= include_file('code_samples/back_office/images/config/routes.yaml') =]] -``` - -It points to a custom controller that handles the downloading of the SVG file. -The controller's definition (that you place in the `config/services.yaml` file under `services` key) and implementation are as follows: - -```yaml -[[= include_file('code_samples/back_office/images/config/services.yaml', 0, 8) =]] -``` - -``` php -[[= include_code('code_samples/back_office/images/src/SvgController.php') =]] -``` - -To be able to use a proper link in your templates, you also need a dedicated Twig extension: - -``` php -[[= include_code('code_samples/back_office/images/src/SvgExtension.php') =]] -``` - -Now you can load SVG files in your templates by using generated links and a newly created Twig helper: - -```twig -[[= include_file('code_samples/back_office/images/templates/themes/standard/svg_helper.html.twig') =]] -``` - ## Image optimization JPEG images are optimized using the ImageMagic library, which is available out of the box. @@ -250,17 +147,6 @@ Install these libraries using your package manager, for example: sudo apt-get install optipng ``` -### Customizing image optimizers - -When the Image Editor saves a modified image, the system dispatches the `ConfigureImageOptimizersEvent` event before running the optimizer chain. -You can listen to this event to customize the list of image optimizers at runtime. - -The following example shows how to remove the Pngquant optimizer to prevent grayscale conversion of low-saturation PNG images: - -``` php -[[= include_code('code_samples/back_office/images/src/Event/RemovePngquantOptimizer.php') =]] -``` - ## Embedding images in Rich Text The [RichText](richtextfield.md) field allows you to embed other content items within the field. diff --git a/docs/content_management/locations.md b/docs/content_management/locations.md index 1597e10198..1f390797d3 100644 --- a/docs/content_management/locations.md +++ b/docs/content_management/locations.md @@ -21,8 +21,7 @@ A content item can have more than one location. It's then present in two or more For example, an article can be at the same time under "Local news" and "Sports news". Even in such a case, one of these places is always the main location. -You can change the main location in the back office in the **Locations** tab, -or [through the API](managing_content.md#changing-the-main-location). +You can change the main location in the back office in the **Locations** tab. ![Locations](content_management_locations.png "Locations") diff --git a/docs/content_management/pages/create_custom_page_block.md b/docs/content_management/pages/create_custom_page_block.md deleted file mode 100644 index 4ef3253a4b..0000000000 --- a/docs/content_management/pages/create_custom_page_block.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -description: Create and configure custom Page blocks to add customized content to Pages. -month_change: false ---- - -# Create custom Page block - -In addition to existing blocks which you can use in a Page, you can also create custom blocks. - -To do this, add block configuration in a YAML file, under the `ibexa_fieldtype_page` [configuration key](configuration.md#configuration-files). - -[[% include 'snippets/page_block_cache_clear.md' %]] - -The following example shows how to create a block that showcases an event. - -## Configure block - -First, add the following [YAML configuration](configuration.md#configuration-files): - -``` yaml -[[= include_file('code_samples/page/custom_page_block/config/packages/page_blocks.yaml', 0, 6) =]][[= include_file('code_samples/page/custom_page_block/config/packages/page_blocks.yaml', 16, 49) =]] -``` - -And provide the translations for the labels: - -- in `translations/ibexa_page_builder_block_config.en.yaml`: - -``` yaml -event_block.view.default: Default -event_block.view.featured: Featured - -event_block.name.name: Name -event_block.category.name: Category -event_block.event.name: Event -``` - -- in `translations/ibexa_page_fieldtype.en.yaml`: - -``` yaml -custom_category.name: Custom category -event_block.name: Event -``` - -- in `translations/validators.en.yaml`: - -``` yaml -validators.message.event_block.name.validator.not_blank: Event name should not be blank. -validators.message.event_block.embed.validator.not_blank: Event content should not be blank. -validators.message.event_block.embed.validator.content_type: Event content should be of type "event". -validators.message.event_block.embed.validator.content_item: Event content should have a numerical ID. -``` - -`event` is the internal name for the block, and `name` indicates the name under which the block is available in the interface. -You also set up the category in the **Page blocks** toolbox that the block appears in. -In this case, it doesn't show up with the rest of the built-in blocks, but in a separate "Custom category" category. -The thumbnail for the block can be one of the pre-existing icons, like in the example above, or you can use a custom SVG file. - -A block can have multiple attributes that you edit when adding it to a page. -In this example, you configure three attributes: name of the event, category it belongs to, and an event content item that you select and embed. - -For a list of all available attribute types, see [Page block attributes](page_block_attributes.md). - -Each attribute can have [validators](page_block_validators.md). -The `not_blank` validators in the example ensure that the user fills in the two block fields. -The `content_type` validator in the example ensure that the user choose a content item of the content type `event`. -The `regexp` validator ensure that the final value looks like a content ID. - -The following UDW configuration is used with the `udw_config_name` key so only an event typed content item can be selected: - -``` yaml -[[= include_file('code_samples/page/custom_page_block/config/packages/page_blocks.yaml', 50, 59) =]] -``` - -## Add block templates - -A block can have different templates that you select when adding it to a page. - -To configure block templates, add them to block configuration: - -``` yaml -[[= include_file('code_samples/page/custom_page_block/config/packages/page_blocks.yaml', 0, 3) =]][[= include_file('code_samples/page/custom_page_block/config/packages/page_blocks.yaml', 7, 16) =]] -``` - -Provide the templates in the indicated folder, in this case in `templates/themes//blocks/event`. - -For example the `featured_template.html.twig` file can look like this: - -``` html+twig -[[= include_file('code_samples/page/custom_page_block/templates/themes/standard/blocks/event/featured_template.html.twig') =]] -``` - -The templates have access to all block attributes, as you can see above in the `name`, `category` and `event` variables. - -Priority of templates indicates the order in which they're presented in Page Builder. -The template with the greatest priority is used as the default one. - -## Add block JavaScript - -If your block is animated with JavaScript, you may have to take precaution to keep it working when previewed in back office's Page Builder. - -If you use an event related to the page being loaded to trigger the initialisation of your custom block, a freshly added block doesn't work in the Page Builder preview. -For example, the [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event) event isn't fired when a block is dragged into the page as the DOM is already loaded. - -The Page Builder fires `body` events that you can listen to initialize your block: - -- `ibexa-render-block-preview` event is fired when the page is loaded in the Page Builder, when a block is added, when a block is deleted, and when a block setting modification is submitted. -- `ibexa-post-update-blocks-preview` event is fired when a block setting modification is submitted, this event has a `detail` property listing the reloaded modified block IDs and their configs. - -In the following code, the same `initCustomBlocks` function is attached to two event listeners. -One listener to call the function when a page is loaded (as a regular front page or as a page edited in the Page Builder). -The other one to call it when a block is added or configured in the Page Builder. -This `initCustomBlocks` function finds the custom blocks to loop through them, initializes some JavaScript when the block isn't already initialized, and flag the block as initialized. -For example, it could initialize carousel blocks with the addition of event listeners to navigation arrows, and the start of an automatic sliding. - -```javascript -document.addEventListener('DOMContentLoaded', function(event) { - initCustomBlocks(); -}); -document.getElementsByTagName('body')[0].addEventListener('ibexa-render-block-preview', function(event) { - initCustomBlocks(); -}); -``` - -!!! note - - If you consider using React JavaScript library, see [React App block](react_app_block.md). - -## Add pre-render event listener - -If you need to compute variables to pass to the template, you can listen or subscribe to the block pre-render event. - -For example, the following event subscriber loads the `event` content item and passes it to the template as `event_content`: - -``` php -[[= include_code('code_samples/page/custom_page_block/src/Event/Subscriber/BlockEmbedEventEventSubscriber.php') =]] -``` - -The block view template could now use `ibexa_render(event_content, {'viewType': 'embed'})` instead of `render(controller('ibexa_content::viewAction', {'contentId': event, 'viewType': 'embed'}))`, other content Twig functions, or field Twig functions. - -For more information, see [Block events](page_blocks.md#block-events). - -## Add edit template - -You can also customize the template for the block settings modal. -Do this under the `configuration_template` [configuration key](configuration.md#configuration-files): - -``` yaml -[[= include_file('code_samples/page/custom_page_block/config/packages/page_blocks.yaml', 0, 7) =]] -``` - -Place the edit template in `templates/themes//blocks/event/config.html.twig`: - -``` html+twig -[[= include_file('code_samples/page/custom_page_block/templates/themes/standard/blocks/event/config.html.twig') =]] -``` - -Your custom page block is now registered in the system. - -!!! caution - - To use the new block in Page Builder, add it to the list of available blocks in a given content type's settings. This can be done manually in [Page field settings]([[= user_doc =]]/content_management/configure_ct_field_settings/#block-display). diff --git a/docs/content_management/pages/page_block_attributes.md b/docs/content_management/pages/page_block_attributes.md index 26a4088f95..7f9fa7b374 100644 --- a/docs/content_management/pages/page_block_attributes.md +++ b/docs/content_management/pages/page_block_attributes.md @@ -30,7 +30,7 @@ The following attribute types are available: |`string`|String|-| |`url`|URL|-| |`text`|Text block|-| -|`richtext`|Rich text block (see [creating RichText block](create_custom_richtext_block.md))|-| +|`richtext`|Rich text block|-| |`embed`|Embedded content item|`udw_config_name`: name of the Universal Discovery Widget's configuration | |`embedvideo`|Embedded content item|`udw_config_name`: name of the Universal Discovery Widget's configuration | |`select`|Drop-down with options to select|
  • `choices` lists the available options in `label: value` form
  • `multiple`, when set to true, allows selecting more than one option
| @@ -53,82 +53,8 @@ attributes: The `embed`, `embedvideo`, and `locationlist` attribute types use the Universal Discovery Widget (UDW). When creating a block with these types you can use the `udw_config_name` option to configure the UDW behavior. -See the [custom block example](create_custom_page_block.md#configure-block) to learn more. -## Custom attribute types - -You can create custom attribute type to add to Page blocks. - -A custom attribute requires attribute type class, a mapper and a template. - -### Block attribute type - -First, create the attribute type class. - -It can extend one of the types available in `fieldtype-page/src/lib/Form/Type/BlockAttribute/`. -You can also use one of the [built-in Symfony types]([[= symfony_doc =]]/reference/forms/types.html), -for example `AbstractType` for any custom type or `IntegerType` for numeric types. - -To define the type, create a `src/Block/Attribute/MyStringAttributeType.php` file: - -``` php hl_lines="5 6 17" -[[= include_code('code_samples/page/custom_attribute/src/Block/Attribute/MyStringAttributeType.php') =]] -``` - -The attribute uses `AbstractType` (line 5) and `TextType` (line 6). -Adding `getBlockPrefix` (line 15) returns a unique prefix key for a custom template of the attribute. - -### Mapper - -At this point, the attribute type configuration is complete, but it requires a mapper. -Depending on the complexity of the type, you can use a `GenericFormTypeMapper` or create your own. - -#### Generic mapper - -For a generic mapper, add a new service definition to `config/services.yaml`: - -``` yaml -[[= include_file('code_samples/page/custom_attribute/config/custom_services.yaml', 0, 7) =]] -``` - -#### Custom mapper - -To use a custom mapper, create a class that inherits from `Ibexa\Contracts\FieldTypePage\FieldType\Page\Block\Attribute\FormTypeMapper\AttributeFormTypeMapperInterface`, -for example in `src/Block/Attribute/MyStringAttributeMapper.php`: - -``` php -[[= include_code('code_samples/page/custom_attribute/src/Block/Attribute/MyStringAttributeMapper.php') =]] -``` - -Then, add a new service definition for your mapper to `config/services.yaml`: - -``` yaml -[[= include_file('code_samples/page/custom_attribute/config/custom_services.yaml', 8, 11) =]] -``` - -### Edit templates - -Next, configure a template for the attribute edit form by creating a `templates/themes/admin/custom_form_templates.html.twig` file: - -``` html+twig -[[= include_file('code_samples/page/custom_attribute/templates/themes/admin/custom_form_templates.html.twig') =]] -``` - -Add the template to your configuration under the `system..page_builder_forms` [configuration key](configuration.md#configuration-files): - -``` yaml -[[= include_file('code_samples/page/custom_attribute/config/packages/page_blocks.yaml', 16, 22) =]] -``` - -### Custom attribute configuration - -Now, you can create a block containing your custom attribute: - -``` yaml hl_lines="12-16" -[[= include_file('code_samples/page/custom_attribute/config/packages/page_blocks.yaml', 0, 15) =]] -``` - -### Nested attribute configuration +## Nested attribute configuration The `nested_attribute` attribute is used when you want to create a group of attributes. diff --git a/docs/content_management/pages/page_block_validators.md b/docs/content_management/pages/page_block_validators.md index a9ca6760b1..17c0f7593d 100644 --- a/docs/content_management/pages/page_block_validators.md +++ b/docs/content_management/pages/page_block_validators.md @@ -34,44 +34,3 @@ email: pattern: '/^\S+@\S+\.\S+$/' message: Provide a valid e-mail address ``` - -## Custom validators - -You can create Page block attributes with custom validators. - -The following example shows how to create a validator which requires that string attributes contain only alphanumeric characters. - -First, create classes that support your intended method of validation. -For example, in `src/Validator`, create an `AlphaOnly.php` file: - -``` php -[[= include_code('code_samples/page/custom_block_validator/src/Validator/AlphaOnly.php') =]] -``` - -In `src/Validator`, create an `AlphaOnlyValidator.php` class that performs the validation. - -``` php -[[= include_code('code_samples/page/custom_block_validator/src/Validator/AlphaOnlyValidator.php') =]] -``` - -Then, under `ibexa_fieldtype_page.block_validators`, enable the new validator in Page Builder: - -``` yaml -[[= include_file('code_samples/page/custom_block_validator/config/packages/page_blocks.yaml', 0, 3) =]] -``` - -Finally, add the validator to one of your block attributes, for example: - -``` yaml hl_lines="16-18" -[[= include_file('code_samples/page/custom_block_validator/config/packages/page_blocks.yaml', 0, 1) =]][[= include_file('code_samples/page/custom_block_validator/config/packages/page_blocks.yaml', 3, 20) =]] -``` - -### Custom required validator - -By default, only `not_blank` and `not_blank_richtext` validators mark a block attribute as required. - -If you create a custom validator `custom_not_blank` with attribute-specific logic, you can extend the `AttributeType` class with a Symfony form type extension to make sure that the attribute is also considered required: - -``` php hl_lines="15" -[[= include_code('code_samples/page/custom_block_validator/src/Form/Extension/AttributeTypeExtension.php') =]] -``` diff --git a/docs/content_management/pages/page_blocks.md b/docs/content_management/pages/page_blocks.md index 94e2d64226..aa7c9920e8 100644 --- a/docs/content_management/pages/page_blocks.md +++ b/docs/content_management/pages/page_blocks.md @@ -33,10 +33,6 @@ For example: [[= include_file('code_samples/page/custom_page_block/config/packages/page_blocks.yaml', 0, 12) =]][[= include_file('code_samples/page/custom_page_block/config/packages/page_blocks.yaml', 16, 17) =]]# ... ``` -!!! tip - - For a full example of block configuration, see [Create custom Page block](create_custom_page_block.md). - ### Block name and help text The `name` setting accepts either a single translation key, a hard coded string of text that won't be translated, or an object with `text` and `help` property keys. @@ -115,44 +111,3 @@ The following example wraps all form fields for block attributes in an ordered l ``` html+twig [[= include_file('code_samples/page/custom_page_block/templates/themes/standard/blocks/event/config.html.twig') =]] ``` - -## Block events - -To add functionalities to your block that go beyond the available attributes, you can use an event listener. - -You can listen to events related to block definition and block rendering. - -The following events are available: - -- `BlockDefinitionEvents::getBlockDefinitionEventName` - dispatched when block definition is created -- `BlockDefinitionEvents::getBlockAttributeDefinitionEventName` - dispatched when block attribute definition is created -- `BlockRenderEvents::getBlockPreRenderEventName` - dispatched before a block is rendered -- `BlockRenderEvents::getBlockPostRenderEventName` - dispatched after a block is rendered - -For example, to modify a block by adding a new parameter to it, you can create the following listener: - -``` php -[[= include_code('code_samples/page/page_listener/src/Block/Listener/MyBlockListener.php') =]] -``` - -Before the block is rendered, the listener adds `my_parameter` to it with value `parameter_value`. -You can use this parameter, for example, in block template: - -``` html+twig -[[= include_file('code_samples/page/page_listener/templates/themes/standard/block/my_block.html.twig') =]] -``` - -### Exposing content relations from blocks - -Page blocks, for example Embed block or Collection block, can embed other content items. -Publishing a page with such blocks creates Relations to those content items. - -When creating a custom block with embeds, you can ensure such Relations are created using the block Relation collection event. - -The event is dispatched on content publication. -You can hook your event listener to the `BlockRelationEvents::getCollectBlockRelationsEventName` event. - -To expose relations, pass an array containing Content IDs to the `Ibexa\FieldTypePage\Event\CollectBlockRelationsEvent::setRelations()` method. -If embedded Content changes, old Relations are removed automatically. - -Providing Relations also invalidates HTTP cache for your block response in one of the related content items changes. diff --git a/docs/content_management/pages/page_builder_guide.md b/docs/content_management/pages/page_builder_guide.md index e78fc76f86..b13e428298 100644 --- a/docs/content_management/pages/page_builder_guide.md +++ b/docs/content_management/pages/page_builder_guide.md @@ -132,7 +132,7 @@ When you add a new block to the drop zone, drop it in the blue highlighted area. ![Drop zone line](drop_zone_line.png) -Ready-to-use blocks available in [[= product_name =]] have their own, unique functions, but you can also [add your own, custom blocks](create_custom_page_block.md). All available tools and settings, that Page Builder comes with, enable you to customize the content appearing on the page. +Ready-to-use blocks available in [[= product_name =]] have their own, unique functions. All available tools and settings, that Page Builder comes with, enable you to customize the content appearing on the page. You can check all ready-to-use blocks available in Page Builder in User Documentation, [Block reference page]([[= user_doc =]]/content_management/block_reference/). diff --git a/docs/content_management/pages/pages.md b/docs/content_management/pages/pages.md index e82d0052c4..75cb657309 100644 --- a/docs/content_management/pages/pages.md +++ b/docs/content_management/pages/pages.md @@ -12,5 +12,4 @@ Pages are block-based special types of content that editors can create and modif "content_management/pages/page_blocks", "content_management/pages/page_block_attributes", "content_management/pages/page_block_validators", - "content_management/pages/create_custom_page_block", ], columns=3) =]] diff --git a/docs/content_management/pages/react_app_block.md b/docs/content_management/pages/react_app_block.md index a717e797dd..e342561a98 100644 --- a/docs/content_management/pages/react_app_block.md +++ b/docs/content_management/pages/react_app_block.md @@ -17,7 +17,7 @@ It's common to all the blocks. ## React App Block configuration React App blocks are regular [Page blocks](page_blocks.md) and can be configured on field definition level as any other block. -File has exactly the same structure as regular YAML [block configuration](create_custom_page_block.md#configure-block), except: +Their configuration has exactly the same structure as regular [block configuration](page_blocks.md#block-configuration), except: - additional `component` attribute which binds Page Builder block with React App - `views` attribute is removed diff --git a/docs/content_management/rich_text/create_custom_richtext_block.md b/docs/content_management/rich_text/create_custom_richtext_block.md deleted file mode 100644 index d72e718b07..0000000000 --- a/docs/content_management/rich_text/create_custom_richtext_block.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -description: Create a custom Page block containing rich text. ---- - -# Create custom RichText block - -A RichText block is a specific example of a [custom block](create_custom_page_block.md) that you can use when you create a page. -To create a custom block, you must define the block's layout, provide templates, add a subscriber, and register the subscriber as a service. - -Follow the procedure below to create a RichText page block. - -First, provide the block configuration under the `ibexa_page_fieldtype.blocks` [configuration key](configuration.md#configuration-files). -The following code defines a new block, its view and configuration templates. -It also sets the attribute type to `richtext` (line 15): - -``` yaml hl_lines="3 15" -[[= include_file('code_samples/back_office/online_editor/config/packages/ibexa_page_fieldtype.yaml') =]] -``` - -!!! note - - Make sure that you provide an icon for the block in the `assets/images/blocks/` folder. - -Then, create a subscriber that converts a string of data into XML code. -Create a `src/Event/Subscriber/RichTextBlockSubscriber.php` file. - -In line 28, `my_block` is the same name of the block that you defined in line 3 above. -Line 28 links this block `PreRenderEvent` to a method using `BlockRenderEvents::getBlockPreRenderEventName()`. -Lines 37-47 handle the conversion of content into an XML string: - -``` php hl_lines="28 37-47" -[[= include_code('code_samples/back_office/online_editor/src/event/subscriber/RichTextBlockSubscriber.php') =]] -``` - -Now you can create templates that are used for displaying and configuring your block. - -Create the view template in `templates/themes//blocks/my_block/richtext.html.twig`. -Line 2 is responsible for rendering the content from XML to HTML5: - -``` html+twig hl_lines="2" -
- {{ document | ibexa_richtext_to_html5 }} -
-``` - -Then, create a separate `templates/themes/admin/blocks/my_block/config.html.twig` template: - -``` html+twig -{% extends '@IbexaPageBuilder/page_builder/block/config.html.twig' %} - -{% block meta %} - {{ parent() }} - -{% endblock %} -``` - -Finally, register the subscriber as a service in `config/services.yaml`: - -``` yaml -services: - App\Event\Subscriber\RichTextBlockSubscriber: - tags: - - { name: kernel.event_subscriber } -``` - -You have successfully created a custom RichText block. -You can now add your block in the **Site** tab. - -![RichText block](extending_richtext_block.png) - -For more information about customizing additional options of the block or creating custom blocks with other attribute types, see [Create custom Page block](create_custom_page_block.md). diff --git a/docs/content_management/rich_text/rich_text.md b/docs/content_management/rich_text/rich_text.md index 4171c85c67..77c755016c 100644 --- a/docs/content_management/rich_text/rich_text.md +++ b/docs/content_management/rich_text/rich_text.md @@ -9,5 +9,4 @@ RichText is a type of field that you add in any content item in [[= product_name [[= cards([ "content_management/rich_text/online_editor_guide", - "content_management/rich_text/create_custom_richtext_block", -], columns=2) =]] +], columns=1) =]] diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index 40b263dccd..de72f6199b 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/docs/content_management/taxonomy/taxonomy.md @@ -99,22 +99,6 @@ ibexa: delete_subtree_size_limit: 20 ``` -## Remove orphaned content items - -In some rare case, especially in [[= product_name =]] v4.2 and older, when deleting parent of huge subtrees, some taxonomy entries aren't properly deleted, leaving content items that point to a non-existing parent. -The command `ibexa:taxonomy:remove-orphaned-content` deletes those orphaned content item. -It works on a taxonomy passed as an argument, and has two options that act as a protective measure against deleting data by mistake: - -- `--dry-run` to list deletable content items, without performing the deletion. -- `--force` to effectively delete the orphaned content items. - -The following example first lists the orphaned content items for taxonomy `tags`, and then deletes them: - -```bash -php bin/console ibexa:taxonomy:remove-orphaned-content tags --dry-run -php bin/console ibexa:taxonomy:remove-orphaned-content tags --force -``` - ## Taxonomy suggestions Once the feature is [enabled](#enable-taxonomy-suggestions), with taxonomy suggestions, editors can pick from suggestions generated by an AI service based on selected fields like the product's or content item's name and description instead of having to manually browse through taxonomy trees and selecting [product categories]([[= user_doc =]]/product_catalog/work_with_product_categories/#assign-product-categories-by-editing-product-details) or [tags]([[= user_doc =]]/content_management/create_edit_content_items/#add-taxonomy-entries). @@ -125,7 +109,7 @@ The `TaxonomyEmbeddingFieldProviderInterface` For performance reasons, embeddings for the taxonomy tree entries are generated only in two cases: -- when the search engine is reindexed, for example, right after you enable the feature and run the `ibexa:reindex` command +- when the search engine is reindexed, for example, right after you enable the feature - when an individual taxonomy entry is created or modified, it's embedding is updated When the editor creates or edits a content item or a product, they can request that the application suggests tags or product categories to be associated with the item. @@ -167,13 +151,6 @@ ibexa: default_embedding_model: 'text-embedding-ada-002' ``` -If you are happy with the default settings, clear the cache and reindex the search engine. - -```bash -php bin/console cache:clear -php bin/console ibexa:reindex -``` - #### Configure AI action Once you enable the Taxonomy suggestions feature, you must [configure an AI action]([[= user_doc =]]/ai_actions/work_with_ai_actions/#create-ai-actions-that-control-taxonomy-suggestions) that handles the generation of embeddings for newly created or edited content items or products. @@ -288,23 +265,4 @@ ibexa: default_embedding_model: 'gemini_embedding_001_1536' ``` -After you make the change: - -- Update the [Solr schema](field_type_search.md#configuring-solr) or Elasticsearch mappings by adding dynamic field definitions. Ensure that they match the dimensions (for example, 1536 or 3072) and suffixes that you defined above -- Clear the cache and reindex the search engine - -### Extending Taxonomy suggestions - -You can extend the feature by replacing the default code by exploring one of the following ideas. - -#### Replace the embedding provider - -By default, the system uses the `ibexa_openai` connector. -You can add your own embedding provider if needed. To do it: - -- Implement the `EmbeddingProviderInterface` -- Register the service with the `ibexa.embedding_provider` tag - -#### Extend the AI action form - -You can extend the `TextToTaxonomyOptionsType` AI action form by inheriting from `Ibexa\Bundle\Taxonomy\Form\Type\AbstractActionConfigurationOptions`. +After you make the change, ensure that the search index field definitions match the dimensions (for example, 1536 or 3072) and the suffixes that you defined above. diff --git a/docs/content_management/taxonomy/taxonomy_api.md b/docs/content_management/taxonomy/taxonomy_api.md deleted file mode 100644 index 22166003d1..0000000000 --- a/docs/content_management/taxonomy/taxonomy_api.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -description: Using the PHP API you can browse taxonomy entries, get their information and manage them. ---- - -# Taxonomy API - -To manage taxonomies, use `TaxonomyServiceInterface`. - -## Getting taxonomy entries - -To get a single taxonomy entry, you can use `TaxonomyServiceInterface::loadEntryById()`, -and provide it with the numerical entry ID. -Or pass entry identifier (with optionally a taxonomy identifier), -and use `TaxonomyServiceInterface::loadEntryByIdentifier()`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/TaxonomyCommand.php', 35, 37, remove_indent=True) =]] -``` - -!!! note - - A taxonomy entry identifier is unique per taxonomy. If you have [several taxonomies](taxonomy.md#customize-taxonomy-structure), you can increase code readability by always passing the taxonomy identifier even when it's the default one. The default taxonomy is `tags` if it exists, else the first configured taxonomy (see `\Ibexa\Taxonomy\Service\TaxonomyConfiguration::getDefaultTaxonomyName` for details). - ``` php - /** - * @var array $springs - * @var \Ibexa\Contracts\Taxonomy\Service\TaxonomyServiceInterface $taxonomyService - */ - $springs[] = $taxonomyService->loadEntryByIdentifier('spring', 'tags'); - $springs[] = $taxonomyService->loadEntryByIdentifier('spring', 'events'); - $springs[] = $taxonomyService->loadEntryByIdentifier('spring', 'devices'); - ``` - -You can also get a taxonomy entry from the ID of its underlying content item, by using `TaxonomyServiceInterface::loadEntryByContentId()`. - -To get the root (main) entry of a given taxonomy, use `TaxonomyServiceInterface::loadRootEntry()` -and provide it with the taxonomy name. - -To get all entries in a taxonomy, use `TaxonomyServiceInterface::loadAllEntries()`, provide it with the taxonomy identifier, -and optionally specify the limit of results and their offset. -The default taxonomy identifier is given by `TaxonomyConfiguration::getDefaultTaxonomyName` and is `'tags'` on a fresh installation. -The default limit is 30. - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/TaxonomyCommand.php', 33, 33, remove_indent=True) =]] -``` - -To see how many entries is there, use `TaxonomyServiceInterface::countAllEntries()` with optionally a taxonomy identifier. - -To get all children of a specific taxonomy entry, use `TaxonomyServiceInterface::loadEntryChildren()`, -provide it with the entry object, and optionally specify the limit of results and their offset. -The default limit is 30: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/TaxonomyCommand.php', 40, 44, remove_indent=True) =]] -``` - -## Managing taxonomy entries - -You can move a taxonomy entry to a different parent by using `TaxonomyServiceInterface::moveEntry()`. -Provide the method with two objects: the entry that you want to move and the new parent entry: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/TaxonomyCommand.php', 46, 49, remove_indent=True) =]] -``` - -You can also move a taxonomy entry by passing its target sibling entry to `TaxonomyServiceInterface::moveEntry()`. -The method takes as parameters the entry you want to move, the future sibling, -and a `position` parameter, which is either `TaxonomyServiceInterface::MOVE_POSITION_NEXT` or `TaxonomyServiceInterface::MOVE_POSITION_PREV`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/TaxonomyCommand.php', 51, 52, remove_indent=True) =]] -``` - -## Search - -You can search for content based on its taxonomy entry assignments by using the standard [`SearchService`](search_api.md) with taxonomy-specific Search Criteria: - -| Criterion | Description | -|---|---| -| [TaxonomyEntryId](taxonomy_entry_id.md) | Find content assigned to a specific taxonomy entry | -| [TaxonomyNoEntries](taxonomy_no_entries.md) | Find content that has no entries assigned from a given taxonomy | -| [TaxonomySubtree](taxonomy_subtree.md) | Find content assigned to a taxonomy entry or any of its descendants | - -You can also use the [TaxonomyEntryId Aggregation](taxonomyentryid_aggregation.md) to count content items per taxonomy entry. diff --git a/docs/content_management/url_management/url_api.md b/docs/content_management/url_management/url_api.md deleted file mode 100644 index cb7e9d75bd..0000000000 --- a/docs/content_management/url_management/url_api.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -description: The PHP API URLService enables searching for external URLs used in tech text and URL fields. ---- - -# URL API - -`URLService` -enables you to find, load and update external URLs used in RichText and URL fields. - -To view a list of all URLs, use `URLService::findUrls` - -`URLService::findUrls` takes as argument a `URLQuery`, -in which you need to specify: - -- query filter, for example, Section -- Sort Clauses for URL queries -- offset for search hits, used for paging the results -- query limit. If value is `0`, search query doesn't return any search hits - -``` php -// ... -[[= include_file('code_samples/api/public_php_api/src/Command/FindUrlCommand.php', 5, 6) =]][[= include_file('code_samples/api/public_php_api/src/Command/FindUrlCommand.php', 7, 10) =]] -// ... -[[= include_file('code_samples/api/public_php_api/src/Command/FindUrlCommand.php', 34, 49) =]] -``` - -## URL search reference - -For the reference of Search Criteria and Sort Clauses you can use in URL search, -see [URL Search Criteria](url_search_criteria.md) and [URL Sort Clauses](url_search_sort_clauses.md). diff --git a/docs/content_management/url_management/url_management.md b/docs/content_management/url_management/url_management.md index c649bef673..0c0640dd2c 100644 --- a/docs/content_management/url_management/url_management.md +++ b/docs/content_management/url_management/url_management.md @@ -106,7 +106,7 @@ For each URL alias definition the history of changes is preserved, so that users !!! caution "Legacy storage engine limitation" - The [Legacy storage engine](field_type_storage.md#legacy-storage-engine) doesn't archive URL aliases, which initially had the same name in multiple languages. + URL aliases that initially had the same name in multiple languages aren't archived. URL aliases aren't SiteAccess-aware. When creating an alias, you can select a SiteAccess to base it on. If the SiteAccess root path (configured in `content.tree_root.location_id`) is different than the default, @@ -146,32 +146,6 @@ You can make use of pre-defined transformation groups. You can also add your own, with your own set of commands. To add commands to an existing group, provide the group name and list the commands that you want to add. -### Regenerating URL aliases - -You can use the `ibexa:urls:regenerate-aliases` command to regenerate all URL aliases. -After the command is applied, old aliases redirect to the new ones. - -Use it when: - -- you change URL alias configuration and want to regenerate old aliases -- you encounter database corruption -- you have content that doesn't have a URL alias - -!!! caution - - Before you apply the command, back up your database and make sure it's not modified while the command is running. - -Execute the following command to regenerate aliases: - -``` bash -bin/console ibexa:urls:regenerate-aliases -``` - -You can also extend the command with the following parameters: - -- `--iteration-count` — Defines how many locations are processed at once to reduce memory usage -- `--location-id` — Regenerates URL addresses for specific locations only, for example, `ibexa:urls:regenerate-aliases --location-id=1 --location-id=2` - ## URL wildcards With wildcards, you can change the URL address for many content items at the same time, by replacing a portion of the destination's URL address. @@ -201,22 +175,3 @@ The **URL wildcards** tab contains all the information about each URL wildcard. To be able to modify wildcard support settings in the user interface, you must have the `content/urltranslator` policy. For more information about permissions, see [Permissions](permissions.md). - -### Configuring URL wildcards with the public PHP API - -You can create URL wildcards with the public PHP API by using the `URLWildcardService` service: - -``` php -/** @var \Ibexa\Contracts\Core\Repository\Repository $repository */ -$source = 'pictures/*/*'; -$destination = 'media/images/{1}/{2}'; -$redirect = true; - -$urlWildcardService = $repository->getURLWildcardService(); -$repository->sudo(static function ($repository) use ($urlWildcardService, $source, $destination, $redirect): void { - $urlWildcardService->create($source, $destination, $redirect); -}); -``` - -If `$redirect` is set to `true`, the redirection changes the URL address. -If it's `false`, the old URL address is be used, with the new content. diff --git a/docs/content_management/workflow/workflow_api.md b/docs/content_management/workflow/workflow_api.md deleted file mode 100644 index 002cc60663..0000000000 --- a/docs/content_management/workflow/workflow_api.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -description: PHP API enables you to get workflow information and apply specific workflow transitions. ---- - -# Workflow API - -You can manage [workflows](workflow.md) with PHP API by using `WorkflowServiceInterface`. - -## Workflow service - -Workflow uses the Symfony [Workflow Component]([[= symfony_doc =]]/workflow.html), -extended in the workflow service. - -The service implements the following methods: - -- `start` - places a content item in a workflow -- `apply` - performs a transition -- `can` - checks if a transition is possible - -The methods `apply` and `can` are the same as in Symfony Workflow, -but the implementation in workflow service extends them, for example by providing messages. - -## Getting workflow information - -To get information about a specific workflow for a content item, use `WorkflowServiceInterface::loadWorkflowMetadataForContent`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/WorkflowCommand.php', 52, 56, remove_indent=True) =]] -``` - -!!! tip - - `marking`, a term from [Symfony Workflow]([[= symfony_doc =]]/workflow.html), - refers to a state in a workflow. - -If you already have a `VersionInfo` object, use `WorkflowServiceInterface::loadWorkflowMetadataForVersionInfo` to avoid loading the full `Content`. -This method is more efficient when iterating over draft versions: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/WorkflowCommand.php', 64, 65, remove_indent=True) =]] -``` - -To get a list of all workflows that can be used for a given content item, use `WorkflowRegistryInterface::getSupportedWorkflows`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/WorkflowCommand.php', 46, 46, remove_indent=True) =]] -``` - -## Applying workflow transitions - -To place a content item in a workflow, use `WorkflowServiceInterface::start`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/WorkflowCommand.php', 51, 51, remove_indent=True) =]] -``` - -To apply a transition to a content item, use `Workflow::apply`. -Additionally, you can check if the transition is possible for the given object by using `WorkflowServiceInterface::can`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/WorkflowCommand.php', 58, 62, remove_indent=True) =]] -``` - -!!! tip - - `Ibexa\Workflow\Value\WorkflowMetadata` object contains all - information about a workflow, such as ID, name, transitions and current stage. - `Ibexa\Workflow\Value\WorkflowMetadata::$workflow` gives you direct - access to native Symfony Workflow object. diff --git a/docs/product_catalog/product_api.md b/docs/product_catalog/product_api.md index c8786479b2..48e46a855d 100644 --- a/docs/product_catalog/product_api.md +++ b/docs/product_catalog/product_api.md @@ -166,7 +166,6 @@ To create a virtual product type (for products that don't require shipping), use #### Adding field definitions To add custom field definitions to the product type, use `getContentTypeCreateStruct()` to access the underlying content type struct. -For more information about working with content types, see [Adding content types](../content_management/content_api/managing_content.md#adding-content-types). ``` php [[= include_code('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 63, 69, remove_indent=True) =]] diff --git a/docs/search/content_type_search_reference/content_type_criteria.md b/docs/search/content_type_search_reference/content_type_criteria.md index 253fb04d55..73987b1079 100644 --- a/docs/search/content_type_search_reference/content_type_criteria.md +++ b/docs/search/content_type_search_reference/content_type_criteria.md @@ -6,8 +6,6 @@ month_change: false # Content Type Search Criteria reference -Content Type Search Criteria are only supported by [Content Type Search (`ContentTypeService::findContentTypes`)](managing_content.md#finding-and-filtering-content-types). - | Criterion | Description | |-------|-------------| | ContainsFieldDefinitionId | Matches content types that contain a field definition with the specified ID. | diff --git a/docs/search/content_type_search_reference/content_type_sort_clauses.md b/docs/search/content_type_search_reference/content_type_sort_clauses.md index da21282d7d..dc4029041a 100644 --- a/docs/search/content_type_search_reference/content_type_sort_clauses.md +++ b/docs/search/content_type_search_reference/content_type_sort_clauses.md @@ -6,7 +6,6 @@ month_change: false # Content Type Search Sort Clauses Content Type Search Sort Clauses are the sorting options for content types. -They're only supported by [Content Type Search (`ContentTypeService::findContentTypes`)](managing_content.md#finding-and-filtering-content-types). Sort Clauses are found in the `Ibexa\Contracts\Core\Repository\Values\ContentType\Query\SortClause` namespace: diff --git a/docs/search/url_search_reference/url_search_criteria.md b/docs/search/url_search_reference/url_search_criteria.md index af047ae0b1..257765cded 100644 --- a/docs/search/url_search_reference/url_search_criteria.md +++ b/docs/search/url_search_reference/url_search_criteria.md @@ -5,8 +5,6 @@ page_type: reference # URL Search Criteria reference -URL Search Criteria are only supported by [URL Search (`URLService::findUrls`)](url_api.md). - |URL criteria|URL based on| |------------|------------| |[LogicalAnd](logicaland_url_criterion.md)|Implements a logical AND Criterion. It matches if ALL of the provided Criteria match.| diff --git a/docs/search/url_search_reference/url_search_sort_clauses.md b/docs/search/url_search_reference/url_search_sort_clauses.md index e052cc26a7..c2e4fec50d 100644 --- a/docs/search/url_search_reference/url_search_sort_clauses.md +++ b/docs/search/url_search_reference/url_search_sort_clauses.md @@ -6,7 +6,6 @@ page_type: reference # URL Sort Clauses URL Sort Clauses are the sorting options for URLs. -They're only supported by [URL Search (`URLService::findUrls`)](url_api.md). All URL Sort Clauses can take the following optional argument: diff --git a/mkdocs.yml b/mkdocs.yml index d7f3f5b201..fd1ffc73b2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -71,9 +71,7 @@ nav: - Locations: content_management/locations.md - Content Relations: content_management/content_relations.md - Content availability: content_management/content_availability.md - - Taxonomy: - - Taxonomy: content_management/taxonomy/taxonomy.md - - Taxonomy API: content_management/taxonomy/taxonomy_api.md + - Taxonomy: content_management/taxonomy/taxonomy.md - Images: - Images: content_management/images/images.md - Configure Image Editor: content_management/images/configure_image_editor.md @@ -82,7 +80,6 @@ nav: - RichText: - RichText: content_management/rich_text/rich_text.md - Online Editor guide: content_management/rich_text/online_editor_guide.md - - Create custom RichText block: content_management/rich_text/create_custom_richtext_block.md - File management: - File management: content_management/file_management/file_management.md - Binary and Media download: content_management/file_management/binary_and_media_download.md @@ -93,35 +90,17 @@ nav: - Page blocks: content_management/pages/page_blocks.md - Page block attributes: content_management/pages/page_block_attributes.md - Page block validators: content_management/pages/page_block_validators.md - - Create custom Page block: content_management/pages/create_custom_page_block.md - React App page block: content_management/pages/react_app_block.md - Ibexa Connect scenario block: content_management/pages/ibexa_connect_scenario_block.md - Forms: - Forms: content_management/forms/forms.md - Form Builder guide: content_management/forms/form_builder_guide.md - Work with Forms: content_management/forms/work_with_forms.md - - Form API: content_management/forms/form_api.md - - Workflow: - - Workflow: content_management/workflow/workflow.md - - Workflow API: content_management/workflow/workflow_api.md - - URL management: - - URL management: content_management/url_management/url_management.md - - URL API: content_management/url_management/url_api.md + - Workflow: content_management/workflow/workflow.md + - URL management: content_management/url_management/url_management.md - User-generated content: content_management/user_generated_content.md - - Content API: - - Browsing content: content_management/content_api/browsing_content.md - - Creating content: content_management/content_api/creating_content.md - - Managing content: content_management/content_api/managing_content.md - - Content management API: - - Bookmark API: content_management/content_management_api/bookmark_api.md - - Section API: content_management/content_management_api/section_api.md - - Object state API: content_management/content_management_api/object_state_api.md - Field types: - Field types: content_management/field_types/field_types.md - - Type and Value: content_management/field_types/type_and_value.md - - Storage: content_management/field_types/field_type_storage.md - - Validation: content_management/field_types/field_type_validation.md - - Searching: content_management/field_types/field_type_search.md - Field type reference: - Field type reference: content_management/field_types/field_type_reference/field_type_reference.md - Address field type: content_management/field_types/field_type_reference/addressfield.md diff --git a/tests/python/invariants-baseline.yaml b/tests/python/invariants-baseline.yaml index b85024e09e..6d3b859df4 100644 --- a/tests/python/invariants-baseline.yaml +++ b/tests/python/invariants-baseline.yaml @@ -57,65 +57,6 @@ php_code_sample: - api/rest_api/extending_rest_api/creating_new_rest_resource.md - api/rest_api/rest_api_usage/rest_requests.md - api/rest_api/rest_api_usage/testing_rest_api.md - - content_management/content_api/browsing_content.md - - content_management/content_api/creating_content.md - - content_management/content_api/managing_content.md - - content_management/content_management_api/bookmark_api.md - - content_management/content_management_api/object_state_api.md - - content_management/content_management_api/section_api.md - - content_management/data_migration/add_data_migration_matcher.md - - content_management/data_migration/create_data_migration_action.md - - content_management/data_migration/create_data_migration_step.md - - content_management/data_migration/data_migration_api.md - - content_management/field_types/create_custom_field_type_comparison.md - - content_management/field_types/create_custom_generic_field_type.md - - content_management/field_types/field_type_reference/addressfield.md - - content_management/field_types/field_type_reference/authorfield.md - - content_management/field_types/field_type_reference/binaryfilefield.md - - content_management/field_types/field_type_reference/checkboxfield.md - - content_management/field_types/field_type_reference/countryfield.md - - content_management/field_types/field_type_reference/dateandtimefield.md - - content_management/field_types/field_type_reference/datefield.md - - content_management/field_types/field_type_reference/emailaddressfield.md - - content_management/field_types/field_type_reference/floatfield.md - - content_management/field_types/field_type_reference/imageassetfield.md - - content_management/field_types/field_type_reference/integerfield.md - - content_management/field_types/field_type_reference/isbnfield.md - - content_management/field_types/field_type_reference/keywordfield.md - - content_management/field_types/field_type_reference/maplocationfield.md - - content_management/field_types/field_type_reference/matrixfield.md - - content_management/field_types/field_type_reference/measurementfield.md - - content_management/field_types/field_type_reference/mediafield.md - - content_management/field_types/field_type_reference/relationfield.md - - content_management/field_types/field_type_reference/relationlistfield.md - - content_management/field_types/field_type_reference/richtextfield.md - - content_management/field_types/field_type_reference/selectionfield.md - - content_management/field_types/field_type_reference/taxonomyentryassignmentfield.md - - content_management/field_types/field_type_reference/taxonomyentryfield.md - - content_management/field_types/field_type_reference/textlinefield.md - - content_management/field_types/field_type_reference/timefield.md - - content_management/field_types/field_type_reference/urlfield.md - - content_management/field_types/field_type_search.md - - content_management/field_types/field_type_validation.md - - content_management/field_types/form_and_template.md - - content_management/field_types/type_and_value.md - - content_management/file_management/file_management.md - - content_management/forms/create_custom_form_field.md - - content_management/forms/create_form_attribute.md - - content_management/forms/form_api.md - - content_management/images/add_image_asset_from_dam.md - - content_management/images/configure_image_editor.md - - content_management/images/images.md - - content_management/pages/create_custom_page_block.md - - content_management/pages/page_block_attributes.md - - content_management/pages/page_block_validators.md - - content_management/pages/page_blocks.md - - content_management/rich_text/create_custom_richtext_block.md - - content_management/taxonomy/taxonomy_api.md - - content_management/url_management/url_api.md - - content_management/url_management/url_management.md - - content_management/workflow/add_custom_workflow_action.md - - content_management/workflow/workflow_api.md - customer_management/cp_applications.md - infrastructure_and_maintenance/background_tasks.md - infrastructure_and_maintenance/cache/http_cache/content_aware_cache.md