Introduction

We've been working a lot with other libraries that generate administration dashboards, routes, resources in other javascript frameworks, but did not find any Vue library capable of performing this kind of solution, except of many really impressive Vue libraries that provide UI components for admin dashboards. We are pretty convinced Vue's learning curve is gentle, so we thought we could try and build our own tool to help building administration applications.

Dependencies and third party libraries

We assume your project is currently shipped with the following dependencies:

• vue-router: used to dynamically create routes and bind components to them. We also take advantage of some of the route hooks.
• vuex: lets us globally share information between the core application and component customizations of a library user.
• vuetify: we basically don't want to implement UI components from scratch, plus their widgets are awesome. The drawer, buttons, cards and CRUD views are implemented with Vuetify, but you could use any other UI framework if you want to build your own CRUD views. Take the magazines view as example.

Core Libaries vue-admin-js depends on

• vuex-crud: this lightweight tool creates the resources crud store state, mutations and getters for us.

Installation

# using npm
npm i --save vue-admin-js

Configuration

Auth Provider

You will have to configure an adapter to communicate with your REST api.

We currently provide a simple example using an axios client in the demo app. Though we intend to keep developing other kind of adapters for different node backend frameworks, they will live in separate packages.

Anyways, we hope the axios example encourages you to write your own adapter until we release the adapters guide. The @va-auth module uses the vuex store and expects a user to make use of the action types it provides.

Usage

App.vue

<template>
  <Admin :authProvider="authProvider">
    <Resource
      name="articles"
      resourceIdName="id"
      userPermissionsField="permissions"
      apiUrl="http://localhost:8888/api/"
    >
      <View slot="list"   :component="ListArticles" :permissions="['admin']" />
      <View slot="show"   :component="ShowArticles" :permissions="['admin']" />
      <View slot="create" :component="CreateArticles" :permissions="['admin']" />
      <View slot="edit"   :component="EditArticles" :isPublic="true" />
    </Resource>
  </Admin>
</template>

<script>
  import { Admin, Resource } from 'vue-admin-js'
  // Your components
  import ListArticles from './components/articles/ListArticles'
  import ShowArticles from './components/articles/ShowArticles'
  import CreateArticles from './components/articles/CreateArticles'
  import EditArticles from './components/articles/EditArticles'
  import createAxiosAdapter from './va-auth-adapter/axios.adapter'
  import axios from 'axios'

  const authUrl = 'http://localhost:8888/api/auth'
  const client = axios

  const authProvider = createAxiosAdapter(client, { authUrl })

  export default {
    name: 'App',
    components: {
      Admin,
      Resource
    },
    data() {
      return {
        authProvider,
        // Your Components
        ListArticles,
        ShowArticles,
        CreateArticles,
        EditArticles,
      }
    }
  }
</script>

ListArticles.vue

<template>
  <List>
    <p source="id" :sortable="true" headerText="ID" alignHeader="left" alignContent="left" />
    <h3 source="title" :sortable="true" headerText="Title" alignHeader="center" alignContent="left" />
    <p source="content" :sortable="true" headerText="Content" alignHeader="center" alignContent="right" />
  </List>
</template>

<script>
import { List } from 'vue-admin-js'

export default {
  name: 'ListArticles',
  components: {
    List
  }
}
</script>

Using your own custom authentication component

By default Vue-Admin provides you with a default authentication view, but you may desire to use your own custom view to authenticate. In that case, you just need to pass it as a property in the Admin component like the following.

Example of custom authentication component usage

  ...
  <Admin :authProvider="authProvider" :authLayout="AuthCustomView">
  ...

In order to use the available authentication mechanism you have to declare a prop with a va object field which will contain the bounded login function.

Example of provided login mechanism usage in custom auth component

  ...
  props: {
    va: {
      type: Object,
      required: true
    }
  },
  ...
  methods: {
    login() {
      this.va.login(this.username, this.password)
    }
  }
  ...

Examples

For a complete example take a look at the demo files

Some of the custom components examples can be found in the magazines views

Contributing and Future features

Nothing could make us happier than the community involvement into this framework, so if you feel like contributing or just sharing an idea for us to improve the library, please do not hesitate to fork vue-admin-js from our repository, comment or open an issue with the available labels.

Starting a new project

Using the official Vue cli

# install the official vue cli
npm install -g @vue/cli-init
# initialise the project
vue init webpack my-project
cd my-project
# install required dependencies
npm install --save vue-admin-js vue-router vuex vuex-crud vuetify
# run the project
npm run dev

...and start customizing your App.vue

Getting it running

# clone the repository
git clone https://github.com/Cambalab/vue-admin.git
# navigate to the repository and install npm dependencies
cd vue-admin && npm install
# install the test server dependencies
cd ../utils/server-test && npm install
# run the server (we prefer to use the same port as Cypress server)
PORT=8888 node server
# in another terminal go to the repository directory and run the Vue application
npm run serve

Running the tests

We use the vue-cli-service to run the tests

end to end tests

# go to the root of the project to run the e2e tests script
# there's no need to run the test server, we use the Cypress server
npm run test:e2e

unit tests

# in the root of the project run the unit tests script
npm run test:unit