コンテンツにスキップ

Panelアプリキット

すべてのサーバーPanelアプリには、plaidcloud_panelキットがインストールされています。このキットは、ライトとダークの両方で、プラットフォームの他の部分と同じ色、書体、余白というPlaidCloudの外観をアプリに与え、フィルター、主要な数値、大規模なデータグリッド、チャート、フォームなど、ほとんどのアプリで必要な画面向けのコンポーネントを提供します。アプリは、プロジェクトのブランディングを自動的に取得します。

import plaidcloud_panel as pcp

キットをインポートすると、PlotlyとMatplotlibのチャートにもPlaidCloudの外観が適用されます。

Panel Studioでは、新規アプリ > Studioから、空のアプリ、テーブルまたはビュー、別のStudioアプリ、ギャラリーのアプリのいずれかから、コマンドを実行することなく開始できます。

gitリポジトリで管理するアプリ向けに、キットには、動作するスターターアプリを書き出すコマンドが含まれています。任意のフォルダーから実行し、テーブル名と列名を編集してください。

ターミナルウィンドウ
plaidcloud-panel new --layout dashboard --title "Sales" --table sales --filters region,year --measure amount
オプション 内容
--layout dashboard サイドバーにフィルター、2つの主要な数値、チャート。
--layout explorer サイドバーにフィルター、行数、行のテーブル。
--table アプリが読み取るPlaidCloudのテーブル。
--filters フィルターに使用する列のカンマ区切りリスト。最初の列がチャートを制御します。
--measure 合計する数値の列。
--dir app.pyとrequirements.txtの書き込み先。デフォルトは現在のフォルダーです。

app.pyがすでに存在する場合、コマンドは何も書き込まずに停止します。2つのファイルをリポジトリにコミットし、サーバーアプリとして公開します。

このアプリは、販売テーブルを地域と年でフィルターし、2つの主要な数値、チャート、一致する行のページ分割されたグリッドを表示します。グリッドでは、金額が桁区切り付きで、利益率がパーセントで表示されます。すべての要素がフィルターに追従します。

import panel as pn
import plaidcloud_panel as pcp
from bokeh.plotting import figure
from plaidcloud.utilities.panel_data import table
pn.extension("tabulator")
sales = table("sales")
bar = pcp.FilterBar(sales, "region", "year")
def by_region(t):
df = t.aggregate(by=["region"], total=("amount", "sum"))
regions = df["region"].astype(str).tolist()
fig = figure(x_range=regions, height=320, toolbar_location=None)
fig.vbar(x=regions, top=df["total"].astype(float).tolist(), width=0.8, color=pcp.series()[0])
return fig
def grid(t):
return pcp.DataGrid(t, key="id", totals={"amount": "sum"}, formats={"amount": "0,0", "margin": "0.0%"})
pcp.App(
"Sales",
sidebar=[bar],
main=[
pn.Row(
pcp.KpiCard("Total amount", bar.table, "amount"),
pcp.KpiCard("Orders", bar.table),
),
pcp.Chart(pn.bind(by_region, bar.table), title="Amount by region"),
pcp.Section("Orders", pn.bind(grid, bar.table)),
],
).servable()

パターンは、キットのどのアプリでも同じです。テーブルに対してFilterBarを作成し、各ビューをbar.tableにバインドします。bar.table(またはウィジェット)にバインドされていないビューは、フィルターが変わっても更新されません。

pcp.App(title, nav=None, *, main=None, sidebar=None, theme_toggle=True, theme=None, commands=None, tour=None)は、アプリのシェルを構築します。タイトル、プロジェクトのロゴ、サインイン中のユーザーを表示するヘッダー、サイドバー、メインエリアで構成されます。結果に対して.servable()を呼び出します。

  • ナビゲーション — nav=[("Overview", overview_page), ("Detail", detail_page)]を渡すと、サイドバーの上部にページメニューが表示されます。各ページは、Panelオブジェクト、またはそれを返す関数です。関数は、ページが選択されたときに実行されます。
  • テーマ — アプリはライトテーマで開きます。ダークテーマで開くにはtheme="dark"を渡すか、URLに?theme=darkを追加します。theme_toggle=True(デフォルト)の場合、ヘッダーにライト/ダークの切り替えスイッチが表示されます。
  • ブランディング — アプリは、セッションの開始時に、プロジェクトのブランドカラーとロゴを読み取ります。ブランディングのないプロジェクトには、PlaidCloudのデフォルトが適用されます。
  • コマンドパレット — Ctrl-K(MacではCmd-K)を押すと、コマンドを検索して実行できます。navのすべてのページが、ページ名の移動として一覧表示され、commands={"Refresh data": refresh}で独自のエントリを追加できます。各エントリは、ラベルと、引数を取らない関数で構成されます。エントリを選択すると、アプリがそれを実行します。
  • 初回起動のツアー — tour=[("Filters", "Narrow the data here."), ("Grid", "Sort and group the rows.")]は、見出しとテキスト1行で構成される各ステップによる、短いステップごとの紹介を表示します。完了またはスキップするまでページの上部に表示され、その後は再表示されません。
  • その他 — その他のキーワード引数は、PanelのFastListTemplateにそのまま渡されます。

pcp.FilterBar(table, "region", "year", amount=pn.widgets.IntInput(name="Amount"))は、指定した列ごとに、検索可能な複数選択ボックスを1つ作成し、その列の個別の値(最大1,000件。リストが切り捨てられた場合は通知されます)を一覧表示します。何も選択されていない場合、ボックスにはすべてと表示されます。その他のものには、列名で独自のウィジェットを渡します。

  • bar.tableは、現在の選択によって絞り込まれたテーブルです。空のウィジェットは、データを絞り込みません。
  • 選択内容はページのURL(?region=EU)に保存されるため、フィルターされたビューをリンクとして共有できます。

pcp.KpiCard(label, source, column=None, fn="sum", fmt="{:,.0f}", drill_to=None)は、主要な数値を1つ表示します。fnはsum、count、avg、min、maxのいずれかで、サーバーがテーブル全体に対して計算します。columnがない場合は、行数が表示されます。数値がフィルターに追従するように、ソースとしてbar.tableを渡します。

drill_to=grid(DataGrid)を渡すと、数値の下にView rowsボタンが追加されます。これを選択すると、グリッドがカード自身のテーブルを参照するようになり、その数値の元になっている行が一覧表示されます。

pcp.DataGrid(source, key="id", totals={"amount": "sum"})は、あらゆるサイズのデータに対応するテーブルビューです。現在のページのみがブラウザーに送信され、ページ送り、並べ替え、合計、エクスポートはすべてサーバーで実行されます。

  • ページ送り — 1ページあたり200、500、または1,000行で、PreviousとNextのボタンと行カウンターがあります。

  • 並べ替え — 列ヘッダーをクリックします。並べ替えは、表示されているページだけでなく、テーブル全体に適用されます。

  • 合計 — totalsは、列をsum、count、avg、min、maxに対応付けます。サーバーが、一致するすべての行に対してそれぞれを計算し、結果をグリッドの最後の行として固定します。

  • エクスポート — CSVとXLSXボタンは、一致するすべての行を、現在の並べ替え順で、export_cap行(デフォルトは100,000行)までダウンロードします。テーブルがそれより大きい場合は、フィルターを絞り込むよう通知されます。=、+、-、@で始まるテキストセルには、スプレッドシートがテキストとして読み取るように、アポストロフィが前に付けられます。

  • 数値の書式 — formats={"margin": "0.0%", "amount": "0,0"}は、numbroの書式文字列を使用して、列ごとの表示形式を設定します。%の書式は100倍されます。合計行にも同じ書式が使用されます。書式のない浮動小数点の列は、桁区切り付きで小数点以下2桁まで表示されます。コピー、CSV、XLSXは、元の値を保持します。

  • キー — keyは、行を一意に識別する列(または列のリスト)です。必ず指定してください。安定したページ送りを参照してください。

  • グループ化 — group_by=["region"]は、グループごとに1行を、totalsのメジャーとrowsの件数(いずれもサーバーが計算)とともに表示し、一致するすべての行に対する合計行も表示します。groupable=["region", "year"]を渡すと、閲覧者が列を選択できるグループ化セレクターが追加されます。グリッドには最大1,000のグループが表示され、リストが切り捨てられた場合は通知されます。グループ行には開くリンクはありません。

  • 条件付き書式 — rulesは、値に応じてセルに色を付けます。各ルールは、column、op(>、>=、<、<=、==、!=、between)、value(betweenの場合は[low, high])、token(success、warning、error、info)を指定します。たとえば、{"column": "margin", "op": "<", "value": 0, "token": "error"}です。合計行には色が付きません。

  • コピー — コピーボタンは、現在のページを、表示されている列と合計行とともに、Excelに貼り付けられるタブ区切りテキストとして、クリップボードにコピーします。

  • Open in PlaidCloud — ソースがPlaidCloudのテーブルの場合、Open in PlaidCloudリンクで、そのテーブルが開きます。

  • 保存された列のレイアウト — layout_key="orders"は、列の選択と並べ替え、一部の列の固定を行うための列とPinnedのセレクターを追加します。各閲覧者の選択は、その名前で保存され、次回アプリを開いたときに復元されます。

  • 行リンク — row_linkは、行を辞書として受け取り、Webアドレスを返す関数で、リンクがない場合はNoneを返します。グリッドには開く列が追加され、リンクのある各行にリンクが表示されます。httpとhttpsのアドレスと、同じサイト内のパスのみがリンクされます。

  • 更新 — grid.refresh()は、同じソースを再度クエリし、ページ、並べ替え、グループ化を保持します。実行がテーブルへの書き込みを完了した後に呼び出してください。

sourceは、テーブル名、またはData APIのテーブルです。グリッドを再フィルターするには、grid.sourceをフィルター済みのテーブルに設定するか、例のようにbar.tableから新しいグリッドを作成します。

グリッドは、閲覧者の行レベルセキュリティの対象です。閲覧者自身の接続を通じて読み取ります。

pcp.Chart(obj, title=None, height=320)は、チャートをタイトル付きのカードに配置します。objには、Bokehの図、hvPlotまたはHoloViewsのプロット、Plotlyの図、Matplotlibの図、またはそれらのいずれかを返すpn.bind(...)を指定できます。Bokehの図の数値軸には桁区切りが表示されるため、800000は800,000と表示されます。

pcp.Form(*widgets, on_submit=save, submit="Save")は、入力ウィジェットを送信ボタン付きの1つのフォームとして配置します。form.values()は、名前の付いたすべてのウィジェットについて{widget.name: widget.value}を返し、on_submitは、ボタンがクリックされたときにその辞書を受け取ります。

コンポーネント 用途
pcp.Section(title, *objects) ページの背景に直接配置される、タイトル付きのグループ。
pcp.Card(title, *objects) 浮き上がった面に配置される、タイトル付きのグループ。
pcp.Tabs(Overview=obj, Detail=obj) タブの内容を、そのタブが選択されたときに読み込むタブ。アクティブなタブには、ブランドカラーが使用されます。
pcp.Loading(height=200) データの読み込み中に表示する、きらめくプレースホルダー。

pcp.StatusBanner(message, kind="info")は、インライン通知を表示します。kindはerror、warning、success、infoのいずれかです。

pcp.run_workflow_button(workflow_id, label=None)は、アプリを開いたユーザーとしてPlaidCloudのワークフローを実行するボタンを追加し、実行中…、続いて完了または失敗を表示します。失敗した場合は、失敗したステップが最大5つまで示されます。project_idを渡さない限り、ワークフローはアプリのプロジェクトに属します。

pcp.RunButton(label, start, status)は、任意のジョブに対して同じことを行います。startはジョブを起動して実行IDを返し、status(run_id)は"running"、"succeeded"、"failed"、または理由を表示するための("failed", reason)を返します。どちらも、REST APIの呼び出しなど、通常の関数です。ボタンのrunsの値は、実行が成功するたびに1ずつ増えるため、その後に更新が必要なビューは、これにバインドします。

run = pcp.run_workflow_button("monthly_load")
grid = pcp.DataGrid("sales", key="id")
run.param.watch(lambda _: grid.refresh(), "runs")

pcp.table_freshness(table_id)は、テーブルが最後に書き込まれた時刻をUpdated 5 min agoのように表示します。経過時間は、ページを開いている間も更新されます。stale_after=datetime.timedelta(hours=24)を渡すと、それより古いデータが警告で示され、実行後に.refresh()を呼び出します。日付を特定できないテーブルにはLast update unknownと表示されますが、これはエラーではありません。pcp.Freshness(fetch)は、任意のソースに対して同じことを行い、fetchはデータが最後に変更された時刻を返します。

pcp.user_stateは、訪問の合間にそれぞれのユーザーの選択を記憶するため、アプリは前回終了したときの状態で開きます。

  • pcp.user_state.persist(widget, "region")は、保存された値をウィジェットに復元し、変更のたびに保存します。ウィジェットがもう提供していない保存済みの値は、無視されます。
  • navで選択したページは、自動的に保存されます。
  • filters.で始まるキー(たとえばpcp.user_state.persist(widget, "filters.region"))は、フィルターの選択を保持します。PlaidCloudは、読み取るたびに、これをそのユーザーの現在の行アクセスに合わせて絞り込むため、保存されたフィルターが、そのユーザーにもう見えない値を復活させることはありません。
  • pcp.user_state.get(key, default)とpcp.user_state.set(key, value)は、その他の小さな値を保存します。

保存された設定は、1つのアプリの1人のユーザーに属し、最大8 KBです。設定がユーザー間で共有されることはありません。設定の保存時にPlaidCloudに接続できない場合、アプリはセッションが終了するまで、それを保持します。

pcp.PrintButton()は、ブラウザーの印刷ダイアログを開き、保存先としてPDFとして保存を選択できます。ページは、サイドバーとコントロールが非表示で、プロジェクトのブランドが適用された状態で印刷されます。各DataGridは、現在のページ全体を最大1,000行まで、最後に合計行を付けて印刷します。ダークアプリは、ライトのパレットで印刷されます。

ボタン、通知、コマンドパレット、ツアー、実行と鮮度のメッセージ、グリッドのフッターなど、キット自体のテキストは、英語、ドイツ語、フランス語で表示されます。言語は、ページのアドレスの?lang=deまたは?lang=frで指定し、指定がない場合はブラウザーの言語になります。数値には、その言語の区切り文字が使用されます。データ、列名、ユーザーが記述したラベルが翻訳されることはありません。

最初の描画に3,000 msより長くかかるページの読み込み、または2,000 msより遅いクエリを実行するページの読み込みでは、アプリのログに、超過した項目を示す警告が書き込まれます。同じ数値は、Panel Studioのインサイトタブにも表示されます。アプリに別の上限を設定するには、次の環境変数を設定します。

変数 デフォルト 設定内容
PLAID_PANEL_BUDGET_FIRST_PAINT_MS 3000 最初の描画までのミリ秒。
PLAID_PANEL_BUDGET_QUERY_MS 2000 1つのクエリのミリ秒。

整数でない値は無視され、デフォルトが適用されます。

pcp.series()は、PlaidCloudのチャートのパレットを、色のリストとして順番に返します。例の棒グラフのように、独自に描画するチャートをキット自体のコンポーネントと一致させるために使用します。