vue-crudengine

Crudengine frontend api plugin for vuejs

Usage no npm install needed!

<script type="module">
  import vueCrudengine from 'https://cdn.skypack.dev/vue-crudengine';
</script>

README

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

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.

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.

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