Vue composables

Plugin views are Vue single file components. @flare/plugin/vue gives them composables for talking to Flare, and components to draw with. The composables are reactive. When the theme, the open database, a widget's settings or the dashboard refresh changes, your component re-renders and its data reloads.

<script lang="ts" setup>
import { useAggregate, useFlare, useWidget } from '@flare/plugin/vue';

const flare = useFlare();
const { settings } = useWidget<{ container?: string }>();
const { data: count } = useAggregate(() =>
  settings.value.container
    ? { container: settings.value.container, aggregate: 'count' }
    : null
);
</script>

useFlare()

Returns ctx inside a component. target and preferences are reactive, and there are two extra fields:

Field	What it is
mode	The theme's mode, light or dark, for the rare case that needs it. Use the tokens for colours.
development	Whether the plugin is running from flare-plugin dev.

<script lang="ts" setup>
import { Badge, useFlare } from '@flare/plugin/vue';
import { computed } from 'vue';

const flare = useFlare();
const production = computed(() => flare.target?.production ?? false);
</script>

<template>
  <Badge v-if="production" tone="danger" dot>Production</Badge>
</template>

useWidget()

Returns a widget's settings, its size in grid cells and its refreshKey, as computed refs. Pass the shape of your settings to type them:

const { settings, size, refreshKey } = useWidget<{
  container?: string;
  field?: string;
}>();

refreshKey goes up each time the dashboard refreshes: every 30 seconds while it's open, and on Live. The data composables already watch it.

useViewProps()

Returns the view's props, reactive. That's WidgetProps for a widget, TransformProps for a result view, and whatever the command returned for a command view. Flare replaces the whole object when they change. defineProps works too.

import { useViewProps, type TransformProps } from '@flare/plugin/vue';

const props = useViewProps<TransformProps>();
const columns = computed(() => props.result.columns);

The data composables

Each one reads through Flare and returns AsyncData:

Field	What it is
data	The latest result, or null. Kept during a reload, so the view never flashes empty.
loading	Whether a read is in progress.
error	A PluginError, or null.
refresh()	Reads again right away.

Pass the request as a function or a ref. The composable reads again when the request changes, when the dashboard refreshes and when another database opens. Return null, undefined or false to wait, for example until a setting is chosen. Results that arrive out of order are dropped, so a slow read never overwrites a newer one.

useRead(request)

Reads records, like ctx.data.read.

const { data: orders, loading } = useRead(() => ({ container: 'orders', limit: 10 }));

useAggregate(request)

Runs a count, sum or average, like ctx.data.aggregate.

const { data: total } = useAggregate({
  container: 'orders',
  aggregate: 'sum',
  field: 'total',
});

useQuery(text)

Runs a read only query in the open database's own language.

const { data: statuses } = useQuery('select status, count(*) from orders group by 1');

useContainers(parent?)

Lists the open database's tables or collections. Pass parent on engines with levels.

const { data: tables } = useContainers();

useFlareData(source, read)

The same behaviour for a read you write yourself. source is the request, and read takes it with ctx and returns a promise. Use it to combine several reads or to call ctx.fetch.

const { data: paidShare } = useFlareData(
  () => (settings.value.container ? { container: settings.value.container } : null),
  async ({ container }, flare) => {
    const [total, paid] = await Promise.all([
      flare.data.aggregate({ container, aggregate: 'count' }),
      flare.data.aggregate({
        container,
        aggregate: 'count',
        filters: [{ field: 'status', operator: '==', value: 'paid' }],
      }),
    ]);
    return total ? (paid ?? 0) / total : null;
  }
);

The types

Type	What it is
Flare	PluginContext with mode and development: what useFlare() returns.
WidgetState<S>	{ settings, size, refreshKey }: what useWidget() returns.
AsyncData<T>	{ data, loading, error, refresh }: what the data composables return.
Source<K>	What to ask for, as a value, a ref or a function, or nothing to wait.
WidgetProps	{ settings, size, refreshKey }: a widget's props.
TransformProps	{ result }: a result view's props, the results with their language.