Usage

Query builder component

The query builder component will permit to user to build its request by defining some filters.

Usage

<script setup>
import { ref } from "vue";

const filter = ref({});
</script>

<template>
  <Builder model="user" v-model="filter"/>
</template>

Props

key	type	required	default	description
modelValue	object	true	-	The query to build (use v-model). Given object will be updated when user will make changes.
model	string	true	-	The model name
allowReset	boolean	false	true	Display a button to permit user to reset query to original state.
computedScopes	object	false	-	Build and inject filters in query. More information here.
allowedProperties	object	false	-	Restrict allowed properties that may be part of query. More information here.
allowedScopes	object	false	-	Restrict allowed scopes that may be part of query. More information here.
allowedOperators	object	false	-	Restrict allowed operators that may be part of query. More information here.
displayOperator	boolean or object	false	true	Display operators.
userTimezone	string	false	UTC	Display time in given timezone and time inputs are considered in given timezone.
requestTimezone	string	false	UTC	Timezone to use when requesting server.
deferred	number	false	1000	Time to wait after a user input to compute the query.
id	string	false	-	The html element id.

Computed scopes

Let's take an example to understand what a computed scope is. For example, we would like users to be able to search for others users by filtering them by first name, last name or email by typing a single text input. The computed scope are meant for that!

A computed scope look like :

{
  id: "quick_search",
  name: "quick search",          // only if you don't manage i18n
  translation: (locale) => {...} // only if you manage i18n
  type: "string",
  useOperator: true,
  computed: (value) => {...},
}

key	type	required	description
id	string	true	the unique identifier of computed scope
name	type	false	the scope name to display if you don't manage i18n
translation	function	false	function that must return the localized scope name according 'locale' parameter (if you manage i18n)
type	string	true	determine the input to display
useOperator	boolean	false	display or not operators
computed	function	false	function that must return a filter usable when request server (first parameter is the typed value, second is the chosen operator)

Computed scope must be associated to a model when passing through props.

Example:

<script setup>
function computeQuickSearch(value, operator) {
  return {
    type: "group",
    operator: "or",
    filters: [
      { property: "first_name", operator: 'like', value: value },
      { property: "last_name", operator: 'like', value: value },
      { property: "email", operator: 'like', value: value },
    ],
  };
}
</script>
<template>
  <Search 
    :model="user" 
    :computed-scopes="{
      user: [
        {
          id: 'quick_search',
          translation: (locale) => locale == 'fr' ? 'recherche rapide' : 'quick search',
          type: 'string',
          computed: computeQuickSearch,
        },
        ...
      ],
      organization: [...],
    }"
    ...
  />
</template>

Allowed properties

Restrict allowed properties that may be part of query.

  <Search 
    :model="user" 
    :allowed-properties="{
      user: ['last_name', 'birth_date'],
      organization: ['company_name', 'address'],
    }"
    ...
  />

Allowed scopes

Restrict allowed scopes that may be part of query.

  <Search 
    :model="user" 
    :allowed-properties="{
      user: ['my_user_scope'],
    }"
    ...
  />

Allowed operators

Restrict allowed operators that may be part of query. This prop will override the plugin setting allowedOperator

  <Search 
    :model="user" 
    :allowed-properties="{
      group: ['or'],
      condition: ['=', '<>'],
      relationship_condition: ['has'],
      scope: ['=', '<>'],
      string: ['=', '<>', 'like', 'not_like'],
    }"
    ...
  />

Events

Computed

A computed event is triggered when user update query filter (the event is deferred according deferred props). The computed filter format may be different than the original filter. It is the computed filter that will be used when requesting sever. The computed filter is given to the event listener as first parameter.

<Builder @computed="(computedFilter) => handle(computedFilter)" />

Collection component

The collection component will display data fetched.

Usage

<script setup>
</script>

<template>
  <Collection model="user" :columns="['first_name', 'last_name']" :limit="20" :direct-query="true"/>
</template>

Props

key	type	required	default	description
model	string	true	-	The model name
columns	array	true	-	Columns to display in collection table. More information here.
filter	object	false	-	The filter to apply when requesting server.
directQuery	boolean	true	-	Request server and display results when component is mounted.
limit	integer	true	-	The count limit of fetched items
offset	string	false	0	The offset of items to fetch
quickSort	boolean	false	true	Display quick sort (permit to sort results when click on collection column header).
postRequest	function	false	-	Function called just after querying server (permit to modify fetched items).
allowedCollectionTypes	array	false	['pagination']	Determine if collection is paginated or with infinite scroll. Allowed values are pagination and infinite. if both are given, user will be able to switch from one to the other.
displayCount	boolean	false	-	Display total items count that match query.
userTimezone	string	false	UTC	Display time in given timezone and time inputs are considered in given timezone.
requestTimezone	string	false	UTC	Timezone to use when requesting server.
requester	function or object	false	-	permit to override requester defined in global plugin configuration.
id	string	false	-	The html element id.

Columns

Columns to display in collection table. Each array element may be string (a property name) or an object that contain property name and others information. the property may be a property of the requested model or a property of nested objects.

When element is an object it may contain following values:

key	type	required	description
id	string	true	the property identifier
label	string or function	true	By default column take the name of the targeted property, but you can set a specific column label. Use a function if you manage i18n (first parameter is the current locale)
order	string	false	possible values are asc or desc. If specified the column will be ordered according given value.
onCellClick	function	false	function called on cell click

Example:

const columns = [
  'first_name',
  {
    id: 'last_name',
    order: 'asc',
    label: (locale) => locale == 'fr' ? 'nom génial' : 'awesome name',
  },
  {
    id: "birth_date",
    onCellClick: (row, property, event) => {
      event.stopPropagation();
      console.log("cell click", row[property]);
    },
  },
  "company",
  "company.address",
  "company.headquarter.address"
];

Events

Row click

The row-click event is triggered on collection row click.

• The current row item is injected as first parameter.
• The html event is injected as second parameter.

<Collection /* ... */ @row-click="(item, e) => handleRowClick(item, e)" />

Export

The export event is triggered on export button click. The export button is displayed only if there is a given event listener.

<Collection /* ... */ @export="exportToExcel" />

Search component

The search component combine both previous components. That permit you to load the search very easily with only one component.

Usage

<script setup>
</script>

<template>
  <Search model="user" :columns="['first_name', 'last_name']" :limit="20"/>
</template>

Props

key	type	required	default	description
model	string	true	-	The model name
allowReset	boolean	false	true	Display a button to permit user to reset query to original state.
computedScopes	object	false	-	Build and inject filters in query. More information here.
allowedProperties	object	false	-	Restrict allowed properties that may be part of query. More information here.
allowedScopes	object	false	-	Restrict allowed scopes that may be part of query. More information here.
allowedOperators	object	false	-	Restrict allowed operators that may be part of query. More information here.
displayOperator	boolean or object	false	true	Display operators.
userTimezone	string	false	UTC	Display time in given timezone and time inputs are considered in given timezone.
requestTimezone	string	false	UTC	Timezone to use when requesting server.
manually	boolean	false	true	If true user must click on a button to request server with new filter. Otherwise the server is requested automatically after user update.
deferred	number	false	1000	Time to wait after a user input to request server (only if manually is false).
columns	array	true	-	Columns to display in collection table. More information here.
filter	object	false	-	The filter to apply when requesting server.
directQuery	boolean	false	true	Request server and display results when component is mounted.
limit	integer	true	-	The count limit of fetched items
offset	string	false	0	The offset of items to fetch
quickSort	boolean	false	true	Display quick sort (permit to sort results when click on collection column header).
postRequest	function	false	-	Function called just after querying server (permit to modify fetched items).
allowedCollectionTypes	array	false	['pagination']	Determine if collection is paginated or with infinite scroll. Allowed values are pagination and infinite. if both are given, user will be able to switch from one to the other.
displayCount	boolean	false	-	Display total items count that match query.
requester	function or object	false	-	permit to override requester defined in global plugin configuration.

Events

Row click

More details here.

Export

More details here.