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>
  <QkitBuilder entity="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. More information on filter format here.
entity	string	true	-	The entity id (user, company, post...)
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. More information here.
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
  parameters: [{ id: 'value', name: 'value', type: 'string' }],
  computed: (parameters) => {...},
}

key	type	required	description
id	string	true	the unique identifier of computed scope
name	string	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)
parameters	array	false	array of parameter objects with id, name and type (string, integer, datetime...)
computed	function	false	function that must return a filter usable when request server (first parameter is the array of parameters values)

Computed scope must be associated to an entity when passing through props.

Example:

<script setup>
function computeQuickSearch(parameters) {
  const value = parameters[0];
  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>
  <QkitSearch
    entity="user"
    :computed-scopes="{
      user: [
        {
          id: 'quick_search',
          translation: (locale) => locale == 'fr' ? 'recherche rapide' : 'quick search',
          parameters: [{ id: 'value', name: 'value', type: 'string' }],
          computed: computeQuickSearch,
        },
        ...
      ],
      organization: [...],
    }"
    ...
  />
</template>

Allowed properties

Restrict allowed properties that may be part of query.

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

Allowed scopes

Restrict allowed scopes that may be part of query.

  <QkitSearch
    entity="user" 
    :allowed-scopes="{
      user: ['my_user_scope'],
    }"
    ...
  />

Allowed operators

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

  <QkitSearch
    entity="user" 
    :allowed-operators="{
      group: ['or'],
      relationship_condition: ['has'],
      condition: {
        basic: ['=', '<>'],
        string: ['=', '<>', 'like', 'not_like'],
      },
    }"
    ...
  />

Display operator

By default operators are displayed but you can define if you want to display operators or not. For example if you want to allow only operator and for group filters, there's no need to display the operator.

You can simply disable all operators :

<QkitBuilder :display-operator="false" />

Or you can disable operators by filter type :

// disable only group operators
<QkitBuilder :display-operator="{ group: false, condition: true, relationship_condition: true }" />

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 server. The computed filter is given to the event listener as first parameter.

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

Collection component

The collection component will display data fetched.

Usage

<script setup>
</script>

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

Props

key	type	required	default	description
entity	string	true	-	The entity id (user, company, post...)
columns	array	true	-	Columns to display in collection table. More information here.
customColumns	object	false	-	permit to customize collection headers and cells rendering. 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	number	true	-	The count limit of fetched items
offset	number	false	0	The offset of items to fetch
orderBy	array	false	-	Array of column ids (strings) or order objects { column: string, order: 'asc'|'desc' } (e.g. ['name'] or [{ column: 'created_at', order: 'desc' }])
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.
editColumns	boolean	false	-	Allows users to define the columns they want to display.
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 value must be a unique identifier for the current collection. Each value may be a property (a property of the requested entity or a property of nested objects) and/or a custom column identifier. If the column is a property, column header label and cell renderer are determined automatically, but you may override them as you want with custom columns.

Example:

const columns = [
  'first_name',
  'age',
  'company',
  'company.address',
  'company.headquarter.address',
  'friend',
  'my_custom_column_one', // MUST be defined in custom columns
  'my_custom_column_two', // MUST be defined in custom columns
];

Columns and relationships

When a column contains a property that is a relationship (has_one or belongs_to), the column value will contain primary_identifiers of the corresponding entity. for example in previous example, The company column would contain the brand name of the company and the friend column would contain first name and last name of the person (if there are no primary_identifiers defined, the id will be displayed). When using relationship column, the item id is fetched from the server too, so it is very convenient to route user on a specific resource.

Custom columns

Custom columns permit to customize columns header and cells. Each key must be a column id and each value an object that describe what you want to customize for the column. A custom column may be associated to an entity property or not. If custom column is associated to an entity property, column header label and cell renderer are determined automatically, but you may override them as you want.

key	type	required	description
open	boolean	false	If the column is NOT associated to a property, you must set this attribute to true.
label	string or function	false	The column header label. You can use a function if you want to manage i18n (first parameter is the current locale)
renderer	string, object or function	false	The renderer that will display cell value. it might be a component or a callback.
onCellClick	function	false	function called on cell click.

Example:

const customColumns = {
  first_name: {
    label: (locale) => locale == 'fr' ? 'nom génial' : 'awesome name',
    renderer: 'first-name-component',
  },
  company: {
    id: "company",
    onCellClick: (value, row, property, event) => {
      event.stopPropagation();
      router.push(`/companies/${value.id}/overview`);
      // if flattened
      // router.push(`/companies/${row[property+'.id']}/overview`);
    },
  },
  my_custom_column_one: {
    open: true, // required !
    label: 'custom column one',
    renderer: (cellValue, rowValue, property) => rowValue.last_name + rowValue.first_name,
  },
  my_custom_column_two: {
    open: true, // required !
    label: (locale) => locale == 'fr' ? 'custom colonne deux' : 'custom column two',
    renderer: (cellValue, rowValue, property) => rowValue.weight + ' kg',
  },
};

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.

<QkitCollection /* ... */ @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.

<QkitCollection /* ... */ @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>
  <QkitSearch entity="user" :columns="['first_name', 'last_name']" :limit="20"/>
</template>

Props

key	type	required	default	description
entity	string	true	-	The entity id (user, company, post...)
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. More information here.
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.
customColumns	object	false	-	permit to customize collection headers and cells rendering. More information here.
filter	object	false	-	The filter to apply when requesting server. More information on filter format here.
directQuery	boolean	false	true	Request server and display results when component is mounted.
limit	number	true	-	The count limit of fetched items
offset	number	false	0	The offset of items to fetch
orderBy	array	false	-	Array of column ids (strings) or order objects { column: string, order: 'asc'|'desc' } (e.g. ['name'] or [{ column: 'created_at', order: 'desc' }])
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.
editColumns	boolean	false	-	Allows users to define the columns they want to display.
requester	function or object	false	-	permit to override requester defined in global plugin configuration.

Events

Row click

More details here.

Export

More details here.

Computed

More details here.

Updated

The updated event is triggered when query filter is modified. The new filter is injected as first parameter.