@onenorth/vue-landing-page-mixin v2.0.2

Vue | Landing Page Mixin

Let's make some landing pages with VueJS!

How do I install it?

npm install -S @onenorth/vue-landing-page-mixin

Why do I want it?

Every landing page we make is pretty different visually!

However, they all share these common requirements:

• Set the API is called with the right query parameters.

• The back button works correctly.

• We can smoothly scroll to results.

This mixin handles all that stuff for you, without getting involved with your HTML or CSS!

That means you can integrate it with an existing app or component!

What does it look like?

Here's a working demo of it on Codepen.

And here's the same CodePen app, to show you how you might use it with require:

const LandingPage = require('@onenorth/vue-landing-page')

new Vue({
  el: '#app',
  mixins: [
    LandingPageMixin({
      endpoint: 'https://swapi.co/api/people'
    })
  ],
  data: {
    keyword: ''
  },
  computed: {
    results () {
      return this.response
        ? this.response.results
        : []
    },
    total () {
      return this.results.length
    },
  },
  methods: {
    onKeywordSubmit () {
      return this.setFilter('search', this.keyword)
        .then(this.updateUrl)
        .then(this.search)
        .then(this.clearKeyword)
        .catch(console.error)
    },
    clearKeyword () {
      this.keyword = ''
    }
  }
})

How do I use it?

The whole mixin revolves around one data property: filters.

filters is just an object that maps filter keys to their values and labels.

Most of the time you'll just:

• Use setFilter or clearFilter

• Chain on any other things you want ( updateUrl, search, scrollTo )

What is filters?

For example, a location dropdown might have an ID of 12345 and the label Chicago.

this.setFilter('location', '12345', 'Chicago')

Maybe the user also chooses the letter A for last name filters.

this.setFilter('letter', 'A')

And then they click "View More".

const currentPage = this.getFilter('page').value || 1
this.setFilter('page', currentPage + 1)

All of this can be modelled in filters:

{
  location: {
    value: '12345',
    label: 'Chicago'
  },
  letter: {
    value: 'A',
    label: 'A'
  },
  page: {
    value: 1,
    label: 1
  }
}

The key and value are used in the URL, and will be sent to your API endpoint on search().

The label is just for display on the page.

Why value AND label?

Storing the value alone would require a GUID lookup in most cases, so it seemed like a better idea to include the label in the data structure.

Rendering active filters?

If you need to display your active filters in a v-for loop, there is a computed value called filterAsList that returns the same filters as this list:

[
  { key: 'location', value: '12345', label: 'Chicago' },
  { key: 'letter', value: 'A', label: 'A' },
  { key: 'page', value: 1, label: 1 }
]

It's pretty common to keep the page filter out of the active filters section, so the activeFilterList is probably what you'll want to use instead:

[
  { key: 'location', value: '12345', label: 'Chicago' },
  { key: 'letter', value: 'A', label: 'A' }
]

API Documentation

A deeper look at the things you can use!

filters

This is an object that maps a key to it's value and label!

Here's an example of what that might look like:

{
  service: { value: '1234', label: 'Litigation' },
  keyword: { value: 'ryan', label: 'ryan' }
}

The value is used in the URL, and the label is a pretty display name. This is especially useful for dropdowns.

isSearching

true if we are currently performing a search, false otherwise. Useful for loading spinners.

{
  isSearching: true
}

paginationFilterNames

A list of the keys that are used for pagination.

{
  paginationFilterNames: [ 'page' ]
}

response

The response from the API endpoint. (The type is whatever type your endpoint returns)

{
  response: {
    page: 1,
    total: 15,
    hasMore: true,
    results: [ ... ]
  }
}

Computed

filtersAsList

The filters property as an array, so you can .map, .filter, or .reduce through it easily.

[
  { key: 'location', value: '12345', label: 'Chicago' },
  { key: 'letter', value: 'A', label: 'A' },
  { key: 'page', value: 1, label: 1 }
]

activeFilterList

Returns a list of filters that aren't used for pagination.

Useful for displaying active filters.

[
  { key: 'location', value: '12345', label: 'Chicago' },
  { key: 'letter', value: 'A', label: 'A' }
]

hasAnyFilters

Returns true if the filters object is empty.

true

queryString

The query string generated from the filters object. Used in fullUrl and apiUrl.

'?letter=A&location=12345&page=1'

apiUrl

The full computed API endpoint, based on the queryString. This is what the search method will use when it is called.

'https://www.somesite.com/api/people?letter=A&location=12345&page=1'

fullUrl

The full URL of the current page. Used to update browser history.

'https://www.somesite.com/people?letter=A&location=12345&page=1'

Methods

getFilter(key)

Get a filter by it's key. The equivalent of filters[key].

Returns a { value: string, label: string } or undefined if no filter exists for that key.

this.getFilter('location')       // { value: '12345', label: 'Chicago' }
this.getFilter('page').value     // 1
this.getFilter('location').label // 'Chicago'

setFilter(key, value, label?)

Sets a filter at key, where the value should be the same as the label.

// Adds { location: { value: '12345', label: 'Chicago' } }
this.setFilter('location', '12345', 'Chicago')

// Missing label input will default to value!
this.setFilter('letter', 'A') // { letter: { value: 'A', label: 'A' } }

clearFilter(key)

Clears the filter at key.

// filters: {
//   location: { value: '12345', label: 'Chicago' },
//   letter: { value: 'A', label: 'A' },
//   page: { value: 1, label: 1 }
// }
this.clearFilter('location')
this.clearFilter('letter')
// filters: {
//   page: { value: 1,  label: 1 }
// }

clearAllFilters()

Clears all filters, and returns an empty object.

// filters: {
//   location: { value: '12345', label: 'Chicago' },
//   letter: { value: 'A', label: 'A' },
//   page: { value: 1, label: 1 }
// }
this.clearAllFilters()
// filters: {}

clearPage()

Clears all page filters, and returns the remaining ones.

Commonly used after a filter change, for resetting the page back to 1.

// {
//   location: { value: '12345', label: 'Chicago' },
//   letter: { value: 'A', label: 'A' },
//   page: { value: 1, label: 1 }
// }
this.clearPage()
// {
//   location: { value: '12345', label: 'Chicago' },
//   letter: { value: 'A', label: 'A' }
// }

clearResponse()

Reset the response object to null.

// response: {
//   page: 2
//   total: 6,
//   hasMore: false,
//   results: [ {} ]
// }
this.clearResponse()
// response: null

updateUrl()

This will set the URL and the browser history, so the back button works as expected!

search()

Perform a search at the current apiUrl with a GET.

scrollTo()

Smoothly scrolls to the provided ID.

This is commonly used after performing a search.

By default, this scrolls to an element with id="results".