Storyblokのdocs翻訳チャレンジその2！！！

# 第二弾

GENERALのGetting started, Installation& Updates, The Storyblok JS Bridgeの翻訳にチャレンジしました。

# ジェネラル

## はじめよう

Storyblokを始める最も簡単な方法は、app.storyblok.comにアカウントを作り、新しいspaceを作った後、下記の手順に従うことです。

![storyblok.jpg](https://qiita-image-store.s3.amazonaws.com/0/157765/4e5514eb-3118-26e3-a68e-c28bf8e7a309.jpeg)


私たちは私たちの作成したチュートリアルを読み、Storyblokの機能について、より詳細な理解を得ることを推奨しています。

* [How to build a full blown website with Nuxt.js, Vue.js and Storyblok](https://www.storyblok.com/tp/nuxt-js-multilanguage-website-tutorial)
* [How to build a full blown website with Next.js, React and Storyblok](https://www.storyblok.com/tp/next-js-react-guide)
* [How to use Storyblok with Gatsby](https://www.storyblok.com/tp/gatsby-multilanguage-website-tutorial)
* [How to use Storyblok with Ruby on Rails and Spree Commerce](https://www.storyblok.com/tp/headless-cms-spree-commerce)
* [How to build a Grid](https://www.storyblok.com/tp/cms-grid-component-layout)
* [How to build Navigations](https://www.storyblok.com/tp/cms-website-header-menu-navigation)

チュートリアルとボイラープレートの全リストは、[getting started landing page](https://www.storyblok.com/getting-started)をご覧下さい。

https://www.storyblok.com/docs/Guides/Getting-Started

# インストールとアップデートの要件

Storyblokは外部に全く依存しません。あなたのシステムがGETリクエストを実行可能であれば準備完了です。

## インストール

StoryblokがSaaS CMSであることから、やらなければならないインストール手順はありません。サインアップしてログインし、何かを作るだけで使う準備は完了です。しかし、あなたがたが私たちのSideBySideエディタを、Storyblokコンポーネントで構成されるあなたのWebサイトにおいて使いたいのであれば、[Storyblok JavaScript Bridge](https://www.storyblok.com/docs/Guides/storyblok-latest-js)を追加する必要があります。

## アップデート

先に示した通り、Storyblokを用いて維持した場合、従来のCMSや内製のCMSと比べて、必要な作業が大幅に少なくなります。例えば、新機能のリリースにともなうダウンタイムについて、あなたは何も考える必要はありません。

しかし、私たちのAPIは幾つかのバージョンに分かれていて、大きな変更が必要な場合は新しいメジャーバージョンを作成し、アップグレード手順を公開します。しかし今日まで、そのようなメジャーアップデートは一度も行われていません。安定性は私たちのコアバリューの一つというわけです。より詳しく知りたい場合は、[Public Roadmap](https://trello.com/b/hffvZks5/sb-roadmap)をご覧ください。

# Admin UI要件

StoryblokのAdmin UIを使う際には、Google ChromeのようなモダンなWebブラウザが必要です。

## Windows, Linux&OS X

| ブラウザ | バージョン |
|:--|:--|
| Chrome  | >=29 |
| Firefox | >=29 |
| Safari  | >=10 |
| IE      | >=11 |
| Edge    | >=12 |

## 埋め込みについて

Storyblokは、クリックでそのテンプレートのコンポーネントに飛ぶために[iframe bridge](https://www.storyblok.com/docs/Guides/storyblok-latest-js)を使用しています。これを有効にするためには、app.storyblok.comへのページの埋め込みを許可する必要があります。この設定は通常デフォルトで行われるため、多くの場合は何も設定する必要はありません。もちろん、ビジュアルコンポーザ無しでStoryblokを使用することもできます。

https://www.storyblok.com/docs/requirements-installation-updates

# Storyblok Bridge

StoryblokとWebサイトの間に[bridge](https://www.storyblok.com/feature/visual-composer)を渡すためには、スクリプトをインクルードする必要があります。このスクリプトはiframe経由でStoryblokと通信し、ユーザーがコンポーネントをクリックしたときにどれを開く必要があるかを、編集インターフェースに伝えます。

これは、draft JSONからコンポーネント毎に`_editable`キーを追加することによって送られた要素の手前にて、シンプルなHTMLコメントを用いて実行されます。

## スクリプトをWebページの`<body>`タグにてインクルード


```html

<script src="//app.storyblok.com/f/storyblok-latest.js?t=YOUR_TOKEN" type="text/javascript">
</script>
```

spaceのdashboardからpreview token(=YOUR_TOKEN)を見ることができます。ユーザーがedit modeでない場合、`<script>`を状況に応じて除外することもできます。

edit modeかどうかチェックする方法は:

* URLパラメーターの`_storyblok`をチェックする
* cookieをチェックする(cookieはURLに`_storyblok`がある最初の時に設定できます)

## 使い方

以下のサーバでレンダリングされるWebサイト用のコードで、ユーザがStoryを保存・公開したら速やかにページをリロードさせられます。

```javascript
// ?tパラメータをscriptタグを使ってまだ投げていない場合はinitが必要。
storyblok.init({
  accessToken: 'your_token'
})

storyblok.on(['published', 'change'], function() {
  location.reload(true)
})

storyblok.pingEditor(function() {
  if (storyblok.inEditor) {
    storyblok.enterEditmode()
  }
})
```

## Events

`on`ハンドラでイベントをlistenできる:


```javascript

storyblok.on('event_name', function(data) {
  console.log(data);
})
```

`published`イベントの場合は、このようになる:


```javascript
storyblok.on('published', function(data) {
  console.log(data);
  // invalidate cache, ...
})
```

appのSyncButtonの場合は特殊なイベントとしてlisten可能:

```javascript
storyblok.on('customEvent', function(data) {
  if (data.event == 'start-sync') {
    // Do sync
  }
})

```

**Storyのslugを変更した後、404 errorになってしまった**

StoryblokをSSR(serverside rendering)で使用しコンテンツを変更する度にリロードしたい場合、slugChanged属性について追加でチェックする必要があります。これでslugを変更してもページは404 errorを投げない状態になるはずです。


```javascript
storyblok.on(['published', 'change'], function(event) {
  if (!event.slugChanged) {
    location.reload(true)
  }
})
```

| イベント | 発生するタイミング |
|:--|:--|
| input         | fieldの値が変わった後 |
| change        | contentが保存された後 |
| published     | ユーザーがpublishedをクリックした後 |
| unpublished   | ユーザーがunpublishedをクリックした後 |
| enterEditmode | edit modeのときエディタが初期化されていた場合、その後 |
| customEvent   | カスタムイベント、サードバーティのプラグインで使用 |

## 関数

### storyblok.init(config)

`config` Object

* `accessToken` 文字列: コンテンツのdraftバージョンを受け取るためのコンテンツ・デリバリAPIのプライベートトークン。`http://app.storyblok.com`のspaceのdashboardから確認できる。

**例**

```javascript

storyblok.init({
  accessToken: 'xf5dRMMjltLzKOcNgMaU9Att'
})
```

### storyblok.isInEditor()  and  pingEditor()

これらの関数で、Storyblok内にあるページが開かれているかをチェックできます。

**例**

```javascript

storyblok.pingEditor(() => {
  if (storyblok.isInEditor()) {
    // getStory('draft')
  } else {
    // getStory('published')
  }
})
```

### storyblok.get(query, success, error)

コンテンツエントリを一つフロントエンドへgetします。

* `query` Object
 * `version` String: draftもしくはpublished。デフォルトはpublished

* `success` Function: 成功時のコールバック
* `error` Function: エラー時のコールバック

**例**

```javascript

storyblok.get({
  slug: 'home', 
  version: 'draft'
}, (data) => {
  var story = data.story
})
```

### storyblok.getAll(query, success, error)

コンテンツエントリを複数getする。

* `query` Object
 * `with_tag` String
 * `starts_with` String
 * `version` String
 * `sort_by` String
 * `filter_by` String
 * `per_page` String
 * `page` String
* `success` Function: 成功時のコールバック
* `error` Function: エラー時のコールバック

**例**

```javascript

storyblok.getAll({
  version: 'draft'
}, (data, xhrResponse) => {
  var total = xhrResponse.getResponseHeader('Total')
  var stories = data.stories
})
```

## ユーザーがStoryblokエディタにてサイトを見ている場合のバリデーションをどうするか

ユーザーがあなたのページをStoryblokで開く場合、私たちはedit modeを使う際のセキュアなバリデーションのために使えるパラメータを幾つか用意しました。

あなたのコンテンツの正しいバージョンを、正規のユーザーがロードするためにバリデーションをする必要が出てくるでしょう。`draft`バージョンは編集者のためのパラメータで、`published`バージョンはパブリックにするためのパラメータです。

シンプルなバリデーションはURLの`_storyblok`パラメータをチェックすることで行えます。これはフロントエンドでもバックエンドでも行うことができます。しかし、よりセキュアなチェックである、バックエンドにロジックを実装し、`_storyblok_tk`パラメータをバリデーションする手法を、私たちはオススメします。

これが、ユーザーがedit modeである場合の、よりセキュアなチェックの例の幾つかです。

```javascript
import crypto from 'crypto'
// getQueryParam = access requests URL param by name

let validationString = getQueryParam('_storyblok_tk[space_id]') + ':' + YOUR_PREVIEW_TOKEN + ':' + getQueryParam('_storyblok_tk[timestamp]')
let validationToken = crypto.createHash('sha1').update(validationString).digest('hex')
if (getQueryParam('_storyblok_tk[token]') == validationToken && 
    getQueryParam('_storyblok_tk[timestamp]') > Math.floor(Date.now()/1000)-3600) { 
    // you're in the edit mode.
    this.editMode = true 
}
```

```php
$sb = $app['request']->query->get('_storyblok_tk');
if (!empty($sb)) {
    $pre_token = $sb['space_id'] . ':' . YOUR_PREVIEW_TOKEN . ':' . $sb['timestamp'];
    $token = sha1($pre_token);
    if ($token == $sb['token'] && (int)$sb['timestamp'] > strtotime('now') - 3600) {
        $app['config.storyblok.edit_mode'] = true;
        // you're in the edit mode.
    }
}
```

URLに追加出来るStoryblokのパラメータは:

| パラメータ | 説明 |
|:--|:--|
| _storyblok | コンテンツエントリのID |
| _storyblok_tk[space_id] | spaceのID |
| _storyblok_tk[timestamp] | タイムスタンプ |
| _storyblok_tk[token] | バリデーショントークン。space_id,timestamp,preview_tokenと紐付けられている。 |

https://www.storyblok.com/docs/Guides/storyblok-latest-js