VST Utils frontend¶
The main feature of the VST Utils framework is autogenerated GUI, which is forming based on the OpenAPI schema. Autogenerated GUI is available because of some frontend mechanisms work.
VST Utils frontend consists of 2 blocks:
Block, that is responsible for parsing of OpenAPI schema and generating entities necessary for application work:
Objects of Model class - store model’s name, fields and so on;
Objects of QuerySet class - operate with data of Model instances;
Objects of View class - have info about representation of Model instance.
Block, that is responsible for rendering and routing. This block works based on:
Vue - views rendering;
Vue Router - routing between application views;
Vuex - application state store.
Let’s look on the structure of those blocks’ elements.
Frontend src entry points¶
vstutils
frontend has several webpack entry points:
spa.js
- main applicationdoc.js
- bundle for documentationauth.js
- libraries for login and register pages
All entry points contains at least:
jquery
bootstrap
fontawesome
admin-lte
Association with back-end entities¶
VST Utils’s back-end is realised on the base of Django Framework, which operates by some entities in it’s work:
So, we decided, that it will be great, if we will use similar entities in the frontend, because it will be easier for backend developer understand how frontend works and vice versa.
Model class and View class are used for generating of frontend Models and View on the final step of parsing of OpenAPI schema.
Model class¶
Model class is an abstraction, that is supposed to be similar to the Django Model abstraction. This class has all necessary data about Model structure: name of the Model, Model’s fields, which field is a primary key, which field is should be used as view field (in some autocomplete lists, for example). Also this class has some methods, for manipulations with Model instances.
Objects of this class are Models, so with the help of this class VST Utils creates all necessary Models based on data from OpenAPI schema.
To get Model Instance you should use getInstance()
method of Model object.
Let’s look on properties of this class.
Structure of Model¶
Let’s look on structure of Model object on the example of User Model:
{
name: "User",
fiends: {
id: IntegerField,
username: StringField,
email: StringField,
is_active: BooleanField,
},
non_instance_attr: ["non_instance_attr", "constructor", "getInstance"],
pk_name: "id",
view_name: "username",
}
As you can see from the example Model has several properties:
name - string, that stores name of Model;
fields - object, that stores Model fields - instances of guiFields;
non_instance_attr - array, that stores names of properties and methods, that should not be added to the Model Instance (during Model instance creation in the
getInstance()
method);pk_name - string, that stores name of Model field, that is Primary Key for this model.
view_name - string, that stores name of Model field, that is supposed to be used for Model Instance representation in some autocomplete lists and so on.
Let’s look on properties of Model Instance.
Structure of Model Instance¶
Let’s look on structure of Model Instance on the example of User Model Instance:
{
name: "User",
fiends: {
id: IntegerField,
username: StringField,
email: StringField,
is_active: BooleanField,
},
non_instance_attr: ["non_instance_attr", "constructor", "getInstance"],
pk_name: "id",
view_name: "username",
data: {
id: 1,
username: "admin",
email: "admin@mail.com"
is_active: true,
},
queryset: QuerySet,
}
As you can see from the example Model Instance has the same properties as Model plus 2 new properties:
name - string, that stores name of Model;
fields - object, that stores Model fields - instances of guiFields;
non_instance_attr - array, that stores names of properties and methods, that should not be added to the Model Instance (during Model instance creation in the
getInstance()
method);pk_name - string, that stores name of Model field, that is Primary Key for this model.
view_name - string, that stores name of Model field, that is supposed to be used for Model Instance representation in some autocomplete lists and so on.
data - object with Model Instance data (values of Model Instance fields);
queryset - instance of QuerySet class - queryset, connected with the current Model Instance.
Let look on the methods of Model and Model Instance.
constructor(name, fields)¶
Arguments:
name: {string} - Model’s name.
fields: {object} - Object with Model fields. Those fields are supposed to be instances of guiFields.
Description: Standard constructor of JS class. This method creates new Model with current name and fields. Also this method sets which field is PK and which field is view field.
getPrefetchFields()¶
Description: Method loops through Model fields, tries to find fields of FK
type (and fields, inherited from FK field)
and returns matched fields. This method is supposed to be called,
when it is necessary to load prefetched data of Model Instance (name of instance, to which FK field is linked, for example).
getInstance(data, queryset)¶
Arguments:
data: {object} - Object with Model Instance data.
queryset: {object} - Instance of QuerySet class. This QuerySet is aimed to load and set all necessary data for Model instance in API.
Description: This method returns Model Instance.
toInner(form_data=this.data)¶
Arguments:
form_data: {object} - Object with Model Instance data, that was modified by user. Default value is
ModelInstance.data
property.
Description: This method converts data from ‘GUI view’ format into format, appropriate for API.
toRepresent(api_data=this.data)¶
Arguments:
api_data: {object} - Object with Model Instance data, that was get from API. Default value is
ModelInstance.data
property.
Description: This method converts data from API format into format, appropriate for ‘GUI view’.
getPkValue()¶
Description: Method, that returns Model Instance’s value of PK field.
getViewFieldValue()¶
Description: Method, that returns Model Instance’s value of view field.
save(method=”patch”)¶
Arguments:
method: {string} - Name of method (POST, PATCH, PUT), that should be used during saving.
Description: Method, that saves Model Instance’s changes.
delete()¶
Description: Method, that deletes Model Instance.
QuerySet class¶
QuerySet class is an abstraction, that is supposed to be similar to the Django QuerySet abstraction. This class has methods for filtering, getting, creating Model Instances. Those methods form appropriate API requests and send them.
Let’s look on properties of this class.
Structure of QuerySet Instance¶
Let’s look on structure of QuerySet Instance on the example of QuerySet for User Model Instance, available by /user/1
path:
{
model: Model,
query: {},
url: "/user/1",
use_prefetch: true,
cache: ModelInstance,
}
As you can see from the example QuerySet Instance has following properties:
model - User Model;
query - object with filters values - (key, value) pairs.
url - string, that stores URL by which connected Model Instance and it’s data are available;
use_prefetch - boolean/array - if boolean - means - use prefetch or not, otherwise, means array with names of model fields, that should be used as prefetch fields.
cache - object/array - if current QuerySet Instance is connected with
list
view, this property will be array, storing list of Model Instances. Otherwise, it will store only one Model Instance and type of this property will be ‘object’.
Let’s look on methods of this class.
constructor(model, url, query={})¶
Arguments:
model: {object} - Model for which this QuerySet will be created.
url: {string} - Current url of view. For example, if current URL is
/user/1
, QuerySet for Model Instance, that should be represented on the view with current url, will have property url equal to/user/1
.query: {object} - Object, that stores current QuerySet filters (pairs of key, value). Default value: empty object.
Description: Standard constructor of JS class. This method creates new QuerySet with current arguments.
Also it sets property use_prefetch
equal to false
. This property means load prefetch data or not.
makeQueryString(query=this.query)¶
Arguments:
query: {object} - Object with pairs of key, value for QuerySet filters. Default value: this.query.
Description: Method, that converts ‘query’ object into ‘filters’ string, appropriate for bulk query.
getDataType()¶
Description: Method, that converts ‘this.url’ string into ‘data_type’ array, appropriate for bulk query.
formBulkQuery(method, data)¶
Arguments:
method: {string} - Method(get/delete/post/put/patch) of bulk query.
data: {object} - ‘data’ property for body of bulk query, data of Model Instance.
Description: Method, that forms body of bulk query.
formQueryAndSend(method, data)¶
Arguments:
method: {string} - Method(get/delete/post/put/patch) of bulk query.
data: {object} - ‘data’ property for body of bulk query, data of Model Instance.
Description: Method, that forms bulk query and sends it to API.
sendQuery(bulk)¶
Arguments:
bulk: {object} - bulk Object with properties of bulk data.
Description: Method, that sends bulk query to API.
clone(props={}, save_cache=false)¶
Arguments:
props: {object} - Object with properties, that should be rewritten in clone. Default value: empty object.
save_cache: {boolean} If true, cache of current QuerySet will be saved in clone. Default value: false.
Description: Method, that returns clone (new QuerySet instance) of current QuerySet, without cache, by default.
copy(props={})¶
Arguments:
props: {object} - Object with properties, that should be rewritten in clone. Default value: empty object.
Description: Method, that returns copy (new QuerySet instance) of current QuerySet, with cache of current QuerySet.
all()¶
Description: Method, that returns clone of current QuerySet Instance with current value of ‘this.query’ property.
filter(filters)¶
Arguments:
filters: {object} - Object with filters(key, value), according to which Model Instances list should be sorted.
Description: Method, that returns clone of current QuerySet Instance with new filters, that will be saved in ‘query’ property.
exclude(filters)¶
Arguments:
filters: {object} - Object with filters(key, value), according to which some instances should be excluded from Model instances list.
Description: Method, that returns clone of current QuerySet Instance with new filters, that will be saved in ‘query’ property.
prefetch(instances=true)¶
Arguments:
instances: {boolean | array} If boolean - means - Use prefetch or not, otherwise, means array with names of model fields, that should be used as prefetch field.
Description: Method, that returns clone of current QuerySet Instance with new value of ‘use_prefetch’ property.
items()¶
Description: Method, that sends to API get request for getting list of Model Instances, appropriate for filters from ‘this.query’ property. Method, returns promise, that it will return list of Model instances, if API request be successful.
create(data)¶
Arguments:
data: {object} Data of new Model Instance.
Description: Method, that sends query to API for creation of new Model Instance and returns promise, that it will return Model Instance, if query response be successful.
delete()¶
Description: Method, that deletes all Model Instances, that this.items() returns. It means, that this method deletes all instances, that were filtered before it’s execution. This method is expected to be called after instance filtering. This method is only for querysets, that have ‘url’ of ‘list’ type. This method should not be applied for querysets with ‘page’ type url.
get()¶
Description: Method, that returns promise, that it will return Model Instance with ‘this.url’ URI, if API query be successful.
clearCache()¶
Description: Method, that cleans QuerySet cache.
_getPrefetchFields()¶
Description: Method, that returns array with names of prefetch fields.
_getBulkDataForPrefetch(prefetch_fields, instances)¶
Arguments:
prefetch_fields {array} - Array with names of prefetch fields.
instances {object} - Object with loaded Model Instances.
Description: Method, that forms bulk_data for prefetch Bulk.
_getBulkDataForPrefetchForInstance(prefetch_fields, instance, bulk_data)¶
Arguments:
prefetch_fields: {array} - Array with names of prefetch fields.
instance: {object} - Model instance.
bulk_data: {object} - Object with bulk_data.
Description: Method, that forms prefetch bulk_data for one instance.
_loadPrefetchData(prefetch_fields, instances)¶
Arguments:
prefetch_fields: {array} - Array with names of prefetch fields.
instances: {object} - Object with loaded model instances.
Description: Method, that loads prefetch info for instances, which were loaded by current queryset.
_setPrefetchValue(res, bulk_data, instances, field_name)¶
Arguments:
res: {object} - Prefetch API response.
bulk_data_item: {object} - Object bulk data for prefetch request.
instances: {array} - Array with instances.
field_name: {string} - Name of model field.
Description: Method, that adds loaded prefetch data to instances.
View class¶
View class is an abstraction, that stores info about representation of some Model Instance available by some path (URL). This class is used for creation of views objects, that stores info about template, that should be used for current view, about views, to which current view can be linked and so on.
There are 5 types of views in VST Utils:
list - view, that is responsible for representation of Model Instances list;
page_new - view, that is responsible for representation of the page for new Model Instance creation;
page - view, that is responsible for representation of Model Instance;
page_edit - view, that is responsible for representation of the page for Model Instance editing;
action - view, that is responsible for representation of the page for some Model Instance action execution.
Those views have common structure, but values of several properties are different for each type of view.
Let’s look on the structure of the list
view on the example of User list
view.
{
objects: QuerySet,
schema: {
actions: {},
autoupdate: true,
child_links: {
change_password: {
name: "change_password",
path: "/user/{id}/change_password/",
},
copy: {
name: "copy",
path: "/user/{id}/copy/",
},
edit: {
name: "edit",
path: "/user/{id}/edit/",
},
remove: {
name: "remove",
},
},
filters: {
id: IntegerField,
id__not: IntegerField,
is_active: StringField,
ordering: StringField,
username: StringField,
username__not: StringField,
},
level: 2,
multi_actions: {
remove: {
name: "remove",
title: "Remove",
multi_action: true,
},
},
name: "user",
operation_id: "user_list",
operations: {
new: {
name: "new",
path: "/user/new/",
},
},
page_path: "/user/{id}/",
path: "/user/",
query_type: "get",
sublinks: {},
type: "list",
},
template: "#template_view_entity",
mixins: [],
}
As you can see from the example View Instance has following properties:
objects - QuerySet instance, connected with current view;
schema - object, that stores options of current view and links to connected views;
template - string, that contents either template string of current view or ‘id’ of element, that stores template string;
mixins - array, that stores additional mixins for Vue component of current view. These mixins will be used during creation of route for current view. These mixins can redefine some base functionality of view Vue component or add some additional ones. RouterConstructor class will combine these mixins with base ones (that will be defined based on the view type).
Let’s look closely on the properties of the schema
property:
actions - object, that stores pairs of key, value, where key - name of action, that can be executed/opened from this view, value - object with options of current action (name, path and so on). Action is an activity, that can be executed for some Model Instance (for example, for User Model Instance it could be ‘change password’, ‘copy’);
autoupdate - boolean, that means make automatic requests for data updating from current view or not;
child_links - object, that stores pairs of key, value, where key - name of child link, that can be executed/opened from this view, value - object with options of current child link (name, path and so on). Child link is an action / operation / sublink of a
page
view, that could be executed/opened from thelist
view;filters - object, that stores pairs of key, value, where key - name of filter, which can be used on current view, value - instance of guiField, that is used for setting filter value. Filter is some option of Model Instance with the help of which you can categorize you search on Model Instance list;
level - number, that tells about nesting depth of current view path;
multi_actions - object, that stores pairs of key, value, where key - name of multi action, that can be executed/opened from this view, value - object with options of current multi action (name, path and so on). Multi action is an action / operation, that can be executed from
list
view for several Model Instance at the same time;name - string, name of Model or Action, connected with current view;
operation_id - string, that stores name of Model and type of view. This property is used in OpenAPI schema;
operations - object, that stores pairs of key, value, where key - name of operation, that can be executed/opened from this view, value - object with options of current operation (name, path and so on). Operation is some basic activity, that be done with the Model Intance (create, edit, save, delete);
page_path - string, path of
page
view connected with currentlist
view;path - string, path of current view (template for URL);
query_type - string, name of HTTP method, that should be used for API requests from current view;
sublinks - object, that stores pairs of key, value, where key - name of sublink, that can be opened from this view, value - object with options of current sublink (name, path and so on). Sublink is an
list
view, that is nested in current. For example, in path/foo/{id}/bar/
bar
will be sublink forfoo
;type - string, type of view (list / page_new / page / page_edit / action);
Let’s look on methods of this class.
constructor(model, schema, template)¶
Arguments:
model: {object} - Model, with which this view is connected.
schema: {object} - Options of current view, that include settings for a view (internal links, view type and so on).
template: {string} - Template content or id of script with template content.
Description: Standard constructor of JS class. This method creates new View with current arguments.
getViewSublinkButtons(type, buttons, instance)¶
Arguments:
type: {string} - Buttons type - actions / operations /sublinks / child_links.
buttons: {object} - Object with buttons options.
instance: {object} - Model Instance connected with current view.
Description: Method, that handles view buttons (actions, operations, sublinks, child_links) and returns them.
getPathTemplateForRouter(path=””)¶
Arguments:
path: {string} - View path.
Description: Method returns string with template of route path for current view.
static getQuerySetConstructor(model)¶
Arguments:
model: {object} - Model object.
Description: Method, that returns QuerySet constructor for view.
Fields classes¶
Very often during creation of some new app developers need to make common fields of some base types and formats (string, boolean, number and so on). Create everytime similar functionality is rather boring and ineffective, so we tried ti solve this problem with the help of VST Utils.
VST Utils has set of built-in fields of the most common types and formats, that can be used for different cases.
For example, when you need to add some field to you web form, that should hide value of inserted password,
all you need to do - just set appropriate format password
instead of string
and VST Utils make all work for you.
Field classes are used in Model Instances as fields and also are used in Views Instances of list
type as filters.
All available fields classes are stored in the guiFields
variable. There are 44 fields formats in VST Utils:
base - base field, from which the most other fields are inherited;
string - string field, for inserting and representation of some short ‘string’ values;
textarea - string field, for inserting and representation of some long ‘string’ values;
number - number field, for inserting and representation of ‘number’ values;
integer - number field, for inserting and representation of values of ‘integer’ format;
int32 - number field, for inserting and representation of values of ‘int32’ format;
int64 - number field, for inserting and representation of values of ‘int64’ format;
double - number field, for inserting and representation of values of ‘double’ format;
float - number field, for inserting and representation of values of ‘float’ format;;
boolean - boolean field, for inserting and representation of ‘boolean’ values;
choices - string field, with strict set of preset values, user can only choose one of the available value variants;
autocomplete - string field, with set of preset values, user can either choose one of the available value variants or insert his own value;
password - string field, that hides inserted value by ‘*’ symbols;
file - string field, that can read content of the file;
secretfile - string field, that can read content of the file and then hide it from representation;
binfile - string field, that can read content of the file and convert it to the ‘base64’ format;
namedbinfile - field of JSON format, that takes and returns JSON with 2 properties: name (string) - name of file and content(base64 string) - content of file;
namedbinimage - field of JSON format, that takes and returns JSON with 2 properties: name (string) - name of image and content(base64 string) - content of image;
multiplenamedbinfile - field of JSON format, that takes and returns array with objects, consisting of 2 properties: name (string) - name of file and content(base64 string) - content of file;
multiplenamedbinimage - field of JSON format, that takes and returns array with objects, consisting of 2 properties: name (string) - name of image and content(base64 string) - content of image;
text_paragraph - string field, that is represented as text paragraph (without any inputs);
plain_text - string field, that saves all non-printing characters during representation;
html - string field, that contents different html tags and that renders them during representation;
date - date field, for inserting and representation of ‘date’ values in ‘YYYY-MM-DD’ format;
date_time - date field, for inserting and representation of ‘date’ values in ‘YYYY-MM-DD HH:mm’ format;
uptime - string field, that converts time duration (amount of seconds) into one of the most appropriate variants (23:59:59 / 01d 00:00:00 / 01m 30d 00:00:00 / 99y 11m 30d 22:23:24) due to the it’s value size;
time_interval - number field, that converts time from milliseconds into seconds;
crontab - string field, that has additional form for creation schedule in ‘crontab’ format;
json - field of JSON format, during representation it uses another guiFields for representation of current field properties;
api_object - field, that is used for representation of some Model Instance from API (value of this field is the whole Model Instance data). This is read only field;
fk - field, that is used for representation of some Model Instance from API (value of this field is the Model Instance Primary Key). During edit mode this field has strict set of preset values to choose;
fk_autocomplete - field, that is used for representation of some Model Instance from API (value of this field is the Model Instance Primary Key or some string). During edit mode user can either choose of the preset values from autocomplete list or insert his own value;
fk_multi_autocomplete - field, that is used for representation of some Model Instance from API (value of this field is the Model Instance Primary Key or some string). During edit mode user can either choose of the preset values from modal window or insert his own value;
color - string field, that stores HEX code of selected color;
inner_api_object - field, that is linked to the fields of another model;
api_data - field for representing some data from API;
dynamic - field, that can change its format depending on the values of surrounding fields;
hidden - field, that is hidden from representation;
form - field, that combines several other fields and stores those values as one JSON, where key - name of form field, value - value of form field;
button - special field for form field, imitates button in form;
string_array - field, that converts array with strings into one string;
string_id - string field, that is supposed to be used in URLs as ‘id’ key. It has additional validation, that checks, that field’s value is not equal to some other URL keys (new/ edit/ remove).
guiFields.base structure¶
All guiFields have common structure, so let’s look on fields properties on the example of guiFields.base:
mixins - array with mixin objects, that will be used during rendering of field component by Vue.js;
options - object with field’s options (settings), like name, title, required, readOnly, type, format, description and so on.
Let’s look on the guiFields.base methods.
constructor(options={})¶
Arguments:
options: {object} - Options of field instance.
Description: Standard constructor of JS class. This method creates new guiFields.base instance with current arguments.
toInner(data={})¶
Arguments:
data: {object} - Object with values of current field and fields from the same fields wrapper. For example, from the same Model Instance.
Description: Method, that converts field value from representation format into format appropriate for API.
toRepresent(data={})¶
Arguments:
data: {object} - Object with values of current field and fields from the same fields wrapper. For example, from the same Model Instance.
Description: Method, that converts field value from format appropriate for API into representation format.
validateValue(data={})¶
Arguments:
data: {object} - Object with values of current field and fields from the same fields wrapper. For example, from the same Model Instance.
Description: Method, that validates values. Method checks that value satisfies field’s options.
static get mixins()¶
Description: Static property for storing field mixins. Content of those mixins for each field is storing in gui_fields_mixins
variable.
Fields of other formats have the same structure and the same methods, but realisation of this methods can vary. Also some fields have some additional properties in options and some additional methods.