Plugin initialization

Import and use plugin

first 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 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.

example:

{
  count: 245,
  collection: [
    {id:25, first_name: 'Jane'},
    {id:25, first_name: 'John'},
    /* ... */
  ]
}

Flattened items

Your requester may return flattened items or items with nested objects.

• flattened item :

{
  first_name: 'Jane', 
  favorite_fruits: ['apple', 'orange'], 
  'company.brand_name': 'awesome brand name', 
  'company.headquarter.address': '5 street nowhere'
}

• item with nested values :

{
  first_name: 'Jane', 
  favorite_fruits: ['apple', 'orange'],
  company: {
    brand_name: 'awesome brand name', 
    headquarter: {
      address: '5 street nowhere'
    }
  }
}

If your requester returns flattened items, you MUST specify the flatten property in your requester object.

const config = {
  requester: {
    request: async (data) => {...},
    flattened: true,
  }
}

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 the previous example we can see that the 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>

You can find all icons keyes here

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',
  }
}

You can find all classes keyes here

Inputs

key	type	required
inputs	object	false

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',
  }
}

You can find all predefined inputs keyes here

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
}