Skip to content

Plugin initialization

Jump to bottom
comhon-project edited this page Jan 26, 2024 · 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:26, 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 your 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: {
      properties: ['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.

You can find an example of a schema that describe a user here.

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. There are some icons that are already defined by default but you can override them if you want to. If an icon is not defined (or null), the associated text will be displayed instead of the icon. You can find all icons keys here.

Each key is the context where icon will be used, each value permit to determine witch icon to display. Example:

const iconList = {
  add: 'fa-solid fa-plus', // will use default component and default prop name
  delete: { icon: "fa-solid fa-minus" }, // will use default component
  reset: { icon: "fa-solid fa-rotate-left", component: "Icon" }, // everything is defined
  previous: { icon: "fa-solid fa-previous", fade:"" }, // you may add some extra props
}

Icon component

key type required default
iconComponent string or object false i

The default component to use to display icon when component is not directly defined on icon. It may be a simple HTML tag or vue component.

Icon prop name

key type required default
iconPropName string false class

The default prop name where the icon value will be placed (only if defined icon is a simple string).

Complete icons config example

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

it will render the following icon:

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

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

Cell renderers

key type required
cellTypeRenderers object false

You may define some callbacks or components to render values in the collection. Each callback or component must be associated to a type.

const config = {
  cellTypeRenderers: {
    integer: CellIntegerComponent,
    string: (cellValue, rowValue, property) => cellValue + ' suffix_int',
  }
}
key type required
cellPropertyRenderers object false

You may define some callbacks or components to render values in the collection. Each callback or component must be associated to a model property.

const config = {
  cellPropertyRenderers: {
    user: {
      weight: (cellValue, rowValue, property) => cellValue + " suffix_weight",
    },
  }
}

The property renderers have a higher priority than type renderers.

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', 
      'begins_with', 'doesnt_begin_with', 'ends_with', 'doesnt_end_with', 'null', 'not_null',
    ],
    enum: ['=', '<>', 'in', 'not_in', 'null', 'not_null'],
    date: ['=', '<>', '<', '<=', '>', '>=', 'in', 'not_in', 'null', 'not_null'],
    time: ['=', '<>', '<', '<=', '>', '>=', 'in', 'not_in', 'null', 'not_null'],
    datetime: ['=', '<>', '<', '<=', '>', '>=', 'in', 'not_in', 'null', 'not_null'],
    boolean: ['=', 'null', 'not_null'],
  },
  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 : ['=']

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.

You can find an example of a translation schema that describe a user here.

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