Kongponents

# Catalog

KCatalog - A grid view of KCards

<KCatalog :fetcher="fetcher" />

Note

The KCatalog component requires the @vue/composition-api package as a peerDependency. You must manually add the package to your host project by running the following

yarn add @vue/composition-api

When importing KCatalog into your project, you will likely need to explicity import the vue file as shown below

import KCatalog from '@kongponents/KCatalog/KCatalog.vue'

NOTE

KCatalog implements KIcon which imports .svg files directly, so a loader is needed in order to render these in your application such as the webpack raw-loader. See here for more information.

Pass a fetcher function to build a slot-able card catalog.

<KCatalog :fetcher="fetcher" />

# Props

# title

The catalog title.

Look Mah!

<KCatalog title="Look Mah!" :fetcher="fetcher" />

# cardSize

Size of the cards. Supports values small, medium (default), and large.

Small Cards

Medium Cards

Large Cards

<KCatalog title="Small Cards" :fetcher="fetcher" cardSize="small" />
<KCatalog title="Medium Cards" :fetcher="fetcher" />
<KCatalog title="Large Cards" :fetcher="fetcher" cardSize="large" />

# noTruncation

By default truncation of items with long descriptions is enabled at 5 lines. Enable noTruncation to turn it off.

Truncate me

No truncation allowed!!

const longItem = {
  title: "Item long",
  description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas in tempus lorem, et molestie quam. Praesent sapien massa, posuere et volutpat nec, imperdiet a dui. Fusce non leo posuere, molestie neque et, posuere ex. Nullam euismod tortor in est sagittis iaculis. In sodales bibendum nulla nec feugiat."
}

<KCatalog title="Truncate me" :fetcher="fetcherLong" />
<KCatalog title="No truncation allowed!!" :fetcher="fetcherLong" no-truncation />

# hasError

See the State section about hasError

# isLoading

See the State section about isLoading

# fetcher

Use a custom fetcher function to fetch card catalog items and leverage server-side pagination.

Note

All fetcher functions should take a single param. This parameter is a JSON object supporting the following properties:

  • Pagination support:
    • page: the currently visible page - starts at 1
    • pageSize: the number of items to display per page

Note

All fetcher functions should return a JSON object. This JSON object should contain the following properties:

  • total - the total count of catalog items (if using pagination)
  • data - an array of JSON objects to populate the card catalog with

Example fetcher function:

fetcher(payload) {
  const params = {
    _limit: payload.pageSize,
    _page: payload.page
  }

  return axios.get('/user_list', {
    baseURL: 'https://kongponents.dev/api',
    params
  }).then(res => {
    return {
      total: res.total,
      data: res.data
    }
  })
}

# initialFetcherParams

Pass in an object of parameters for the initial fetcher function call. If not provided, will default to the following values:

{ pageSize: 15, page: 1 }

# fetcherCacheKey

The fetcher functionality makes use of SWRV to handle caching of response data. Whenever the cache key is changed the fetcher will automatically refire and repopulate the table data.

<template>
  <KCatalog
    :fetcher="fetcher"
    :fetcherCacheKey="cacheKey" />
</template>

<script>
export default {
  data () {
    return {
      cacheKey: 1
    }
  },
  methods: {
    itemDeleted () {
      // take an action on the DOM
      cacheKey++ // triggers refetch
    }
  }
}
</script>

# searchInput

Pass in a string of search input for server-side table filtering. See the Server-side function section for an example.

# paginationTotalItems

Pass the total number of items in the set to populate the pagination text:

1 to 20 of <paginationTotalItems>

If not provided the fetcher response should return a top-level property total or return a data property that is an array.

# paginationNeighbors

Pass in a number of pagination neighbors to be used by the pagination component. See more detail in the Pagination docs.

# paginationPageSizes

Pass in an array of page sizes for the page size dropdown. If not provided will default to the following:

[15, 30, 50, 75, 100]

# disablePaginationPageJump

Set this to true to limit pagination navigation to previous / next page only.

<template>
  <KCatalog
    :fetcher="fetcher"
    :disablePaginationPageJump="true" />
</template>

# disablePagination

Set this to true to remove the pagination bar when using a fetcher.

# KCatalogItem

KCatalog generates a KCatalogItem for each item in the items property. At the most basic level, KCatalogItem is a wrapper around KCard to display correctly inside KCatalog. You can use the body slot of the KCatalog to manually create your own catalog items.

# Properties

  • item - the card content is built from this, it expects a title and optionally a description.

    { title: 'some title', description: 'some description' }

  • truncate - a boolean (default to true), whether or not to truncate the description text.

<KCatalogItem
  :item="item"
  :truncate="false"
  class="catalog-item"
/>

# Card Slots

  • cardTitle - the title content for the card
  • cardBody - the body content for the card
<KCatalogItem>
  <template v-slot:cardTitle>
    <KIcon
      icon="profile"
      color="#7F01FE"
      size="44" />
    Look Mah!
  </template>
  <template v-slot:cardBody>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi nec justo libero. Nullam accumsan quis ipsum vitae tempus. Integer non pharetra orci. Suspendisse potenti.</template>
</KCatalogItem>

# States

# Empty

Empty catalog

<KCatalog title="Empty catalog" :fetcher="emptyFetcher" />

Set the following properties to handle empty state:

  • emptyStateTitle - Title text for empty state
  • emptyStateMessage - Message for empty state
  • emptyStateIcon - Icon for empty state
  • emptyStateIconColor - Color for empty state icon
  • emptyStateIconSize - Size for empty state icon
  • emptyStateActionRoute - Route for empty state action
  • emptyStateActionMessage - Button text for empty state action

If using a CTA button, a KCatalog-empty-state-cta-clicked event is fired when clicked.

Customized empty catalog

<!-- Using a route string -->
<KCatalog
  title="Customized empty catalog"
  :fetcher="emptyFetcher"
  emptyStateTitle="No Workspaces exist"
  emptyStateMessage="Adding a new Workspace will populate this catalog."
  emptyStateActionMessage="Create a Workspace"
  emptyStateActionRoute="#empty-state-full-example"
  emptyStateIcon="workspaces"
  emptyStateIconColor="#5996ff"
  emptyStateIconSize="35"
/>

<!-- Using a route object -->
<KCatalog
  title="Customized empty catalog"
  :fetcher="emptyFetcher"
  emptyStateTitle="No Workspaces exist"
  emptyStateMessage="Adding a new Workspace will populate this catalog."
  emptyStateActionMessage="Create a Workspace"
  emptyStateActionRoute="{
    name: 'create-workspace',
    params: {
      organizationId: 'd27e40e0-c9ac-43e2-8be8-54862fab45ea'
    }
  }"
  emptyStateIcon="workspaces"
  emptyStateIconColor="#5996ff"
  emptyStateIconSize="35"
/>

# Error

Set the hasError prop to true to enable the error state.

Catalog with error

Warning
An error occurred
Data cannot be displayed due to an error.
<KCatalog title="Empty catalog" :fetcher="fetcher" :hasError="true" />

Set the following properties to customize error state:

  • errorStateTitle - Title text for error state
  • errorStateMessage - Message for error state
  • errorStateIcon - Icon for error state
  • errorStateIconColor - Color for error state icon
  • errorStateIconSize - Size for error state icon
  • errorStateActionRoute - Route for error state action
  • errorStateActionMessage - Button text for error state action

If using a CTA button, a KCatalog-error-cta-clicked event is fired when clicked.

Catalog with error

Danger
Something went wrong
Error loading data.
Report an Issue 
<!-- Using a route string -->
<KCatalog
  title="Catalog with error"
  :fetcher="fetcher"
  :hasError="true"
  errorStateTitle="Something went wrong"
  errorStateMessage="Error loading data."
  errorStateActionMessage="Report an Issue"
  errorStateActionRoute="create-workspace"
  errorStateIcon="dangerCircle"
  errorStateIconColor="#e6173a"
  errorStateIconSize="35"
/>

<!-- Using a route object -->
<KCatalog
  title="Catalog with error"
  :fetcher="fetcher"
  :hasError="true"
  errorStateTitle="Something went wrong"
  errorStateMessage="Error loading data."
  errorStateActionMessage="Report an Issue"
  errorStateActionRoute="{
    name: 'report-issue',
    params: {
      organizationId: 'd27e40e0-c9ac-43e2-8be8-54862fab45ea'
    }
  }"
  errorStateIcon="dangerCircle"
  errorStateIconColor="#e6173a"
  errorStateIconSize="35"
/>

# Loading

Set the isLoading prop to true to enable the loading state.

Loading catalog

<KCatalog title="Loading catalog" :fetcher="fetcher" :isLoading="true" />

# Slots

Both the title & description of the card items as well as the entire catalog body are slottable.

  • body - The body of the card catalog, if you do not want to use KCatalogItem components for the children.
  • cardHeader - Will slot the card title for each entry
  • cardBody - Will slot the card body for each entry

I'm slotted baby!

<KCatalog title="I'm slotted baby!" >
  <template v-slot:body>
    <KCatalogItem
      v-for="item in getItems(4)"
      :key="item.title.replace(' ', '-')"
      :item="item"
      class="catalog-item"
    />
  </template>
</KCatalog>

If used in conjuction with a fetcher you have the option of using the returned data.

Customized body

<KCatalog :fetcher="fetcher" title="Customized body">
  <template v-slot:body="{ data }">
    <div v-for="item in data">
      <h4>{{ item.title }}</h4>
      <p>{{ item.description }}</p>
    </div>
  </template>
</KCatalog>

Use the cardTitle and cardBody slots to access item specific data.

Customized cards

<KCatalog :fetcher="fetcher" title="Customized cards">
  <template v-slot:cardTitle="{ item }">
    <div class="color-blue-500">
      {{ item.title }}
    </div>
  </template>
  <template v-slot:cardBody="{ item }">
    <span class="color-purple-400">
    {{ item.description }}
    </span>
  </template>
</KCatalog>

KCatalog has built-in state management for loading, empty, and error states. You can either use the props described in the section above or completely slot in your own content.

  • empty-state - Slot content to be displayed when empty
  • error-state - Slot content to be displayed when in an error state
<template>
  <KCatalog :fetcher="() => { return { data: [] } }">
    <template v-slot:empty-state>
      <KIcon icon="warning" />
      No Content!!!
    </template>
    <template v-slot:error-state>
      <KIcon icon="error" />
      Something went wrong
    </template>
  </KCatalog>
</template>

# Server-side functions

Pass a fetcher function to enable server-side pagination. The fetcher function should structure the ajax request URL in such a way that enables server side pagination per the requirements of the API being used.

Note

The loading state is handled automatically. When the fetcher is called the internal loading state is triggered and will be resolved when the fetcher returns. You can override this behavior using the isLoading prop.

Example URL

https://kongponents.dev/api/components?_page=1&_limit=10

<!-- Example Component Usage -->

<KCard>
  <template v-slot:body>
    <KInput placeholder="Search..." v-model="search" type="search" />
    <KCatalog
      :fetcher="fetcher"
      :initial-fetcher-params="{
        query: '',
        pageSize: 15,
        page: 1
      }"
      :search-input="search"
    />
  </template>
</KCard>

// Example Fetcher Function

fetcher(payload) {
  const params = {
    _limit: payload.pageSize,
    _page: payload.page
  }

  if (query) {
    params.q = payload.query
    params._page = 1
  }

  return axios.get('/user_list', {
    baseURL: 'https://kongponents.dev/api',
    params
  }).then(res => {
    return {
      total: res.total,
      data: res.data
    }
  })
}

# Theming

KCatalog is for the most part a collection of KCards. To theme the cards, use the existing KCard theming variables here.

← Checkbox →