メインコンテンツまでスキップ

14. チュートリアルと実践

初級チュートリアル​

Lucy Studioが初めてなら、まずは下のチュートリアルから始めてください。画面を1つ最初から最後まで作りながら、ウィジェットの配置、プロパティの設定、スクリプトの作成といった中心的な流れを10〜15分で身につけられます。

外部APIでアプリを作る​

公共API連携の例 — 韓国のお祭り情報（Korea Festival）​

公共データポータルが提供するお祭り情報の公共APIを連携して作った一覧画面です。ListViewでお祭りの写真とお祭り名（韓国語／英語）、位置、ContextID、最終更新日を表示し、下部にページネーション（1 / 14）を置いて次のページを読み込めるように構成しています。

この画面は、Lucy StudioのTutorial01プロジェクトをCloneしたあと、**16_Tutorials**フォルダに保存された.lfpファイルを参照できます。

一覧のお祭りの行（row）をクリックすると、画面右側に詳細情報を表示するSideパネル（End Drawer）が開くようにスクリプトを構成しています。

function lsvPlace_onSelected(idx)
{
  $log.e("selected : " + idx);
  lsvPlace.current = idx;
  
  const filename = "16_Tutorials/Tutorial_API_SIDE";
  $form.openEndDrawer(filename, {data:txtContextID.text, width:300});

  showFlag = !showFlag;
}

lsvPlace_onSelected(idx)は、ListViewlsvPlaceで行を選択したときに呼び出されるイベント関数です。選択したインデックスをlsvPlace.currentに保存したあと、$form.openEndDrawer()で16_Tutorials/Tutorial_API_SIDE画面を右側のSideパネルとして開き、選択した行のtxtContextIDのテキスト値をdataパラメータとして渡すことで、詳細画面でそのまま使えるようにします（widthはパネルの幅、showFlagは開いている／閉じている状態を示すトグル変数です）。

備考

公共APIとは？ 政府・自治体・公共機関が公共データポータル（data.go.kr）などを通じて無料で提供するREST APIです。多くの場合、会員登録後に申請すると発行されるサービスキー（認証キー）をリクエストに含めないと呼び出せません。

Lucy Studioで外部APIを呼び出す​

画面（ページ）スクリプトから、$httpグローバルオブジェクトでREST APIを直接呼び出せます。get / post / put / patch / delete / head / options / multipartメソッドを提供しており、すべてのメソッドはコールバック関数を(ステータスコード, レスポンスヘッダー, レスポンスボディ)の3つの引数で呼び出します。レスポンスボディは文字列として渡されるため、JSONレスポンスの場合はJSON.parse()で自分でパースする必要があります。

$http.get(
  "https://apis.data.go.kr/B551011/EngService2/searchFestival2" +
    "?serviceKey=YOUR_SERVICE_KEY&MobileOS=ETC&MobileApp=LucyStudio&_type=json" +
    "&numOfRows=10&pageNo=1",
  {},
  function (status, headers, body) {
    if (status !== 200) {
      $log.i("API Error! : " + status);
      return;
    }
    var items = JSON.parse(body).response.body.items.item;
    $log.i("Received item count : " + items.length);
    // itemsをListViewに表示する方法は以下を参照
  }
);
警告

$httpリクエストは非同期で処理されます。レスポンスが届く前に画面が先に描画されることがあるため、ウィジェットの更新は必ずコールバック関数の中で実行してください。

レスポンスで受け取った項目の配列は、$httpコールバックの中で直接ループしながらListViewに追加していきます。以下は韓国観光公社のお祭り情報APIレスポンスのフィールドを実際のウィジェットのプロパティに代入するコードで、lsvPlace.clear()で既存の一覧をクリアしたあとitems配列をループし、lsvPlace.add()で行を追加してlsvPlace.currentでその行を指定しながら各ウィジェットのプロパティを設定します。

lsvPlace.clear();
    for (var i = 0; i < items.length; i++) {
      var item = items[i];
      if (!item) continue;

      lsvPlace.add();
      lsvPlace.current = i;
      
      txtTitle.text     = (item.title  || "");
      txtAddr.text      =  (item.addr1  || "");
      txtContentID.text = (item.contentid || "");
      imgFirst.setProperty("image.url", item.firstimage || "");
      txt_startDate.text = item.eventstartdate;
      txt_endDate.text = item.eventstartdate;  
    }

同じAPIを複数の画面で繰り返し呼び出したり、リクエスト／レスポンスの構造を保存して再利用したりしたい場合は、毎回$httpで直接呼び出す代わりに、StudioのProvider機能で登録しておく方法もあります。Providerとそれを画面に接続する方法は、下の金融・ビジネスアプリの例セクションで扱います。

金融・ビジネスアプリの例​

備考

**Provider（データプロバイダー）**は、REST APIやソケットなどの外部データソースに名前を付けてStudioに登録しておくものです。**DataSet（データセット）**は、そのProviderがやり取りするデータ構造（リクエスト／レスポンススキーマ）を、画面のウィジェットに繰り返しバインディングできる形で取り出したものです。1つのProviderを複数のDataSet・複数の画面で再利用できます。

一般的な利用の流れは次のとおりです。

  1. Providerの登録 — 名前、呼び出しURL、HTTPメソッド、リクエスト／レスポンススキーマを入力して、データソースを1つ作ります。リアルタイム相場のように、サーバーが値を継続的に送ってくる（push）ソースも登録できます。
  2. DataSetの作成 — 新しくスキーマを作るか、すでに作ったProviderのレスポンススキーマをそのまま取り込んで（Quick Create）DataSetを作ります。
  3. ウィジェットへのバインディング — DataSetのフィールドを画面のウィジェット（テキスト、テーブル、チャートなど）にドラッグして接続すると、Providerが受け取った値が変わるたびにウィジェットが自動で更新されます。

リアルタイム相場画面の例（証券会社Provider連携）​

証券会社が提供するProviderをDataSetに接続して、リアルタイム相場データを画面にバインディングした例です。上のLiveStockPrices画面のように、Providerが受信した値がDataSetを通じてリアルタイムに画面へ更新される構造です。

この画面は、Lucy StudioのTutorial01プロジェクトをCloneしたあと、**16_Tutorials**フォルダに保存された.lfpファイルを参照できます。

警告

この画面はLucyStudioのDataSetの概念を適用した例であり、現在のClosed AlphaバージョンにはDataSet/Provider機能が反映されていません。