Skip to content

Add more storyblok docs #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
apfelbox merged 1 commit into from
Mar 23, 2026
Merged

Add more storyblok docs #63

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions blog/2026-03-23-storyblok-advanced-field-docs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
27 changes: 27 additions & 0 deletions docs/php/symfony/storyblok/api/content-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()`
52 changes: 30 additions & 22 deletions docs/php/symfony/storyblok/components/fields.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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. |



Expand Down Expand Up @@ -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.

Expand Down
34 changes: 34 additions & 0 deletions docs/php/symfony/storyblok/components/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
1 change: 1 addition & 0 deletions docs/php/symfony/storyblok/more-features/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
37 changes: 37 additions & 0 deletions docs/php/symfony/storyblok/more-features/rich-text-transformers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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("<p>Hello</p>");
```

The method returns Rich Text data as array or `null` if the input could not be parsed.
Loading