Zestaw Panel App Kit
W każdej serwerowej aplikacji Panel jest zainstalowany zestaw plaidcloud_panel. Nadaje on aplikacji wygląd PlaidCloud — te same kolory, krój pisma i odstępy co w reszcie platformy, w jasnym i ciemnym motywie — oraz udostępnia gotowe komponenty do ekranów, których potrzebuje większość aplikacji: filtry, liczby nagłówkowe, duża siatka danych, wykresy i formularze. Twoja aplikacja automatycznie przejmuje markę projektu.
import plaidcloud_panel as pcpZaimportowanie zestawu stosuje też wygląd PlaidCloud do wykresów Plotly i Matplotlib.
Zacznij od szablonu
Dział zatytułowany „Zacznij od szablonu”W Panel Studio Nowa aplikacja > Studio zaczyna od pustej aplikacji, tabeli lub widoku, innej aplikacji Studio albo aplikacji z galerii, bez polecenia do uruchomienia.
Dla aplikacji przechowywanej w repozytorium git zestaw zawiera polecenie, które zapisuje działającą aplikację startową. Uruchom je z dowolnego folderu, a następnie zmień nazwy tabel i kolumn:
plaidcloud-panel new --layout dashboard --title "Sales" --table sales --filters region,year --measure amount| Opcja | Co robi |
|---|---|
--layout dashboard |
Filtry na pasku bocznym, dwie liczby nagłówkowe i wykres. |
--layout explorer |
Filtry na pasku bocznym, liczba wierszy i tabela wierszy. |
--table |
Tabela PlaidCloud, którą aplikacja odczytuje. |
--filters |
Kolumny oddzielone przecinkami, według których się filtruje. Pierwsza z nich steruje wykresem. |
--measure |
Kolumna liczbowa do zsumowania. |
--dir |
Gdzie zapisać app.py i requirements.txt. Domyślnie bieżący folder. |
Polecenie kończy działanie bez zapisywania czegokolwiek, jeśli app.py już istnieje. Zatwierdź te dwa pliki w repozytorium i opublikuj je jako aplikację serwerową.
Przykładowa aplikacja
Dział zatytułowany „Przykładowa aplikacja”Ta aplikacja filtruje tabelę sprzedaży według regionu i roku, pokazuje dwie liczby nagłówkowe, wykres oraz siatkę z stronicowaniem pasujących wierszy. Siatka pokazuje kwoty z separatorami tysięcy, a marże jako wartości procentowe. Każdy element podąża za filtrami.
import panel as pnimport plaidcloud_panel as pcpfrom bokeh.plotting import figurefrom 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()Wzorzec jest taki sam w każdej aplikacji zestawu: zbuduj FilterBar nad tabelą, a następnie powiąż każdy widok z bar.table. Widok, który nie jest powiązany z bar.table (ani z widżetem), nigdy się nie odświeża po zmianie filtrów.
pcp.App(title, nav=None, *, main=None, sidebar=None, theme_toggle=True, theme=None, commands=None, tour=None) buduje powłokę aplikacji: nagłówek z tytułem, logo projektu i zalogowanym użytkownikiem, pasek boczny i obszar główny. Wywołaj .servable() na wyniku.
- Nawigacja — przekaż
nav=[("Overview", overview_page), ("Detail", detail_page)], aby uzyskać menu stron u góry paska bocznego. Każda strona to obiekt Panel lub funkcja, która go zwraca. Funkcje są uruchamiane po wybraniu strony. - Motyw — aplikacja otwiera się w jasnym motywie. Przekaż
theme="dark", aby otworzyć ją w ciemnym motywie, lub dodaj?theme=darkdo adresu URL. Przytheme_toggle=True(domyślnie) nagłówek zawiera przełącznik jasny/ciemny. - Marka — aplikacja odczytuje kolory marki i logo swojego projektu na początku sesji. Projekt bez marki otrzymuje domyślne ustawienia PlaidCloud.
- Paleta poleceń — naciśnij Ctrl-K (Cmd-K na komputerze Mac), aby wyszukiwać i uruchamiać polecenia. Każda strona w
navjest wyświetlana jako Przejdź do nazwa strony, acommands={"Refresh data": refresh}dodaje Twoje własne pozycje, każda z etykietą i funkcją bez argumentów. Wybierz pozycję, a aplikacja ją uruchomi. - Wycieczka po pierwszym uruchomieniu —
tour=[("Filters", "Narrow the data here."), ("Grid", "Sort and group the rows.")]pokazuje krótkie wprowadzenie krok po kroku, w którym każdy krok to nagłówek i wiersz tekstu. Pojawia się u góry strony, dopóki go nie ukończysz lub nie pominiesz, i nie jest wyświetlane ponownie. - Wszystko inne — pozostałe argumenty nazwane są przekazywane do
FastListTemplatePanel.
FilterBar
Dział zatytułowany „FilterBar”pcp.FilterBar(table, "region", "year", amount=pn.widgets.IntInput(name="Amount")) tworzy jedno przeszukiwalne pole wielokrotnego wyboru dla każdej wskazanej kolumny, z listą unikatowych wartości tej kolumny (do 1000, z informacją, gdy lista została obcięta). Pole pokazuje Wszystkie, gdy nic nie jest wybrane. Własne widżety przekaż według nazwy kolumny do wszystkiego innego.
bar.tableto tabela zawężona bieżącymi wyborami. Pusty widżet nie zawęża danych.- Wybory są zapisywane w adresie URL strony (
?region=EU), więc przefiltrowany widok można udostępnić jako łącze.
KpiCard
Dział zatytułowany „KpiCard”pcp.KpiCard(label, source, column=None, fn="sum", fmt="{:,.0f}", drill_to=None) pokazuje jedną liczbę nagłówkową. fn to sum, count, avg, min lub max, obliczane przez serwer dla całej tabeli. Bez column pokazuje liczbę wierszy. Przekaż bar.table jako źródło, aby liczba podążała za filtrami.
Przekaż drill_to=grid, czyli DataGrid, aby dodać przycisk View rows pod liczbą. Jego wybranie kieruje siatkę na własną tabelę karty, więc siatka wyświetla wiersze stojące za liczbą.
DataGrid
Dział zatytułowany „DataGrid”pcp.DataGrid(source, key="id", totals={"amount": "sum"}) to widok tabelaryczny dla danych dowolnej wielkości. Do przeglądarki wysyłana jest tylko bieżąca strona; stronicowanie, sortowanie, sumy i eksport działają na serwerze.
-
Stronicowanie — 200, 500 lub 1000 wierszy na stronę, z przyciskami Previous i Next oraz licznikiem wierszy.
-
Sortowanie — kliknij nagłówek kolumny. Sortowanie dotyczy całej tabeli, a nie tylko widocznej strony.
-
Sumy —
totalsmapuje kolumnę nasum,count,avg,minlubmax. Serwer oblicza każdą z nich dla każdego pasującego wiersza i przypina wynik jako ostatni wiersz siatki. -
Eksport — przyciski CSV i XLSX pobierają każdy pasujący wiersz w bieżącej kolejności sortowania, do
export_capwierszy (domyślnie 100 000). Gdy tabela jest większa, komunikat prosi o zawężenie filtrów. Komórki tekstowe zaczynające się od=,+,-lub@są poprzedzone apostrofem, aby arkusz kalkulacyjny odczytał je jako tekst. -
Formaty liczb —
formats={"margin": "0.0%", "amount": "0,0"}ustawia format wyświetlania dla każdej kolumny, używając ciągów formatu numbro. Format%mnoży przez 100. Wiersz sum używa tego samego formatu. Kolumny zmiennoprzecinkowe bez formatu pokazują do dwóch miejsc po przecinku z separatorami tysięcy. Kopiuj, CSV i XLSX zachowują surowe wartości. -
Klucz —
keyto kolumna lub lista kolumn, które jednoznacznie identyfikują wiersz. Zawsze go przekazuj. Zobacz Stabilne stronicowanie. -
Grupuj według —
group_by=["region"]pokazuje jeden wiersz na grupę, z miaramitotalsi liczbąrows, wszystko obliczane przez serwer, oraz wiersz Razem dla każdego pasującego wiersza. Przekażgroupable=["region", "year"], aby dodać selektor Grupuj według, w którym przeglądający wybierają kolumny. Siatka pokazuje do 1000 grup i informuje, gdy obcięła listę. Wiersze grup nie mają łączy Otwórz. -
Formatowanie warunkowe —
ruleskoloruje komórki według wartości. Każda reguła wskazujecolumn,op(>,>=,<,<=,==,!=lubbetween),value([low, high]dlabetween) oraztoken(success,warning,errorlubinfo), na przykład{"column": "margin", "op": "<", "value": 0, "token": "error"}. Wiersz sum nigdy nie jest kolorowany. -
Kopiuj — przycisk Kopiuj umieszcza bieżącą stronę, z widocznymi kolumnami i wierszem sum, w schowku jako tekst rozdzielany tabulatorami, który można wkleić do Excel.
-
Open in PlaidCloud — gdy źródłem jest tabela PlaidCloud, łącze Open in PlaidCloud otwiera tę tabelę.
-
Zapisany układ kolumn —
layout_key="orders"dodaje selektory Kolumny i Pinned do wyboru i porządkowania kolumn oraz przypinania niektórych z nich. Wybór każdego przeglądającego jest zapisywany pod tą nazwą i przywracany przy następnym otwarciu aplikacji. -
Łącza wierszy —
row_linkto funkcja, która przyjmuje wiersz, jako słownik, i zwraca adres internetowy lubNone, gdy nie ma łącza. Siatka dodaje kolumnę Otwórz z łączem w każdym wierszu, który je ma. Łączone są tylko adresyhttpihttpsoraz ścieżki w tej samej witrynie. -
Odświeżanie —
grid.refresh()ponownie wykonuje zapytanie do tego samego źródła i zachowuje stronę, sortowanie i grupowanie. Wywołaj ją po tym, jak uruchomienie zakończy zapisywanie tabeli.
source to nazwa tabeli lub tabela z Data API. Aby ponownie przefiltrować siatkę, ustaw grid.source na przefiltrowaną tabelę lub zbuduj nową siatkę z bar.table, jak w przykładzie.
Siatka podlega zabezpieczeniom na poziomie wierszy przeglądającego: odczytuje dane przez własne połączenie przeglądającego.
pcp.Chart(obj, title=None, height=320) umieszcza wykres w karcie z tytułem. obj może być figurą Bokeh, wykresem hvPlot lub HoloViews, figurą Plotly, figurą Matplotlib albo pn.bind(...), które zwraca którąkolwiek z nich. Osie liczbowe na figurach Bokeh pokazują separatory tysięcy, więc 800000 jest wyświetlane jako 800,000.
pcp.Form(*widgets, on_submit=save, submit="Save") układa widżety wejściowe jako jeden formularz z przyciskiem zatwierdzenia. form.values() zwraca {widget.name: widget.value} dla każdego nazwanego widżetu, a on_submit otrzymuje ten słownik po kliknięciu przycisku.
Section, Card, Tabs i Loading
Dział zatytułowany „Section, Card, Tabs i Loading”| Komponent | Do czego służy |
|---|---|
pcp.Section(title, *objects) |
Grupa z tytułem bezpośrednio na tle strony. |
pcp.Card(title, *objects) |
Grupa z tytułem na podniesionej powierzchni. |
pcp.Tabs(Overview=obj, Detail=obj) |
Karty, które ładują zawartość karty po jej wybraniu. Aktywna karta przyjmuje kolor marki. |
pcp.Loading(height=200) |
Migoczący element zastępczy do wyświetlania podczas ładowania danych. |
StatusBanner
Dział zatytułowany „StatusBanner”pcp.StatusBanner(message, kind="info") pokazuje wbudowane powiadomienie. kind to error, warning, success lub info.
Przyciski uruchamiania i aktualność
Dział zatytułowany „Przyciski uruchamiania i aktualność”pcp.run_workflow_button(workflow_id, label=None) dodaje przycisk, który uruchamia przepływ pracy PlaidCloud jako osoba, która otworzyła aplikację, i pokazuje Uruchomiony…, a następnie Gotowe lub Niepowodzenie. Niepowodzenie wskazuje kroki, które się nie powiodły, do pięciu. Przepływ pracy należy do projektu aplikacji, chyba że przekażesz project_id.
pcp.RunButton(label, start, status) robi to samo dla dowolnego zadania. start je uruchamia i zwraca identyfikator uruchomienia; status(run_id) zwraca "running", "succeeded" lub "failed" albo ("failed", reason), aby pokazać przyczynę. Obie są zwykłymi funkcjami, takimi jak wywołania REST API. Wartość runs przycisku rośnie o jeden przy każdym udanym uruchomieniu, więc widok, który musi się potem odświeżyć, wiąże się z nią:
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) pokazuje, kiedy tabela została ostatnio zapisana, jako Updated 5 min ago. Wiek aktualizuje się, gdy strona pozostaje otwarta. Przekaż stale_after=datetime.timedelta(hours=24), aby oznaczyć starsze dane ostrzeżeniem, i wywołaj .refresh() po uruchomieniu. Tabela, której nie można datować, pokazuje Last update unknown; nigdy nie jest to błąd. pcp.Freshness(fetch) robi to samo dla dowolnego źródła, gdzie fetch zwraca, kiedy dane ostatnio się zmieniły.
Zapisane ustawienia
Dział zatytułowany „Zapisane ustawienia”pcp.user_state zapamiętuje wybory każdej osoby między wizytami, więc aplikacja otwiera się tak, jak ją zostawiono.
pcp.user_state.persist(widget, "region")przywraca zapisaną wartość do widżetu i zapisuje ją przy każdej zmianie. Zapisana wartość, której widżet już nie oferuje, jest ignorowana.- Strona wybrana w
navjest zapisywana automatycznie. - Klucz zaczynający się od
filters., taki jakpcp.user_state.persist(widget, "filters.region"), przechowuje wybór filtra. PlaidCloud przycina go do bieżącego dostępu do wierszy tej osoby przy każdym odczycie, więc zapisany filtr nigdy nie przywraca wartości, których osoba już nie może zobaczyć. pcp.user_state.get(key, default)ipcp.user_state.set(key, value)zapisują każdą inną małą wartość.
Zapisane ustawienia należą do jednej osoby w jednej aplikacji, do 8 KB. Ustawienia nigdy nie są współdzielone między osobami. Jeśli podczas zapisu ustawienia nie można połączyć się z PlaidCloud, aplikacja przechowuje je do końca sesji.
Drukowanie i zapisywanie jako PDF
Dział zatytułowany „Drukowanie i zapisywanie jako PDF”pcp.PrintButton() otwiera okno drukowania przeglądarki, w którym miejscem docelowym może być Zapisz jako PDF. Strona jest drukowana z ukrytym paskiem bocznym i kontrolkami oraz z zastosowaną marką projektu. Każdy DataGrid drukuje całą swoją bieżącą stronę, do 1000 wierszy, z wierszem sum na końcu. Ciemna aplikacja drukuje się w jasnej palecie.
Własny tekst zestawu, taki jak przyciski, powiadomienia, paleta poleceń, wycieczka, komunikaty o uruchomieniu i aktualności oraz stopka siatki, pojawia się w języku angielskim, niemieckim lub francuskim. Język to ?lang=de lub ?lang=fr w adresie strony, w przeciwnym razie język przeglądarki. Liczby używają separatorów danego języka. Twoje dane, nazwy kolumn i etykiety, które piszesz, nigdy nie są tłumaczone.
Budżety wydajności
Dział zatytułowany „Budżety wydajności”Wczytanie strony, w którym pierwsze renderowanie trwa dłużej niż 3000 ms lub które wykonuje zapytanie wolniejsze niż 2000 ms, zapisuje ostrzeżenie w dzienniku aplikacji, wskazując, co przekroczyło limit. Te same wartości pojawiają się na karcie Wnioski w Panel Studio. Aby ustawić inne limity dla aplikacji, ustaw te zmienne środowiskowe:
| Zmienna | Domyślna | Ustawia |
|---|---|---|
PLAID_PANEL_BUDGET_FIRST_PAINT_MS |
3000 |
Milisekundy do pierwszego renderowania. |
PLAID_PANEL_BUDGET_QUERY_MS |
2000 |
Milisekundy na jedno zapytanie. |
Wartość, która nie jest liczbą całkowitą, jest ignorowana i obowiązuje wartość domyślna.
Kolory dla własnych wykresów
Dział zatytułowany „Kolory dla własnych wykresów”pcp.series() zwraca paletę wykresów PlaidCloud jako listę kolorów, w kolejności. Użyj jej, aby wykresy rysowane samodzielnie pasowały do własnych komponentów zestawu, tak jak w przykładzie dla wykresu słupkowego.
Następne kroki
Dział zatytułowany „Następne kroki”- Data API — filtruj, stronicuj, zliczaj i agreguj tabele PlaidCloud z aplikacji.
- Alerty i podsumowania — wysyłaj z aplikacji alerty KPI i zaplanowane podsumowania.
- Marka projektu — ustaw kolory i logo raz dla każdej aplikacji w projekcie.