Plugin initialization

Plugin initialization

fisrt you have to define your plugin configuration :

import { plugin } from "@query-kit/vue";

app.use(plugin, {
  // here is your confiration
})

Configurations

Requester

|key|type|required |requester|function or object|true The requester that will fetch data from server. If config is an object, it MUST contain request property that contain a value of type function. The request function MUST return a promise that contains results of search request. The first parameter is the request data.

Example:

const config = {
  requester: async (data) => {
    const myData = {
      url: 'https://my.domain.com/endpoint',
      method: 'POST',
      ...data
    };
    return myRequester.fetch(myData);
  }
}

the injected data object contains following values:

data.model // the model name
data.order // the order of requested items
data.offset // the offset of the first returned result (pagination)
data.limit // the count limit of returned items (pagination)
data.filter // the request filters
data.properties // the properties that must be returned for each returned items

the requester MUST return an object with that contains:

• a count value that correspond to total items count that respect filter (not only returned items count)
• a collection that is an array of items.

Schema loader

|key|type|required |schemaLoader|function or object|true The schema loader that will load you models structure. If config is an object, it MUST contain load property that contain a value of type function. The load function MUST return a promise that contains the model structure. the first parameter is the model name.

Example :

const schemaLoader = async (modelName) => {
  if (modelName != 'user') {
    throw new Error('only user model for example');
  }
  return {
    properties: [
      {id: 'id', type: 'integer'},
      {id: 'first_name', type: 'string'},
      {id: 'last_name', type: 'string'},
      {id: 'birth_date', type: 'date'},
    ],
    search: ['first_name', 'last_name']
  }
}
const config = {
  schemaLoader: schemaLoader
}

Of course, shemas should be retrieved from server. In thie previous example we can see that ower user model has 4 properties but only 2 are filtrable.

Icons

Icons

|key|type|required |icons|object|false You may register some icons that will be used to display some contents, typically some buttons will use icons if you define them. Each key is the context where icon will be used, each value permit to determine witch icon to display.

Example:

const iconList = {
  add: 'fa fa-plus',
  delete: 'fa fa-minus',
}

Icon component

|key|type|required|default |iconComponent|object|false|i The component to use to display icon. It may be a simple HTML tag or vue component.

Icon prop name

|key|type|required|default |iconPropName|object|false|class The prop name where the icon value will be placed.

icons config example

const config = {
  requester: /* ... */,
  icons: {
    add: 'fa fa-plus',
  },
  iconComponent: 'i',
  iconPropName: 'class',
}

it will render the following add icon:

<i class="fa fa-plus"></i>

Classes

|key|type|required |classes|object|false By default render HTML elements will have some predifined classes, but you may override this classes names to define your own classes to use. Note: if you don't use predifined themes. the default classes comes without any style. So you can customize them as you want.

Example:

const config = {
  classes: {
    modal: 'my-modal-class',
    group: 'my-group-class',
    btn: 'my-btn-class',
  }
}

|key|type|required |classes|object|false

Inputs

You may define some custom input to filter your search. Basic properties filters has predefined inputs (like string, integer, date, enumerations...) but for more complex properties that have a very specific type, this is typically where you should use cunstom inputs. You can override existing basic inputs too. Custom inputs are components that will render the filter and that will return the filter value typed by the user. To register the component, you will have to link it to a property type.

Example:

const config = {
  inputs: {
    my_very_specific_type: 'my-very-specific-component',
    integer: 'my-integer-component-override',
  }
}

Default locale

|key|type|required|default |defaultLocale|string|false|en The default locale to use.

Fallback locale

|key|type|required|default |fallbackLocale|string|false|en The fallback locale to use when a translation is not found in current locale.

Schema locale loader

|key|type|required |schemaLocaleLoader|function or object|false You may define translations for your schema properties. If config is an object, it MUST contain load property that contain a value of type function. The load function MUST return a promise that contains transaltions. the first parameter is the model name. the second is the current locale.

Example :

const schemaLoader = async (modelName, locale) => {
  if (modelName != 'user') {
    throw new Error('only user model for example');
  }
  if (locale == 'en') {
    return {
      id: 'identifier',
      first_name: 'first name',
      last_name: 'last name',
      birth_date: 'birth date',
    }
  }
  if (locale == 'fr') {
    return {
      id: 'identifiant',
      first_name: 'prénom',
      last_name: 'nom',
      birth_date: 'date de naissance',
    }
  }
  return {};
}
const config = {
  schemaLoader: schemaLoader
}

Of course, translations should be retrieved from server.

render HTML

|key|type|required|default |renderHtml|boolean|false|false By default properties with type html are rendered as simple text to prevent XSS attack. but you may render them as HTML by setting renderHtml as true.

const config = {
  renderHtml: true
}

Usage

Query builder component

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

props

|key|type|required|default |modelValue|object|true|- |model|string|true|- |allowReset|boolean|false|true |computedScopes|object|false|- |allowedScopes|object|false|- |allowedProperties|object|false|- |allowedOperators|object|false|- |displayOperator|boolean or object|false|true |computedFilters|array|false|- |userTimezone|string|false|UTC |requestTimezone|string|false|UTC |deferred|number|false|1000 |displayShortcuts|boolean|false|false |id|string|false|-

Collection component

The collection component will display data fetched.

props

Search component

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

props

All props that are defined in query builder and collection components are usable in this component.

Example:

<script setup>
import Search from '@query-kit/vue';
</script>
<template>
  <Search model="user" />
</template>