Merge branch 'release/1.0.20'

Author: RicLeP

.idea/laravel-storyblok-docs.iml

@@ -33,8 +33,9 @@
     */
 
 	'versions'      => [
-		'default'   => '2.21',
+		'default'   => '2.23',
 		'published' => [
+			'2.23',
 			'2.21',
 			'2.20',
 			'2.19',

config/larecipe.php

@@ -0,0 +1,42 @@
+# Assets
+
+---
+
+- [Custom asset domains](#custom-domains)
+
+Assets are a special type of Field with additional functionality. Where possible to try to detect the type of file upload and return an appropriate Field. `Image` classes are returned when the file has one of the following extensions: ‘.jpg’, ‘.jpeg’, ‘.png’, ‘.gif’, ‘.webp’. See the [Image documentation](/{{route}}/{{version}}/images) for more.
+
+
+## Checking for a file
+
+To check if a file has been uploaded in Storyblok call `hasFile()` on the Asset.
+
+```php
+$myAsset->hasFile();
+```
+
+> {info} When using multi-asset fields we only receive a URL from Storyblok the Asset|Image fields are less complete.
+
+
+<a name="custom-domains">
+## Custom asset domains
+</a>
+
+Storyblok allows you to serve assets from their platform using a custom domain. You will need to define two configuration values in your `storyblok` config file:
+
+```php
+[
+    // rest of configuration
+    `asset_domain` => 'custom.asset.domain',
+    `image_service_domain` => 'custom.imageservice.domain'
+]
+```
+
+The configuration to customise both domains is needed because:
+
+- Storyblok links a CloudFront distribution directly to the S3 bucket, bypassing the image service.
+- Non-image assets cannot pass through the image service, so you cannot pass all asset requests through img2.storyblok.com
+
+> {info} [See Storyblok’s documentation on setting up the custom asset domains](https://www.storyblok.com/docs/custom-assets-domain).
+
+Thank you to [Brent Mullen](https://github.com/brentmullen) for this feature!

resources/docs/2.23/assets.md

@@ -0,0 +1,110 @@
+# Basic usage
+
+---
+
+- [Determining the view to use](#determining-view)
+- [Determining the Page class](#the-page-class)
+- [Available data](#available-data)
+- [Using draft content](#draft-content)
+
+
+Once [installed](/{{route}}/{{version}}/installation) you can start working with Storyblok in your Laravel application just by creating the appropriate Blade views.
+
+The package will consume Storyblok’s JSON responses and automatically convert them to nested PHP objects. The type of object created can be set just by matching the filename to that of the Storyblok component. This is covered in more detail in the [blocks documentation](/{{route}}/{{version}}/blocks).
+
+The best way to understand this is to `dd($story)` in Blade file and check out the document structure.
+
+Create the following folder `resources/views/storyblok/pages`, this is the default location where you will store all of your Blade views but you are free to use any structure you want. You can read more about how the package selects which view is loaded and how to define your own rules in the [views documentation](/{{route}}/{{version}}/views).
+
+> {info} You can change the default view path in the `storyblok.php` configuration file
+
+---
+
+<a name="determining-view">
+## Determining the view to use
+</a>
+
+Every `Page` has a `views()` method that returns an array of possible views to pass to Laravel’s `view()->first()` function ([see the Laravel docs](https://laravel.com/docs/7.x/views)). The package looks for a Blade file matching the name of the [Content Type](https://www.storyblok.com/docs/the-key-concept#content-types) component used for the current page in Storyblok, that doesn’t exist then `page.blade.php` will be tried.
+
+If you have a Content Type component called `episode` being used for the page then it will look for an `episode.blade.php` file in `resources/views/storyblok/pages`.
+
+Each `Block` implements `views()` and  `render()` methods that will give you a list of possible views to use and render the block. You can read more about this in the [blocks documentation](/{{route}}/{{version}}/blocks).
+
+---
+
+<a name="the-page-class">
+## Determining the Page class
+</a>
+
+By default it uses the `App\Storyblok\Page` class. To provide your own object for the page create a class in `App\Storyblok\Pages` and name it as the Studly case version of the Content Type from Storyblok. Be sure to extend `Riclep\Storyblok\Page` or the website’s default `Page` if you want common functionality.
+
+In the `episode` example above you’d create an `Episode` class like so:
+
+```php
+<?php
+// episode.php
+
+namespace App\Storyblok\Pages;
+
+class Episode extends App\Storyblok\Page
+{
+
+}
+```
+
+<a name="available-data">
+## Available Data
+</a>
+
+The selected view will be passed the complete `Page` object in a variable called `$story` which contains all the processed data for the current page. To display your content just print it to the screen, if our Episode has fields for `title`, `text` and a `nested` field containing child blocks we’d access them as so:
+
+```html
+<main>
+    <header>
+        <h1>{{ $story->title }}</h1>
+    </header>
+
+    <section>
+        {{ $story->text }}
+
+        <div>
+        	{{ $story->nested[0]->name }}<br>
+        	{{ $story->nested[0]->role }}
+        </div>
+    </section>
+</main>
+
+```
+
+If the `text` field was rich-text it would automatically be converted in a `Riclep\Storyblok\Fields\RictText` class. Printing it to screen will automatically covert it to HTML.
+
+The nested blocks will be transformed into `App\Storyblok\Block` classes and all of their fields processed and converted. You can of course override this. If the JSON for the block looked like this:
+
+```json
+{
+    "name": "Richard Le Poidevin",
+    "_uid": "xxx",
+    "role": "Host",
+    "component": "person",
+    "_editable": "xxx"
+}
+```
+
+Creating a class called `Person` in `App\Storyblok\Blocks` would make this block become that type. Within this block you are free to manipulate the data and fields as desired.
+
+
+
+<a name="draft-content">
+## Using draft content
+</a>
+
+By default Storyblok will only load draft content when inside their visual editor. Sometimes it’s helpful to have access to draft content during development. To load draft content outside of the editor make a new .env variable like so.
+
+```php
+STORYBLOK_DRAFT=true
+```
+
+> {warning} Be careful not to use draft content in production! Either remove the env variable or set it to false.
+
+
+Every time you publish in Storyblok the webhook will clear Laravel’s cache but the package provides a `storyblok.clear-cache` route if you need to do this manually in your code. You can of course clear the cache with Artisan too. If you’re using a taggable Cache driver the package uses the `storyblok` tag.