第1章 デベロッパーポータル

本セクションを完了すると、デベロッパーポータルの構造、使用方法、および機能を理解することができます。

実際のブランディングに合わせて、デベロッパーポータル全体の外観や操作感をカスタマイズできます。ポータルのすべての要素を完全に制御できるので、開発者に API の使用方法を容易に理解してもらうことができます。API デベロッパーポータルが適切に作成されていれば、開発者はコンセプトをごく短時間のうちに実際のアプリケーションに具体化することができます。

1.1. デベロッパーポータルの概要

デベロッパーポータルの構成要素は以下のとおりです。

  • 左側のメニュー: Content、Drafts、Redirects、Groups、Feature Visibility、ActiveDocs、Legal Terms、Settings、および Liquid のドキュメントにアクセスできます。
  • メインエリア: 上記セクションの詳細が表示されます。
Developer portal page overview

1.2. Content

このセクションは、デベロッパーポータルシステムのビューで最も重要な部分です。Content セクションにはサイト構造と階層が表示され、またページ内のコンテンツを編集することができます。つまり、サイト構造、ページ、およびそこに保存されたその他のアセットを管理できます。ポータルの階層は、ディレクトリーツリーの形式で表示されます。

Developer portal content page

上記の図は、Content セクション内のあるページのサンプルビューを示しています。図に示すように、サイトのパス階層を維持したまま、すべてのファイル (ページ、イメージ、スタイルシート、JavaScript など) が表示されます。前述のように、セクションは機能的にディレクトリーと同じです。

右側には、ページ編集ビューが表示されます。ここにはページ名 (標準ページか組み込みページかどうかも示されます) と、コンテンツに新しい要素 (ページ、レイアウト、パーシャル、セクション、またはファイル) を追加するためのボタンが表示されます。その下では、ページで使用するレイアウトを選択したり、Liquid タグの機能を切り替えたりすることができます。それに続く部分はテキストエディターで、コードの強調表示、表作成、行番号など多くの機能に対応しています。タブボタンの Draft と Published を使用すると、編集したドキュメントのドラフトバージョンと公開バージョンが切り替わります。それに続くのは、ドキュメントのバージョンを一覧表示するアイコン、およびポップアップ編集ウィンドウを開くアイコンです。

ページのコンテンツを編集するには、目的のレイアウトを選択し、コンテンツタイプや URL パスなどのいくつかの追加オプションを設定してから、HTML、Markdown、または Textile 形式でコードを入力するだけです。

このビューのもう 1 つの重要な機能は、Preview ボタンです。ページの公開バージョンまたはドラフトバージョンをプレビュー表示するかどうかを選択できます。ボタンをクリックするとデベロッパーポータルモードにリダイレクトされ、レンダリングされたページの公開 (またはドラフト) バージョンと共に、ダークグレーの縦長のバーが表示されます (右側)。このバーには、デベロッパーポータルのページ、レイアウト、およびパーシャルの編集ビューへのリンクが含まれています。ここでは、ドラフトと公開ビューを切り替えることができます。

Developer Portal preview mode

フィルター機能もあり、検索フィールドとして機能するだけでなく、表示される要素をスタイルシート、JavaScript またはその他の指定タイプのみに制限することができます。

Find content in Developer Portal

1.3. Layouts および Partials

Layouts および Partials セクションでは、テンプレートとページの再利用可能な部分を管理します。それらの機能は Content セクションの機能に類似しています。

Layouts セクションは、ページで使用されるテンプレートの定義で構成されます。レイアウトはページの主要構造で、このテンプレートのコンテンツが、そのレイアウトを使用するすべてのページでレンダリングされます。ページのパーシャルおよび実際のコンテンツがテンプレートの内部に存在します。

パーシャルとは、コードの再利用可能な部分で、異なるページの多くの場所に適用できます。たとえば、フッターはどのレイアウトでも同じで、サイドバーもレイアウトが異なるものの、複数ページで同じものが使用されます。

レイアウト、パーシャル、またはメールテンプレートにパーシャルを含めるには、以下のコマンドを使用します。

{% include "partial_name" %}

ポータルの他の部分と同様、レイアウトとパーシャルにもドラフトと公開の状態があり、以下の機能を含む、完全なバージョン履歴を確認できます。

  • レイアウトテンプレート用のテキストエディター
  • ドラフトを保存する、現在のバージョンを公開する、最後の公開バージョンに戻すことができます。
  • テキストエディターをドラフトバージョンと公開バージョンで切り替える、バージョン履歴を一覧表示する、ポップアップエディターを起動することができます。
Developer portal layout highlight

Liquid タグの詳細ガイドは、『Liquid Reference』を参照してください。

1.4. Redirects および Changes

デベロッパーポータルの最後の要素は、Redirects セクションと Changes セクションです。これらは、Content セクションよりもかなりシンプルですが、やはり重要なセクションであり、いくつかのカスタム機能を利用することができます。

Redirects は、あるポータル URL から別のポータル URL へのリダイレクトを設定するのに役立ちます。これは、たとえば古いページを非推奨にするが、すべてのリンクを変更したくない場合に便利です。Redirects は組み込みのデベロッパーポータルページには使用できません。自分で作成したページにしか使用することはできません

最後の Changes セクションも重要です。ここには新しく編集され公開されていないすべてのページの一覧が含まれ、個別に公開するか、すべてを 1 度に公開するかを選択できます。

1.5. ローカルアセットの更新

本セクションでは、デベロッパーポータルのローカルアセット更新の詳細について説明します。その際のベースを以下に示します。

  • 3scale 2.8 から、新しいデベロッパーポータルはすべて cdn_asset タグを使用して作成されます。
  • 既存のデベロッパーポータルインスタンスについては、cdn_asset タグを使用してアセットを更新する必要があります。この機能により、他の Web サイトからダウンロードする必要のあるアセットへの依存がなくなりました。すべての外部アセットがコンテンツ配信ネットワーク (CDN) からコードベースに移行されたためです。

したがって、既存のデベロッパーポータルインスタンスを更新し、新しいローカルアセットを使用するには、以下の手順に従います。

  1. Audience > Developer Portal > Content の順に移動します。
  2. ウィンドウの左側にあるメニューリストから、Main layout を選択します。

    Developer Portal: main layout
  3. {{ '//netdna.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.css' | stylesheet_link_tag }}

    {% cdn_asset /font-awesome/4.3.0/css/font-awesome.css %} に置き換えます。

  4. {{ '//ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js' | javascript_include_tag }}

    {% cdn_asset /jquery/1.7.1/jquery.min.js %} に置き換えます。

  5. Publish をクリックし、続いて Save をクリックします。
  6. ウィンドウの左側にあるメニューリストから、Partials を選択します。
  7. stats/chart を選択します。

    Developer Portal: main layout
  8. {{ '//ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/themes/ui-lightness/jquery-ui.css' | stylesheet_link_tag }}

    {% cdn_asset /jquery-ui/1.11.4/jquery-ui.css %} に置き換えます。

  9. Publish をクリックし、続いて Save をクリックします。

上述のインスタンス (Main layout および stats/chart) をベースに他のインスタンスファイルを作成している場合は、それらも更新する必要があります。詳細は、porta での Liquid タグ についてのドキュメントを参照してください。