ErdSoft Guidelines

# Vue.js

# Vue CLI - Installation

Vue CLI is a full system for rapid Vue.js development, providing:

  • Interactive project scaffolding via @vue/cli.
  • Zero config rapid prototyping via @vue/cli + @vue/cli-service-global.
  • A runtime dependency (@vue/cli-service) that is:
    • Upgradeable;
    • Built on top of webpack, with sensible defaults;
    • Configurable via in-project config file;
    • Extensible via plugins
  • A rich collection of official plugins integrating the best tools in the frontend ecosystem.
  • A full graphical user interface to create and manage Vue.js projects.

More info on: Vuejs Guide

Install Vue CLI globbaly

npm install -g @vue/cli

OR

yarn global add @vue/cli

# Vue CLI - Create a project

vue create [project-neve]

Choose the advanced option, example:

  • Babel, Router, Vuex
  • History mode: Y
  • In package.json

open the project via terminal

cd [project-neve]

install vuetify plugin, we use this for the icons, inputs etc.

vue add vuetify

Choose the default options

And after a

Yarn serve

Our development server is started, on port :8080

# API Handling

# API Call - fake backend

Before we start our project we have to communicate with our backend developers about these 4 things:

  • What data will we recieve and in what format.
  • What data will we send and in what format.
  • Where and when we need an API call.

So we can be closest to the end product

  • install Axios and Dotenv plugint
  • Create a server folder (don't forget to put the /server/node_modules in to the gitignore)
  • Create a package.json and a server.js file

# Package.json

{ 
  "name": "events-api", 
  "version": "1.0.0", 
  "description": "", 
  "main": "server.js", 
  "scripts": { 
    "start": "nodemon server.js", 
    "test": "echo \"Error: no test specified\" && exit 1" 
  }, 
  "author": "", 
  "license": "ISC", 
  "dependencies": { 
    "body-parser": "^1.19.0", 
    "cors": "^2.8.5", 
    "express": "^4.17.1", 
    "nodemon": "^1.19.4" 
  } 
}

# Server.js

const express = require('express'); 
const bodyParser = require('body-parser'); 
const cors = require('cors'); 
const app = express(); 
const port = 8000; 
app.use(bodyParser.json()); 
app.use(cors()); 
app.use(express.urlencoded({ extended: true }));  
app.get('/', (req, res) => { 
  res.send(`Hi! Server is listening on port ${port}`) 
}); 
// listen on the port 
app.listen(port);

install the packages with an

npm install

and after an

npm start

will start our server.

# concurrently

Concurrently on npm this is a package that will help us start our express server and our yarn serve with only one command.

Install the package, and after the installation add this line to the package.json

"dev": "concurrently \"cd server && npm run start\" \"vue-cli-service serve\"",

to the scripts part. It should look like this:

"scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "dev": "concurrently \"cd server && npm run start\" \"vue-cli-service serve\"",
    "i18n:report": "vue-cli-service i18n:report --src './src/**/*.?(js|vue)' --locales './src/locales/**/*.json'"
},

you can start it with a:

yarn dev

# Example API call

let products =  
{ 
    "status": "success", 
    "message": "A message explaining the error if the status index is anything but success.", 
    "products": [ 
        { 
            "id": 4, 
            "name": "Vruć burek sa mesom 275g", 
            "description": "Burek od razvučenog testa, filovano mešanim mlevenim mesom, lukom i začinima.", 
            "main_picture": “http://app.prolece.test:8080/img/parce.eeed7223.png", 
            "price": 150.00, 
            "prepare_time": 30, 
            "min_amount": 2 
        } 
    ] 
} 
app.get('/api/products', (req, res) => { 
    res.send(products); 
});

# API Call - frontend

expand our state in the store/index.js with the following:

axiosInstance: axios.create({ 
    baseURL: process.env.VUE_APP_URL, 
}),

Our base URL will be in the .env.local file

VUE_APP_URL=http://localhost:8000

This will change after a while. If we will have an admin, we just put the admin link in here.

WARNING

This will not work on a phone, if you want data in your mobile device, change the localhost part to your ipv4 address

# Example api call

We put the API calls in the created() lifecycle hook - more about that here

this.$store.state.axiosInstance 
    .get("/api/products") 

    .then(response => {}) 

    .catch(err => {})

# Example error handling

this.$store.state.axiosInstance
    .get("/api/")
    .then(response => {
        if(response.data['status'] != 'success' && response.data['message'] != '') {
            // error IN the API - error from backend
            this.showToast(response.data['message'], 3500);
            this.$router.go(-1);
        }
        else {
            // Do your thing
        }
    })
    .catch(err => {
        // error WITH the API
        this.showToast(err, 3500);
        // Do something
    })

# Localization - i18n

we use the i18n plugin

First time we will recieve the language from an URL parameter.

If the user didnt change the language we will handle the language like this (App.vue)

if(this.$store.state.lang == '' && urlParams.get('lang') != null) { 
    this.$store.state.lang = urlParams.get('lang'); 
    this.$i18n.locale = this.$store.state.lang; 
} 
else { 
    if(this.$store.state.lang != '') { 
        this.$i18n.locale = this.$store.state.lang; 
    } 
    else { 
        this.$i18n.locale = 'sr'; 
    } 
}

In the locales folder create our language files in local.json format

We store the selected language in the localstorage - So the selected language will be visible again when we reopen the app

# Example

  • html
{{ $t('products.description') }}
  • js
this.$t('products.error_msg')

# URL Attributes

App.vue

beforeCreate() {
    // save all the params
    const urlParams = new URLSearchParams(window.location.search); 

    // individual parameters
    this.$store.state.email = urlParams.get('email'); 
    this.$store.state.phone = urlParams.get('phone'); 
    this.$store.state.device_id = urlParams.get('device_id'); 
    this.$store.state.device_token = urlParams.get('device_token'); 
}

# Page Animation

# simple example

<transition :name="transition" mode="out-in"> 
    <router-view></router-view> 
</transition> 

.transform-enter-active, .transform-leave-active { 
    transition: transform .5s; 
} 
.transform-enter/* .fade-leave-active below version 2.1.8 */ { 
    transform: translateX(100%); 
} 
.transform-leave-to { 
    transform: translateX(-100%);  
}

# iOS animation

example on subotica_com_app project

<main>
    <transition :name="transitionName" v-on:before-enter="debug" v-on:before-leave="debug">
        <router-view/>
    </transition>
</main>

export default {
    data: function() {
        return {
            transitionName: "",
        }
    },
    watch: {
        $route(to, from) {
            this.transitionName = to.meta.page > from.meta.page ? "next" : "prev";
        }
    },
}

main {
    min-height: 100%;
    display: grid!important;
    grid-template: "main";
    flex: 1;
    background-color: white;
    position: relative;
    z-index: 0;
    overflow-x: hidden;
}

main > * {
    grid-area: main; /* Transition: make sections overlap on same cell */
    background-color: white;
    position: relative;
}

main > :first-child {
    z-index: 1; /* Prevent flickering on first frame when transition classes not added yet */
}

.next-leave-to {
    animation: leaveToLeft 700ms both cubic-bezier(0.165, 0.84, 0.44, 1);
    z-index: 0;
}

.next-enter-to {
    animation: enterFromRight 700ms both cubic-bezier(0.165, 0.84, 0.44, 1);
    z-index: 1;
}

.prev-leave-to {
    animation: leaveToRight 700ms both cubic-bezier(0.165, 0.84, 0.44, 1);
    z-index: 1;
}

.prev-enter-to {
    animation: enterFromLeft 700ms both cubic-bezier(0.165, 0.84, 0.44, 1);
    z-index: 0;
}

@keyframes leaveToLeft {
    from {
        transform: translateX(0);
    }
    to {
        transform: translateX(-25%);
        filter: brightness(0.5);
    }
}

@keyframes enterFromLeft {
    from {
        transform: translateX(-25%);
        filter: brightness(0.5);
    }
    to {
        transform: translateX(0);
    }
}

@keyframes leaveToRight {
    from {
        transform: translateX(0);
    }
    to {
        transform: translateX(100%);
    }
}

@keyframes enterFromRight {
    from {
        transform: translateX(100%);
    }
    to {
        transform: translateX(0);
    }
}

# Global SCSS

# assets/css/global.scss

We use this for all the global scss on the page. Example: forms, titles, buttons, notifications, plugin modifications

# assets/css/utilities.scss

Utility scss stores our global variables, like color codes, breakpoints, utility classes and all the mixins

module.exports = { 
    css: { 
        loaderOptions: { 
            sass: { 
                additionalData: `@import "src/assets/css/utilities.scss"; @import "src/assets/css/global.scss";`
            } 
        } 
    }
};

# Optional back button

Header.vue

We have to replace the menu button with the back button so we use a v-if

<button @click="$router.go(-1)" v-if="$route.query.name" class="header__menu"><v-icon>mdi-chevron-left</v-icon></button>

<div @click="openMenu()" v-else class="header__menu js-trigger-menu"><v-icon>mdi-menu</v-icon></div>

we replace the logo with the page name so

<router-link v-if="!$route.query.name" to="/clubs" class="header__logo"><img src="@/assets/images/barfly_logo.png" alt="" /></router-link> 

<div v-else class="header__title">{{ pageName }}</div> 

<router-link :to="{ name: 'Help', query: { name: 'FAQ' }}">{{ $t('navigation.help') }}</router-link>

WARNING

if we have an :id parameter, and we use a router.go(-1) and want call the $route.params.id we get a string not a number

# Block the back button

if we push the back button on mobile it will navigate the user to the root

document.addEventListener('backbutton', function(){ 
    if(this.$route.path!=='/') { 
        this.$router.push('/').catch(()=>{}); 
    } 
});

# Search component

We can use this to search on any list on the page. Example: barfly-client

# components/search.vue

The search component will be used to handle the input. With a v-model we bind the input value to a search variable. A watch function will watch this variable and emit it to the parent, basically we pass the value in real time.

<template> 
    <div class="search"> 
        <v-icon>mdi-magnify</v-icon> 
        <input type="text" :placeholder="$t('events.search')" v-model="search"> 
        <v-icon @click="clearInput()" v-if="search.length > 0">mdi-close-circle</v-icon> 
    </div> 
</template> 

<script> 
    export default { 
        data: function() { 
            return { 
                search: '', 
            } 
        }, 
        methods: { 
            clearInput: function() { 
                this.search = ''; 
            }, 
        }, 
        watch: { 
            search: { 
                handler: function() { 
                    this.$emit('searchData', this.search); 
                }, 
                deep: true  
            } 
        }, 
    } 
</script>

# List page

On the list page we have a handleData method, we fetch our data, and update our local search variable.

The computed method will handle our filter function. Basically if we have a for loop, we pass this variable to the v-for, and it will be filtered whenever you type in something to the input.

<template>
    <search @searchData="handleData($event)"></search>
</template>

<script> 
export default { 
        components: { 
            'search': Search 
        }, 
        data: function() { 
            return { 
                search: '', 
            } 
        }, 
        methods: { 
            handleData: function(e) { 
                this.search = e; 
            } 
        }, 
        computed: { 
            filteredEvents: function() { 
                return this.events.filter(events => { 
                    return (this.search.length === 0 || events.name.toLowerCase().includes(this.search.toLowerCase())) 
                }); 
            }, 
        }, 
    }
</script>

# Route

We import the vue components into the router/index.js file, and after that we connect them to a route, which will have a path and a reference name. We use router in history mode, and we set that when we change route, the page will scroll up to the top. That’s necessary, because at route change, it remembers our scroll position.

const router = new VueRouter({ 
    scrollBehavior() { 
        return { x: 0, y: 0 }; 
    }, 
    mode: 'history', 
    base: process.env.BASE_URL, 
    routes 
})

# Toast messages

With toasts, we display error messages, and responses from API.

For toasts, we use a plugin called vue-toast-notification, mainly because it has a very native android toast design. We create a mixin, which we can call globally from our project, if we want to display a toast message.

main.js

Vue.mixin({ 
    methods: { 
        showToast: function (message,time) { 
            this.$root.$toast.open({ 
                message: message, 
                type: 'default', 
                position: 'bottom', 
                duration: time 
            }); 
        }, 
    }, 
})

An example for calling the toast mixin. We have to pass two data at call. The message we want to display, and the duration of the toast.

this.showToast(data, 3500);
Last Updated: 10/12/2020, 4:03:43 PM

Nuxt.js →