sky-list

Vue module for requesting search API (via axios) and displaying result with different pagination options

List of content

• Installation
• Usage
• Option tables
• Examples
• API Response Setup

Installation

npm install sky-list

yarn add sky-list

Usage

Import

import Vue from 'vue';

Different import approaches. The First provides the minified and compiled dist version, the other the raw .vue file.

import SkyList from 'sky-list';

// If you want to use the baseline scss add the following line
import '${YOUR-PROJECT-ROOT-PATH}/node_modules/sky-list/src/SkyList.scss';

Install plugin

Vue.use(SkyList);

Option tables

Props

Name	Type	Default	Options	Description
parameters	Object	{ keywords: '' }		Parameters to use in query declared with initial value
options	Object	{ api: '/umbraco/api/site/search/', limit: 10, showCount: false, paginationType: 'more', loadFetch: false, }	paginationType navigation numeric pagination more all	Change custom request setup. loadFetch: enables/disables fetch on page load. showCount: enables/disables "x" results found. api: your prefered endpoint
filter	Object	{}		Declare query properties to be handled as filters eg: { fitlerName: initialValue }
value-map	Object	{}		If a v-model returns a object and a prop is needed, it can be declared with initial value eg: { nestedPropName: initialValue }
validate-query	Function	query => query.keywords
live-search	Boolean	true		Enable/disable search on query change
query	Object	{}		Pass a query object directly to SkyList. Overrides internal query object. Useful for keeping query state outside of SkyList and only using it to fetch and render results
transform-params	Function	params => params		Hook to modify params before request is sent. Useful for transforming SkyList to integrate with endpoints that do not use the default param naming conventions
transform-result	Function	result => result		Hook to modify result before request is resolved. Useful for transforming the returned data to match the API response structure SkyList expects.

Slots

| Name | Slot-scope | Description | |--|--|--| | listForm | query Object
result Object | Slot for custom form setup to be v-model'ed against SkyList query | | listItem | index Number
listItem Object | Slot for custom item markup | | listAside | query Object
result Object | Slot for adding custom aside content next to the result list | | resultMessage | query Object
pagination Object | Slot for custom message when results are found | | noResultMessage | query Object | Slot for custom message when no results are found | | listMore | itemsLeft Number | Slot for custom show more button | | listPrev | | Slot for custom previous button | | listNext | | Slot for custom next button | | paginationBullet | count Number | Slot for custom pagination bullets | | filters | query Object
result Object
area Object | Slot for filtering result (i.e. by groups/areas etc.) |

Events

SkyList emits a few events for flexibility. This list will likely expand in the future. Example:

<sky-list @result="handleResultFn" />

| Name | Arguments | Description | |--|--|--| | result | result Object | Emitted every time result changes | | loadingBegin | none | Emitted whenever a fetch begins | | loadingEnd | none | Emitted when done fetching |

Examples

<sky-list>
    <div
        slot="listForm"
        slot-scope="{ query, result }"
    >
        <input type="text" v-model="query['keywords']" placeholder="Type your search query">
    </div>


    <div
        slot="listItem"
        slot-scope="{ index, item }"
        :item="item"
    >
        Custom handling of list item
    </div>
</sky-list>

Component options (with default values)

<sky-list
    :parameters="{ keywords: '' }" || Add your own key/value pair with initial values
    :options="{
        api: '/umbraco/api/site/search/',
        limit: 10,
        showCount: false, || true |false
        paginationType: 'more', || 'navigation' | 'pagination' | 'more' | 'all' | 'numeric'
        loadFetch: false,
    }"
    :validate-query="query => query.keywords" || parse in your own query validation
    :live-search="true" || true/false
    :value-map="{}" || If v-model returns an object setup rule for which prop to use eg. { nestedPropName: initialValue }
>
    <!-- content config here -->
    <!-- pagination config here -->
</sky-list>

Content slots (with default values)

Sky-list exposes different slot which can be customized

Message slots

resultMessage: custom message displayed when results are found

<sky-list ... >
    <span
        slot="resultMessage"
        slot-scope="{ query, pagination }"
    >
        Your search for <em>"{{query.keywords}}"</em> returned <em>{{pagination.total}} {{(pagination.total === 1) ? 'result' : 'results'}}</em>
    </span>
</sky-list>

noResultMessage: custom message displayed when no results are found

<sky-list ... >
    <span
        slot="noResultMessage"
        slot-scope="{ query }"
        v-text="'Your search for ${query.keywords} returned no results'"
    />
</sky-list>

List item slot

listItem: Slot for customizing list items. exposes item object and list index

<sky-list ...>
    <div
        slot="listItem"
        slot-scope="{ item, index }"
    >
        <small v-text="`No. ${index + 1}`"
        <h2 v-text="item.title" />
        <p v-text="item.teaser" />
    </div>
</sky-list>

Preferably this can be used with custom components like this

<sky-list ...>
    <MyComponent
        slot="listItem"
        slot-scope="{ item, index }"
        :my-prop-for-data="item"
        :my-prop-for-index="index"
    />
</sky-list>

Pagination slot options (with default values)

paginationType: 'more' | 'all'

Slot for customizing show more / all button

<sky-list ... >
    <span
        slot="listMore"
        slot-scope="{ itemsLeft }"
        v-text="`${itemsLeft} not displayed`"
    />
</sky-list>

paginationType: 'navigation' | 'pagination'

listPrev: Slot for customizing previous button nextPrev: Slot for customizing next button

<sky-list ... >
    <span slot="listPrev">Previous</span>
    <span slot="listNext">Next</span>
</sky-list>

paginationType: 'numeric' | 'pagination'

paginationBullet: Slot for customizing bullets

<sky-list ... >
    <span
        slot="paginationBullet"
        slot-scope=" { count }"
        v-text="`Page ${count}`"
    />
</sky-list>

API Response Setup

SkyList expects a response with the following setup

{
    "meta":{
        "code":200
    },
    "pagination":{
        "total":1,
        "limit":10,
        "offset":0
    },
    "data":[
        {
            title: 'item1',
            teaser: 'lorem ipsum',
        },
        {
            title: 'item2',
            teaser: '',
        },
        {
            title: 'item3',
            teaser: null,
        },
        ...
    ]
}

If your endpoint expects other names for pagination params than limit and offset the transform-params prop can be used to alter the params before requesting. Likewise, upon receiving data, you can use the transform-result prop to transform any data received to match the type of API response SkyList expects. Quick example of both in use:

<SkyList
    :options="{
        api: foreignEndpoint,
    }"
    :transform-params="params => ({
        q: params.keywords,
        startIndex: params.offset,
        maxResults: params.limit,
    })"
    :transform-result="result => ({
        pagination: {
            total: result.TotalResults,
            limit: result.EffectiveParameters.MaxResults,
            offset: result.Offset,
        },
        data: result.Documents,
    })"
>
    ...
</SkyList>

Credits

This module is made by the Frontenders at skybrud.dk. Feel free to use it in any way you want. Feedback, questions and bugreports should be posted as issues. Pull-requests appreciated!