Skip to content

Home

Jump to bottom
andy.rothwell edited this page Feb 3, 2020 · 36 revisions

Welcome to the phila-vue-comps (pvc) wiki!

What is phila-vue-comps (@phila/vue-comps in npmjs.com)?

phila-vue-comps (pvc, stands for Philadelphia vue components) is a library of vue components which can be used in any vue project. Some of these are generic HTML components, wrapped in vue components. Many of these components wrap specific components from the City of Philadelphia Digital Standards so that they can be used with vue.

pvc does not run code to initiate a Vue instance or Vuex store. It is basically just an unordered list of ~30 MOSTLY unrelated .vue files. It also includes:

  • main.js – imports and exports all of the .vue files
  • store.js – creates and exports an object called ‘store’ which has some functions for using and storing data for the components
  • A util folder with 2 files specific to tasks:
    • generate-billing-xml.js
    • unique-id.js

In a project that USES pvc, you would:

  • In package.json add the dependency "@phila/vue-comps": "2.0.9", or in index.html add:

      <script src=“//unpkg.com/@phila/[email protected]/dist/phila-vue-comps.js></script>

  • Initiate the Vue instance and Vuex store, import the @phila/vue-comps package, and use individual .vue components from it

Example

An example project exists at pvc-example-app and a live example app exists here.

Overview

Components in this library are designed to allow you to create app elements without writing any HTML, and only having to include minimal instructions for the style, options, and data needed by the element.

The mixin TopicComponent is included in each component. (NOTE, this mixin should be renamed, so that the Topic component is not implied to be required); it includes in every component a common set of props:

  • slots
  • options
  • item

Since each component in the library can therefore be relied upon to include these props, all html, computeds, functions, and other things in each component have a fairly uniform way of being written.

Instructions for including the Components in an app

Many pages of this wiki provides 2 sets of instructions, for both of 2 hypothetical circumstances:

  1. You are writing an application using Vue.js and want to include the component within a Vue template. These sections are preceded by the heading "In a Vue template:".
  2. You are using a library like Mapboard which imports this library, and allows you to include the components by writing a config file. These sections are preceded by the heading "In a Mapboard config file:".

"Topic"-related Components

The components in this library were originally in the library Mapboard, and they were required to be within Topics. This is no longer true, but currently there are legacy idiosyncracies about how components work (which should be removed), related to Topics, in all components.

The 4 Topic-related components are included first here in the wiki, so that anything related to Topics in the following components can be assumed to be understood.

Components

Event Emitting

In order to separate this library from @phila/vue-datafetch (pvd), the components above are not inflexibly tied to pvd's methods.

If a component emits an event, you can make it do anything.

Many of the events of these components correspond to functions in pvd fairly closely (since the libraries were built together).

If you are using @phila/vue-datafetch, you may be able to handle any event emitted by these components simply calling the a function in the pvd $controller:

handleSearchFormSubmit(value) {
  this.$controller.handleSearchFormSubmit(value);
}

The Store

Instructions for using the PVC Store are here

Clone this wiki locally