PrimeWeb Google Map

Vue.js Component Library

Introduction

This library aims to encapsulate how PrimeWeb uses the Google Maps JavaScript API. This will enable Primayer's developers to spend less time creating google map implementations multiple times across PrimeWeb and more time dealing with the unique requirements of a PrimeWeb Application. This library serves as a central point for Google Map implementations for use in Vue.js based applications.

Usage

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

In order to use this library you will first need to install and set up its peer dependencies

from your project root folder in a Terminal, Console, PowerShell or CMD:

npm install --save vue2-google-maps

To set up the peer dependencies add the following to your main.js:

import * as VueGoogleMaps from "vue2-google-maps";
Vue.use(VueGoogleMaps, {
  load: {
    key: " { ... INSERT YOUR GOOGLE API KEY HERE ... } ",
    libraries: "places,drawing,visualization"
  }
});

To install the library, from your project root folder in a Terminal, Console, PowerShell or CMD:

npm install --save @primayer/prime-google-map

To set the library up, in your main.js file: import PrimeGoogleMap from '@primayer/prime-google-map'; Vue.use(PrimeGoogleMap)

Here is a simple example of how to use the component:

<template>
  <div>
    <prime-google-map
    :nodes="nodes"
    :pipes="pipes"
    ></prime-google-map>
  </div>
</template>

<script>
// import models
import { Pipe, Node } from 'prime-google-map'

// imports for testing purposes only
import * as ExamplePipes from './apiExamples/Pipes'
import * as ExampleNodes from './apiExamples/Nodes'

export default {
  name: 'app',
  computed: {
    pipes() {
      // dummy get method for testing
      let pipes = [];
      ExamplePipes.ExamplePipes.forEach(rawPipe => {
        pipes.push(new Pipe(rawPipe))
      })
      return pipes
    },
    nodes() {
      // dummy get method for testing
      let nodes = [];
      ExampleNodes.ExampleNodes.forEach(rawNode => {
        nodes.push(new Node(rawNode))
      })
      return nodes
    }
  }
}
</script>

Library contents

Here is a list of the available Vue components provided by this library:

• PrimeGoogleMap

Here is a list of available JS classes provided by this library:

• Pipe
• Section
• Node
• Logger
• GenericMarkerData
• LatLong
• MapOptions

Here are the other provided contents of the library:

• MaterialDetails - an object literal constant used to describe materials for pipes

Prime Google Maps

This component exposes the following options

props:

• mapOptions. Type: MapOptions. This optional prop requires an object of the time MapOptions and is used to set up the google map.
• mapCursor. Type; String. A URL targeting the image to use as a draggable cursor.
• nodes. Type: Array, of Node objects. Default is an empty array. A validator is used to enforce the type of object given.
• pipes. Type: Array, of Pipes objects. Default is an empty array. A validator is used to enforce the type of object given.
• loggers. Type: Array, of Logger objects. Default is an empty array. A validator is used to enforce the type of object given.
• markers. Type: Array, of GenericMarkerData objects or objects that are derived inherited from the GenericMarkerData class. Default is an empty array. A validator is used to enforce the type of object given.
• activePipes. Type: Array, of Pipes objects. The given array of Pipes is expected to be a sub set of the array given to pipes. Default is an empty array. A validator is used to enforce the type of object given.

v-models:

None. No v-models are exposed

events:

All of the most commonly used google maps events are provided. As Google Maps events natively share similar/same names a prefix has bee added for clarity. The prefixes are:

'map-' : for map based events. 'node-' : for node based events. 'logger-' : for logger based events. 'pipe-' : for pipe based events, including active pipes. 'marker-' : for generic marker based events.

Here are the provided map events, with the prefix:

• map-bounds_changed
• map-click
• map-dblclick
• map-drag
• map-dragend
• map-dragstart
• map-idle
• map-mousemove
• map-mouseout
• map-mouseover
• map-resize
• map-rightclick
• map-tilesloaded
• map-center_changed
• map-heading_changed
• map-maptypeid_canged
• map-tilt_changed
• map-zoom_changed

Here are the events exposed for Nodes, Loggers, Generic Markers, and Pipes. These excluding the prefix.

• click
• dblclick
• drag
• dragend
• dragstart
• mousedown
• mouseout
• mouseover
• mouseup
• rightclick

Please add the prefix for correct use. For example:

node-click or marker-mouseover or pipe-dblclick

In actual use and example would look like this:

<template>
  <div>
    <prime-google-map
    @logger-click="onLoggerClick"
    ></prime-google-map>
  </div>
</template>

<script>
export default {
  name: 'app',
  methods: {
      onLoggerClick(event, logger) {
          console.log(event) // prints event object
          console.log(logger) // prints logger object
      }
  }
}
</script>

Do not forget, if you are using the provided classes rather than making your own you need to use the following statement to import them:

// import models
import { Pipe, Node } from 'prime-google-map'

The { } are required

MapOptions Class

Constructor:

The constructor takes the same object literal as a Google Map Object. However some have not yet been included, the available options are:

• centre
• heading
• mapTypeId
• options
• tilt
• zoom

for more information check out Google Maps API docs here

Properties:

None

Methods:

None

LatLong Class

Constructor:

This class is considered a helper towards standardization, therefor its constructor can expect a wider than expected range on object literals. This class accepts:

• A two element long array of Strings or Numbers
• An object literal with the keys:
  • m_Item1
  • m_Item2
• An object literal with the keys:
  • latitude
  • longitude

Properties:

• latitude
• longitude
• googleLatLong (getter only)

Methods:

None

Generic Marker Class

Constructor:

The constructor expects an object literal that contains the following:

• id : Any
• name: String
• latitude: Number
• longitude: Number

The constructor is also set up to accept Google Map Marker options in its object literal:

• animation
• attribution
• clickable
• cursor
• draggable
• icon
• label
• opacity;
• options
• place
• shape
• title
• zIndex

more information about these can be found here

Properties:

All of the properties set in the constructor are available. Plus these additional available properties:

• googleLocation (getter only)

Methods:

None

Node Class

inherits from Generic Marker Class

Constructor:

The constructor takes the same object literal as a Generic Marker Class with the additional properties available:

• global_user
• group_id
• icon_url
• LocationTuple (becomes a LatLong object)

Properties:

Same as Generic Marker Class. With the constructor given keys changed to:

• globalUser
• groupId
• location (a LatLong object)

Methods:

None

Logger Class

inherits from Generic Marker Class

Constructor:

The constructor takes the same object literal as a Generic Marker Class with the additional properties available:

• coords (becomes a LatLong object)
• loggerType
• isNode
• image

Properties:

Same as Generic Marker Class

Methods:

None

Pipe Class

Constructor:

The constructor expects an object literal with the following keys:

• Id
• Group
• Coords
• User
• CreatedOn
• TotalLength
• LoggerId
• Enabled
• Colour
• Sections (becomes array of Sections objects, Section call not exposed)
• Loggers
• StartLatLng
• EndLatLng

These keys match with the pipe JSON object returned by PrimeWeb API. So Pipe JSON objects can be converted to Pipe Objects directly

Properties:

All of the constructor keys are properties, however they are in camelCase not PascalCase. The following additional properties also are available:

• calculatedTotalLength (getter only)
• sectionsCount (getter only)
• materialBreakDown (getter only)
• googleCoords (getter only)
• googlePolyLineOpt (getter only)
• googlePolyLineStroke (getter only)

Methods:

• coords(), return LatLong Object

Section Class

Constructor:

The constructor expects an object literal with the following keys:

• PipeId
• Id
• Material
• Length
• Diameter
• Velocity
• Default
• Abrev
• Pixels

These keys match with the section JSON object returned by PrimeWeb API. So section JSON objects can be converted to Section Objects directly. When a Pipe is constructed sections are automatically created in the pipe class, the type if the sections used is this Section class.

Properties:

All of the constructor keys are properties, however they are in camelCase not PascalCase. The following additional properties also are available:

• materialName (getter only)

Methods:

None

Contribute

As a fellow member of Primayer's development team, contribution to this library is welcomed and encouraged.

Once the repository is on you dev machine. Navigate to the project root in a terminal of some kind. From the project root run npm install, then navigate to the test app root folder cd testapp and run npm install again. Next set a npm link between the library and the test app. so from the test app root folder:

cd ..

npm link

cd testapp

npm link @primayer/prime-google-map

If you run a npm install at any point on the library or the test app the npm link will be destroyed and will have to be remade.

Build Process

In order to build the library for testing or distribution:

From the library root folder, in a terminal run npm run build. A "dist" folder will be produced and will contain the complied library for redistribution.

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.