Vue-crudengine

Crudengine is a program to help us to get rid of boilerplate programing. This package is a wrapper for crudengine, so we don't have to write http calls, but neet little functions, that are much easier to remember and read. This package is meant to be used in pair with the crudengine.

Disclaimer

This package is very much under development and all functions are subject to change. Also some functionality may not be documented or they might not work at all.

If you find anything that isn't working or not up to the documentation let us know or create a pull request over on github. Thank You in advance!

Table of contents

• Getting started
• Features
• About protobuf

Getting started

We intended vue-crudengine to be a plugin for nuxtjs but it can be used some other way. For now we will focus on how to use with nuxtjs.

// in plugins/vue-crudengine.js
import vueCrudengine from 'vue-crudengine'

export default async ( ctx, inject ) => {
  // the constructor expects two parameters: axios, backend crudengine prefix
  const API = new vueCrudengine(ctx.$axios, 'api')

  // If we are planning to use protobuf
  await API.initProto('/api.proto') // this should be in the static folder and named api.proto
  // we can get this file by issuing a call to /api/protofile on the backend

  // inject vue-crudengine into nuxt context
  ctx.$API = API
  inject( 'API', API ) // Use in .vue files as this.$API
}

// nuxt.config.js
export  default {
  plugins: ['~/plugins/vue-crudengine']
}

Functions

Note: All functions return a promise.

Schema

Special function that returns everything there is to know about the schemas we registered. Schema names will be the keys of the object. If ModelName is given only that models schema will be returned

• Method: GET
• Resolves into: Object

this.$API.Schema( ModelName = null ) // ModelName is optional
.then(schema => ... )
.catch( Error => ... )

SchemaKeys

Returns the key paths to the schema

• Method: GET
• Resolves into: Array of Strings e.g. ['name.surname', name.firstname]

this.$API.SchemaKeys( ModelName = null ) // ModelName is optional
.then(schema => ... )
.catch( Error => ... )

Read

Returns documents for the schema.

• Method: GET
• Resolves into: Array of Objects

this.$API.Read( ModelName [, OptionsObject ])
.then( Documents => ... )
.catch( Error => ... )

Options:

| key | description | type | example | |:-:|:-:|:-:|:-:| | filter | Mongodb query | Object | { age: 18 } | | projection | Fields to include in results. Uses mongodb projection. | array of strings | ['name'] | | sort | Mongodb sort | object | { age : -1 } | | skip | The number of documents to skip in the results set. | number | 10 | | limit | The number of documents to include in the results set. | number | 10 |

Get

Find one document by id.

• Method: GET
• Resolves into: Object

this.$API.Get( ModelName, DocumentId [, OptionsObject ])
.then( Document => ... )
.catch( Error => ... )

Options:

| key | description | type | example | |:-:|:-:|:-:|:-:| | projection | Fields to include in projection. | array of strings | ['name'] |

ProtoRead [BETA]

The same as Read but uses protobuf for speed. 😎

• Method: GET
• Resolves into: ArrayBuffer

this.$API.Get( ModelName [, OptionsObject ])
.then( Documents => ... )
.catch( Error => ... )

Params:

| key | description | type | example | |:-:|:-:|:-:|:-:| | filter | Mongodb query | Object | { age: { $exists: true } } | | projection | Fields to include in projection | array of strings | ['name'] | | sort | Mongodb sort | object | { age : -1, posts: 1 } | | skip | The number of documents to skip in the results set. | number | 10 | | limit | The number of documents to include in the results set. | number | 10 |

TableHeaders

Get the keys, names, descriptions and other meaningful properties for the schema and for the subschemas (refs to other schemas). E.g.: useful for tables.

• Methods: GET
• Resolves into: Array of Objects

this.$API.TableHeaders( ModelName )
.then( Headers => ... )
.catch( Error => ... )

GetService

Runs a function in services.

• Method: GET
• Resolves into: Any

this.$API.GetService( ServiceName, FunctionName, Params )
.then( Result => ... )
.catch( Error => ... )

Params: whatever we send. See Services section for more info!

RunService

Runs a function in services.

• Method: POST
• Resolves into: Any

this.$API.RunService( ServiceName, FunctionName, Params )
.then( Result => ... )
.catch( Error => ... )

Params: whatever we send. See Services section for more info!

The difference between the two is just the method. With POST you can send data more easily and not get the results cached, with GET you can get the results cached.

Create

Creates a new document in database. If the DocumentObject contains a file it will be uploaded, then the file will be replaced with the file path.

• Method: POST
• Resolves into: Object (mongodb document)

this.$API.Create( ModelName, DocumentObject )
.then( Document => ... )
.catch( Error => ... )

DocumentObject: An object that matches the mongoose schema.

UploadFile

Uploads a given file.

• Method: POST
• Resolves into: { path: '/static/myFilesUniqueName.pdf', originalname: "IGaveThisFileAName.pdf" }

this.$API.UploadFile( MyFile )
.then( Response => ... )
.catch( Error => ... )

GetFileUrl

Get the file path for the file.

• Method: GET
• Returns: { path, thumbnail }

this.$API.GetFileUrl( File )

GetFile

Get the url for the downloaded file.

• Method: GET
• Returns: blob url (String)

this.$API.GetFile( File )

GetThumbnail

Get the url for the downloaded thumbnail.

• Method: GET
• Returns: blob url (String)

this.$API.GetThumbnail( File )

Update

Updates a document in database. If there is a file in the object, crudengine will upload it, but will not delete the previous file.

• Method: PATCH
• Resolves into: WriteResults

this.$API.Update( ModelName, DocumentObject )
.then( Document => ... )
.catch( Error => ... )

DocumentObject: A mongodb document that we modified. (ObjectID included)

Delete

Deletes a document from database. Files will not be deleted, we have to do that manually, to avoid accidental file deletion.

• Method: DELETE
• Resolves into: WriteResults

this.$API.Delete( ModelName, Id )
.then( Document => ... )
.catch( Error => ... )

DeleteFile

Deletes a file on a given path. Only paths, that are inside the /api/static folder will be accepted. If there is, deletes thumbnail as well.

• Method: DELETE
• Resolves into: Empty response

this.$API.DeleteFile( PathToMyFile )
.then( EmptyResponse => ... )
.catch( Error => ... )

Table

Combines the TableHeaders and the Read function into one function.

• Method: GET
• Resolves into: { Headers, Data }

this.$API.Table( ModelName [, OptionsObject ])
.then( Documents => ... )
.catch( Error => ... )

Params:

| key | description | type | example | |:-:|:-:|:-:|:-:| | filter | Mongodb query | Object | { age: { $exists: true } } | | projection | Fields to include in projection | array of strings | ['name'] | | sort | Mongodb sort | object | { age : -1, posts: 1 } | | skip | The number of documents to skip in the results set. | number | 10 | | limit | The number of documents to include in the results set. | number | 10 |

ProtoTable [BETA]

Combines the TableHeaders and the ProtoRead function into one function.

• Method: GET
• Resolves into: { Headers, Data }

this.$API.ProtoTable( ModelName [, OptionsObject ])
.then( Documents => ... )
.catch( Error => ... )

Params:

| key | description | type | example | |:-:|:-:|:-:|:-:| | filter | Mongodb query | Object | { age: { $exists: true } } | | projection | Fields to include in projection | array of strings | ['name'] | | sort | Mongodb sort | object | { age : -1, posts: 1 } | | skip | The number of documents to skip in the results set. | number | 10 | | limit | The number of documents to include in the results set. | number | 10 |

Proto

JSON.stringify is cpu intensive and slow. When querying a large set of data it is beneficial to use something lighter than JSON. We use protocol buffers to help with that. In order to be able to work with protobuf normally we need to create a .proto file that includes all schemas and a bit more. Crudengine will do that for us automatically.

If we want to decode the data crudengine serves the .proto file at /api/protofile

Currently there is no way using protobufjs to automate getting the generated proto file from the backend, but we'll integrate it as soon as they make it possible.

Authors

• Horváth Bálint
• Zákány Balázs

Changelog

• 2020-05-25 File handling added.

Contributing

Email us at zkny or horvbalint or visit the github page