LoginSignup
1
0

More than 5 years have passed since last update.

@si-gma

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

Last updated at Posted at 2018-09-05

第二弾

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

ジェネラル

はじめよう

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

storyblok.jpg

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

チュートリアルとボイラープレートの全リストは、getting started landing pageをご覧下さい。

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

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

インストール

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

アップデート

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

しかし、私たちのAPIは幾つかのバージョンに分かれていて、大きな変更が必要な場合は新しいメジャーバージョンを作成し、アップグレード手順を公開します。しかし今日まで、そのようなメジャーアップデートは一度も行われていません。安定性は私たちのコアバリューの一つというわけです。より詳しく知りたい場合は、Public 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を使用しています。これを有効にするためには、app.storyblok.comへのページの埋め込みを許可する必要があります。この設定は通常デフォルトで行われるため、多くの場合は何も設定する必要はありません。もちろん、ビジュアルコンポーザ無しでStoryblokを使用することもできます。

Storyblok Bridge

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

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

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


<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を保存・公開したら速やかにページをリロードさせられます。

// ?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できる:


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

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

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

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

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

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

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

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から確認できる。

例


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

storyblok.isInEditor() and pingEditor()

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

例


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: エラー時のコールバック

例


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: エラー時のコールバック

例


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である場合の、よりセキュアなチェックの例の幾つかです。

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 
}

$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

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
0