Common Components

Vue.js Component Library

Introduction

This library aims to encapsulate all components used across the PrimeWeb ecosystem of applications.

Usage

! Please ensure you are logged into npm using a Primayer npm account to access our private repository !

npm install --save @primayer/common-components;

To set the library up, in your main.js file:

import CommonComponents from '@primayer/common-components';

import "@primayer/common-components/dist/common-components.css";

Vue.use(CommonComponents)

Library contents

This library provides the following:

Vue components

• CorrelationPeak,
• PipeDiagram,
• BPipeList,
• BPipeRow,
• BPipeTitle,
• Slider,
• FrequencyChart,
• AddLeak,
• DataCard,
• LeakCancel,
• MapPage,
• NavigateTo,
• Node,
• NodeCancel,
• NoWiFiWait,
• PipeCancel,
• Sort,
• SortUp,
• SortDown,
• BDeleteConfirmModal,
• BPrimeCard,
• BSaveAll,
• BYesNo,
• Brand,
• ClickToEdit,
• Loading,
• Overlay,
• Drag

Classes

• Details (correlation details class)

Mixins

• DraggableMixin

DraggableMixin

The draggable mixin provides a set of methods that can bee included on a vue component to make it draggle. Just using the mixin alone is not enough a few additional bits are needed in order to make the component draggable. note: using the Drag component in most cases is better than rolling your own with this mixin. If you want to roll your own, start by setting up the mix in as per normal:

import { DraggableMixin } from "@primayer/common-components";
export default {
  mixins: [DraggableMixin],
}

Next, in the template file rap your root node in a div and add a bound draggable class to it. we also need to add a set of events to the root node i.e. this:

<template>
  <rootNode>
    <!-- other elements -->
  </rootNode>
</template>

becomes:

<template>
  <div :class="{ draggable: draggable }">
    <rootNode
      @touchstart.stop="hang"
      @touchend.stop="drop"
      @mousedown.stop="hang"
      @mouseup.stop="drop"
      @touchmove.stop="iosMove"
    >
      <!-- other elements -->
    </rootNode>
  </div>
</template>

The draggable variable that toggles the draggable class is provided by the mixin in the form of a prop.

The last step is to define your draggable class. A basic default is provided by the library to use, but in most circumstances you will want to use your own. Here is the default that you can use as a starting point:

.draggable {
  position: absolute;
  top: 0;
  left: 0;
  z-index: 1;
}

The draggable mixin provides the following:

props

• draggable:
  • type: Boolean,
  • default: false
• width:
  • type: Number,
  • default: 0
• height:
  • type: Number,
  • default: 0
• parentWidth:
  • type: Number,
  • default: 0
• parentHeight:
  • type: Number,
  • default: 0
• initTop:
  • type: Number,
  • default: 0
• initLeft:
  • type: Number,
  • default: 0

these pros can be used to help controls how the draggable component is used by the components parent. For example the Correlation component in Analytics Details uses the initTop and initLeft to define a starting location like so:

<Correlation
  draggable
  :initTop="dragInitTop"
  :initLeft="dragInitLeft"
/>
<!-- other props removed for brevity-->

data properties

• shiftY
• shiftX
• left
• top
• elem
• isIos
• parent: object
  • width,
  • height

methods

• iosMove(e)
• elementMove(e)
• hang(e)
• drop

watchers

• width
• height

the methods and watchers are of no real use other than for the inner working of the mixin. They are listed to ensure that you know what the methods are called so that an accidental over write does not take place.

events

• dragging: fired when the element is being moved
• activated: fired when a element has been grabbed/activated
• dropped: fired when a element has been dropped.

life cycle hooks

• mounted: used to set up the internals of the mixin. configures the isIos property and uses initTop and initLeft to set starting values for top and left respectively.

example

basic example in full would look something like this:

example.vue

<template>
  <div :class="{ draggable: draggable }">
    <div
      @touchstart.stop="hang"
      @touchend.stop="drop"
      @mousedown.stop="hang"
      @mouseup.stop="drop"
      @touchmove.stop="iosMove"
    >
      <!-- other elements -->
    </div>
  </div>
</template>

<script>
import { DraggableMixin } from "@primayer/common-components";
export default {
  mixins: [DraggableMixin],
  //.. the rest of the JS
}
</script>

<style>
.draggable {
  position: absolute;
  top: 0;
  left: 0;
  z-index: 1;
}
/* the rest of the components css*/
</style>

parent.vue

<template>
  <div>
    <Example
      draggable
      :initTop="dragInitTop"
      :initLeft="dragInitLeft"
    />
  </div>
</template>

<script>
import Example from "./example";
export default {
  data() {
    return {
      dragInitTop: 5,
      dragInitLeft: 10,
    }
  }
}
</script>

<style>
</style>

Note:

some components have a capital letter 'b' as a prefix. This denotes that the component rely on Bootstrap Vue styling

Contribute

No special instructions. Follow the standard processes.

Build Process

In order to build the library for testing or distribution, in a terminal type:

npm run build-bundle

Publish

when logged into npm on your local terminal as a Primayer's npm account holder just run npm publish. Please ensure you update the version number in the package.json and create a release tag on GitHub.

Issues, Suggestions and Non-Technical contributions

Any Issues or suggestions should be marked in the repository issue tracker with the appropriate tags and all necessity details.

Any non-technical contributions will be handled on an ad-hoc bases. Usage Documentation/Media will be stored in the manner preferred by Primayer Ltd. as appropriate.

Licencing

No contributions, that are external from Primayer Ltd are allowed, unless express permission is provided by Primayer Ltd.'s management team.

The code and work in this repository (excluding 3rd party open source code) is proprietary and is owned by Primayer Ltd. The files stored in this repository are not for use, redistribution, sale or any other such activity, in part or as a whole. All rights reserved.