Skip to content

Plugin initialization

Jump to bottom
comhon-project edited this page Aug 27, 2023 · 31 revisions

Import and use plugin

Before any usage of query-kit, 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.

Complete icons config example

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

it will render the following icon:

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

You can find all icons keys here

Classes

key type required
classes object false

By default rendered HTML elements will have some predefined classes, but you may override this classes names to define your own classes to use.
Note: if you don't use predefined 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 keys here

Inputs

key type required
inputs object false

You may define some custom input to use when rendering a filter. Basic properties filters have 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 custom inputs. You can override existing basic inputs too. A custom input is a component that will permit user to type the wanted filter value with your own inputs. You can see an example of a boolean input filter here.

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 keys here.

By default when a filter is used with in or not_in operators, the filter component can be displayed several times. in

But you can define a custom component that manage directly these operators and it will be rendered only one time. It will have to output the correct value according operator (an array of possible values when used with in or not_in). To do so, you will have to specify that your component must be displayed only one time:

const config = {
  inputs: {
    my_other_specific_type: {
      component: 'my-other-specific-component',
      unique: true,
    },
  }
}

Default locale

key type required default
defaultLocale string false en

The default locale to use.

Allowed operators

key type required
allowedOperators object false

The allowedOperators option permit to define which operators will be usable in the request builder.

The default operators are :

{
  condition: {
    basic: ['=', '<>', '<', '<=', '>', '>=', 'in', 'not_in', 'like', 'not_like'],
    enum: ['=', '<>', 'in', 'not_in'],
    date: ['=', '<>', '<', '<=', '>', '>=', 'in', 'not_in'],
    time: ['=', '<>', '<', '<=', '>', '>=', 'in', 'not_in'],
    datetime: ['=', '<>', '<', '<=', '>', '>=', 'in', 'not_in'],
    boolean: ['='],
  },
  group: ['and', 'or'],
  relationship_condition: ['has', 'has_not'],
}

The basic operators are operators usable in condition that has a type not referenced in previous list (like integer, string ...). You can override any operator list with your own, you can specify new types with their allowed operators too.

Example:

const config = {
  allowedOperators: {
    condition: {
      string: ["=", "<>"],
      datetime: ["=", "<>"],
      array: ["=", "in"],
      my_custom_type: ["like", "not_like"],
    },
    group: ['and'],
  }
}

Each values will completely replace the default one.

Note that array operators is a restriction of the contained type operators. For example we have a property favorite_fruits that is an array of string :

 {
  id: 'favorite_fruits',
  type: 'array',
  children: {
    type: 'string'
  }
}

According previous config, allowed operators for this property are the intersection of array operators and string operators : ['=']

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
}

Clone this wiki locally