diff --git a/blog/2026-03-23-storyblok-advanced-field-docs.mdx b/blog/2026-03-23-storyblok-advanced-field-docs.mdx new file mode 100644 index 0000000..373c44d --- /dev/null +++ b/blog/2026-03-23-storyblok-advanced-field-docs.mdx @@ -0,0 +1,19 @@ +--- +title: Storyblok Fields, Metadata and Rich Text Helpers +authors: [jannik] +tags: [storyblok, symfony] +--- + +The Storyblok docs were expanded with advanced field options, Story metadata access, Rich Text helper utilities, and `ReleaseVersion` usage in the Content API. + +## Updated Pages + +- [Fields][1]: documented `ChoiceField` advanced options and sources, plus missing options for `AssetField`, `LinkField` and `RichTextField`. +- [Components][2]: added a full `StoryMetaData` reference table with short descriptions for all accessors and properties. +- [Content API][3]: documented `ReleaseVersion` usage for fetch methods. +- [More Features][4]: added docs for Rich Text conversion helpers. + +[1]: /docs/php/symfony/storyblok/components/fields +[2]: /docs/php/symfony/storyblok/components +[3]: /docs/php/symfony/storyblok/api/content-api +[4]: /docs/php/symfony/storyblok/more-features/rich-text-transformers diff --git a/docs/php/symfony/storyblok/api/content-api.mdx b/docs/php/symfony/storyblok/api/content-api.mdx index dee3a21..ebbfd8f 100644 --- a/docs/php/symfony/storyblok/api/content-api.mdx +++ b/docs/php/symfony/storyblok/api/content-api.mdx @@ -81,3 +81,30 @@ Fetches signed asset data for private assets. ```php $appStoryblok->contentApi->fetchSignedAssetUrl("https://a.storyblok.com/f/..."); ``` + +## Version / Release State + +Most content fetch methods accept a `ReleaseVersion` argument as last parameter and default to `ReleaseVersion::PUBLISHED`. + +```php +use Torr\Storyblok\Release\ReleaseVersion; + +$appStoryblok->contentApi->fetchSingleStory( + identifier: "home", + version: ReleaseVersion::DRAFT, +); + +// you can also create the version from a preview flag: + +ReleaseVersion::fromPreviewFlag(true); +``` + +This is supported for: + +- `fetchSingleStory()` +- `fetchStories()` +- `fetchAllStories()` +- `fetchDatasourceEntries()` +- `fetchFoldersInPath()` +- `fetchFolderTitleMap()` +- `fetchAllLinks()` diff --git a/docs/php/symfony/storyblok/components/fields.mdx b/docs/php/symfony/storyblok/components/fields.mdx index 6d901a0..498fe83 100644 --- a/docs/php/symfony/storyblok/components/fields.mdx +++ b/docs/php/symfony/storyblok/components/fields.mdx @@ -115,11 +115,12 @@ A selector to select one or multiple assets. #### Custom Options -| Option | Description | -|---------------------|-------------------------------------------------------------------------------| -| `$fileTypes` | The file types to allow. Use the `AssetFileType` enum for all allowed values. | -| `$allowMultiple` | Whether to allow selecting multiple assets. | -| `$allowExternalUrl` | Whether to also allow adding external URLs as assets. | +| Option | Description | +|------------------------|-------------------------------------------------------------------------------| +| `$fileTypes` | The file types to allow. Use the `AssetFileType` enum for all allowed values. | +| `$allowMultiple` | Whether to allow selecting multiple assets. | +| `$allowExternalUrl` | Whether to also allow adding external URLs as assets. | +| `$useDescriptionAsAlt` | Whether the entered asset description should be used as fallback alt text. | You can manually order the items in multi-select mode. @@ -152,10 +153,12 @@ A selection field. #### Custom Options -| Option | Description | -|---------------------|-------------------------------------------------------------------------------| -| `$choices` | The file types to allow. Use the `AssetFileType` enum for all allowed values. | -| `$allowMultiselect` | Whether to allow selecting multiple entries. | +| Option | Description | +|---------------------------|------------------------------------------------------------------------------------| +| `$choices` | The source for selectable options (for example `StaticChoices` or `StoryChoices`). | +| `$allowMultiselect` | Whether to allow selecting multiple entries. | +| `$minimumNumberOfOptions` | Minimum amount of selected options (only in multiselect mode). | +| `$maximumNumberOfOptions` | Maximum amount of selected options (only in multiselect mode). | #### Choice Sources @@ -164,8 +167,10 @@ The selection can display different kind of choices. - `DatasourceChoices`: load choices from a data source in this space. - `LanguagesChoices`: selection of Storyblok-defined languages. +- `RemoteJsonChoices`: load choices from a remote JSON endpoint. - `StaticChoices`: a list of statically defined choices. - `StoryChoices`: a selector to select other stories. +- `EnumChoices`: use a PHP backed enum as source. The enum must implement `BackedEnumChoiceInterface`. :::note @@ -196,13 +201,15 @@ Will always allow to link to an internal story or an external URL. #### Custom Options -| Option | Description | -|----------------------|-----------------------------------------------------------------------------------------| -| `$allowEmailLinks` | Allows adding e-mail links. | -| `$allowAssetLinks` | Allows linking to an asset. | -| `$allowAnchors` | Add a custom text anchor to an internal link. | -| `$internalLinkScope` | Scope to restrict the story selector to. See the Storyblok docs for the pattern format. | -| `$allowedComponents` | Restrict the type of selectable stories. | +| Option | Description | +|--------------------------|-----------------------------------------------------------------------------------------| +| `$allowEmailLinks` | Allows adding e-mail links. | +| `$allowAssetLinks` | Allows linking to an asset. | +| `$allowAnchors` | Add a custom text anchor to an internal link. | +| `$internalLinkScope` | Scope to restrict the story selector to. See the Storyblok docs for the pattern format. | +| `$allowedComponents` | Restrict the type of selectable stories. | +| `$allowTargetBlank` | Allow selecting the `target="_blank"` option in the editor. | +| `$allowCustomAttributes` | Allow entering custom link attributes in the editor. | @@ -241,12 +248,13 @@ Field to edit formatted text content. #### Custom Options -| Option | Description | -|----------------------|-------------------------------------------------------------------------------------| -| `$maxLength` | Restrict content length. | -| `$allowedComponents` | Restrict the type of embeddable components. | -| `$toolbarOptions` | Toolbar buttons / features to enable in the editor. Use the `RichTextStyling` enum. | -| `$styleOptions` | Custom selectable inline styles. | +| Option | Description | +|---------------------------------------------|-------------------------------------------------------------------------------------------------| +| `$maxLength` | Restrict content length. | +| `$allowedComponents` | Restrict the type of embeddable components. | +| `$toolbarOptions` | Toolbar buttons / features to enable in the editor. Use the `RichTextStyling` enum. | +| `$styleOptions` | Custom selectable inline styles. | +| `$automaticallyTransformNonRichTextContent` | Accept string input and transform it to Rich Text data. Useful for migrations from `TextField`. | The `$styleOptions` are inline styles, that will be set as class names on the surrounding inline tag when rendering. diff --git a/docs/php/symfony/storyblok/components/index.mdx b/docs/php/symfony/storyblok/components/index.mdx index 50e29b5..4fca455 100644 --- a/docs/php/symfony/storyblok/components/index.mdx +++ b/docs/php/symfony/storyblok/components/index.mdx @@ -210,3 +210,37 @@ class PageStory extends Story } } ``` + +### Story Metadata + +Every story also contains metadata from Storyblok that you can access via `getMetaData()`. + +```php +$metaData = $story->getMetaData(); +``` + +`StoryMetaData` provides these accessors: + +| Method / Property | Description | +|-----------------------------------|-----------------------------------------------------------------------------------------------------| +| `spaceId` | Storyblok space id of the current story. | +| `getType()` | Component key (document type) of the story. | +| `getId()` | Numeric story id. | +| `getUuid()` | Stable UUID of the story. | +| `getName()` | Display name of the story in Storyblok. | +| `getSlug()` | Last slug segment (without parent path). | +| `getFullSlug()` | Full story slug path. | +| `getParentSlug()` | Parent slug path without trailing slash, or `null` for root entries. | +| `getSlugSegments()` | Full slug split into path segments. | +| `getLocale()` | Locale as provided by Storyblok (`lang`). Normally just `"Default"`, as we don't use these locales. | +| `getLocaleFromSlug()` | Locale inferred from slug / folder at the configured locale level, if valid. | +| `getCreatedAt()` | Creation timestamp (`DateTimeImmutable`). | +| `getFirstPublishedAt()` | First publish timestamp or `null` if never published. | +| `getPublishedAt()` | Latest publish timestamp or `null` if not published. | +| `isStartPage()` | Whether this story is marked as start page. | +| `getPosition()` | Optional folder position used for sorting in Storyblok. | +| `getAlternateLanguages()` | Raw alternate language entries including inferred locale. | +| `getTranslatedDocumentsMapping()` | Locale-to-full-slug mapping for translated alternates. | +| `getPreviewData()` | Raw `_editable` preview marker used for Storyblok visual editing. | + +This is useful for routing, locale switching and backend preview integrations. diff --git a/docs/php/symfony/storyblok/more-features/index.mdx b/docs/php/symfony/storyblok/more-features/index.mdx index 8cddde9..4671adf 100644 --- a/docs/php/symfony/storyblok/more-features/index.mdx +++ b/docs/php/symfony/storyblok/more-features/index.mdx @@ -11,3 +11,4 @@ In special cases, they can be used to implement custom requirements in your appl - [Backend Edit URL Helper](./backend-edit-url-helper) - [Request Validator](./request-validator) - [ID Slug Mapper](./id-slug-mapper) +- [Rich Text Transformers](./rich-text-transformers) diff --git a/docs/php/symfony/storyblok/more-features/rich-text-transformers.mdx b/docs/php/symfony/storyblok/more-features/rich-text-transformers.mdx new file mode 100644 index 0000000..4c2bdc2 --- /dev/null +++ b/docs/php/symfony/storyblok/more-features/rich-text-transformers.mdx @@ -0,0 +1,37 @@ +# Rich Text Transformers + +The bundle ships additional helpers for converting between Storyblok Rich Text JSON and HTML. + +These are mainly useful when integrating translation flows or content migrations. + +## `RichTextHtmlTransformer` + +This helper converts in both directions: + +- Rich Text JSON markup to HTML +- HTML to Rich Text JSON markup +- Rich Text JSON markup to plain text + +```php +use Torr\Storyblok\Tiptap\Transformer\RichTextHtmlTransformer; + +public function example (RichTextHtmlTransformer $transformer) : void +{ + $html = $transformer->transformToHtml($jsonMarkup); + $json = $transformer->transformToJsonMarkup($html); + $text = $transformer->transformToPlainText($jsonMarkup); +} +``` + +## `HtmlToRichTextTransformer` + +If you only need one-way conversion from HTML to Rich Text array data (for example while migrating old text data), you can use: + +```php +use Torr\Storyblok\RichText\HtmlToRichTextTransformer; + +$data = (new HtmlToRichTextTransformer()) + ->parseHtmlToRichText("

Hello

"); +``` + +The method returns Rich Text data as array or `null` if the input could not be parsed.