Components for the nextcloud dashboard

Warning

This library is deprecated as the components are now part of @nextcloud/vue starting with version 6.0.0.

Installation

npm install --save @nextcloud/vue-dashboard

Building locally

npm link
npm ci
npm run build

# in your apps repo
npm link @nextcloud/vue-dashboard

Usage

Documentation

DashboardWidget component

This component displays a dashboard widget with an item list as its content.

You can define an optional header, footer and empty-content.

You can set this component in loading mode.

The default item rendering can be overridden with the default slot.

Items can have a context menu.

Item list

This component takes a list of items in the "items" prop.

If the default slot is not overridden, then do whatever you want with the item objects structure. You will access them in your custom default item slot.

If the default slot is not overridden, DashboardWidgetItem component is used so an items must look like:

const itemList = [
	{
		id: '1', // string or integer
		targetUrl: 'https://target.org', // the item element is a link to this URL
		avatarUrl: 'https://avatar.url/img.png', // used if avatarUsername is not defined
		avatarUsername: 'Robert', // used if avatarUrl is not defined
		avatarIsNoUser: true, // passed to the Avatar component in WidgetItem component
		overlayIconUrl: generateUrl('/svg/core/actions/sound?color=' + this.themingColor), // optional, small icon to display on the bottom-right corner of the avatar
		mainText: 'First item text',
		subText: 'First item subtext',
	},
	{
		id: '2',
		targetUrl: 'https://other-target.org',
		avatarUrl: 'https://other-avatar.url/img.png',
		overlayIconUrl: generateUrl('/svg/core/actions/add?color=' + this.themingColor),
		mainText: 'Second item text',
		subText: 'Second item subtext',
	},
]

Item menu

You can optionally pass an object in the "itemMenu" prop to define a context menu for each items. Each entry of this object must define "text" and "icon" properties.

When clicking the menu item, an event (named like the itemMenu key) will be emitted to the widget's parent.

const itemMenu = {
	// triggers an event named "markDone" when clicked
	'markDone': {
		text: t('app', 'Mark as done'),
		icon: 'icon-checkmark',
	},
	// triggers an event named "hide" when clicked
	'hide': {
		text: t('app', 'Hide'),
		icon: 'icon-toggle',
	}
}

All props

• showMoreUrl: If this is set, a "show more" text is displayed on the widget's bottom. It's a link pointing to this URL.
• loading: A boolean to put the widget in a loading state
• itemMenu: An object containing context menu entries that will be displayed for each items
• items: An object containing the items themselves (specific structure must be respected except if you override item rendering with the default slot)

Events

• for each menu item, an event named like its key is emitted with the item as a parameter

Slots

• default (optional, default=DashboardWidgetItem): The default slot can be optionnally overridden. It contains the template of one item.
• header (optional): Something to display on top of the widget
• empty-content (optional): What to display when the item list is empty
• footer (optional): Something to display

Simplest example with custom item

<template>
	<DashboardWidget :items="items">
		<template v-slot:default="{ item }">
			{{ item.title }}
		</template>
	</DashboardWidget>
</template>

<script>
import { DashboardWidget } from '@nextcloud/vue-dashboard'
const myItems = [
	{
		title: 'first',
		content: 'blabla',
	},
	{
		title: 'second',
		content: 'fuzzfuzz',
	},
]
export default {
	name: 'MyDashboardWidget',
	props: [],
	components: {
		DashboardWidget,
	},
	data() {
		return {
			items: myItems
		}
	},
}
</script>

Complete example using DashboardWidgetItem

<template>
	<DashboardWidget :items="items"
		:show-more-url="'https://nextcloud.com'"
		:item-menu="itemMenu"
		@hide="onHide"
		@markDone="onMarkDone"
		:loading="state === 'loading'">

		<template v-slot:empty-content>
			Nothing to display
		</template>
	</DashboardWidget>
</template>

<script>
import { DashboardWidget } from '@nextcloud/vue-dashboard'
const myItems = [
	{
		id: '1',
		targetUrl: 'https://target.org',
		avatarUrl: 'https://avatar.url/img.png',
		avatarUsername: 'Robert',
		avatarIsNoUser: true,
		overlayIconUrl: generateUrl('/svg/core/actions/sound?color=' + this.themingColor),
		mainText: 'First item text',
		subText: 'First item subtext',
	},
	{
		id: '2',
		targetUrl: 'https://other-target.org',
		avatarUrl: 'https://other-avatar.url/img.png',
		overlayIconUrl: generateUrl('/svg/core/actions/add?color=' + this.themingColor),
		mainText: 'Second item text',
		subText: 'Second item subtext',
	},
]
const myItemMenu = {
	// triggers an event named "markDone" when clicked
	'markDone': {
		text: t('app', 'Mark as done'),
		icon: 'icon-checkmark',
	},
	// triggers an event named "hide" when clicked
	'hide': {
		text: t('app', 'Hide'),
		icon: 'icon-toggle',
	}
}
export default {
	name: 'MyDashboardWidget',
	props: [],
	components: {
		DashboardWidget,
	},
	data() {
		return {
			items: myItems,
			itemMenu: myItemMenu,
			loading: true,
		}
	},
	methods: {
		onMoreClick() {
			console.log('more clicked')
			const win = window.open('https://wherever.you.want', '_blank')
			win.focus()
		},
		onHide(item) {
			console.log('user wants to hide item ' + item.id)
			// do what you want
		},
		onMarkDone(item) {
			console.log('user wants to mark item ' + item.id + ' as done')
			// do what you want
		},
	},
}
</script>

DashboardWidgetItem component

This component displays a dashboard widget item. It is used by default by the DashboardWidget component. You can also use it wherever you want.

It has an optional context menu.

Usage

All props

• id: A unique string/integer identifying the item (optional).
• itemMenu: An object containing context menu entries that will be displayed for each items
• targetUrl: The item element is a link to this URL.
• avatarUrl: Where to get the avatar image. Used if avatarUsername is not defined.
• avatarUsername: Name to provide to the Avatar. Used if avatarUrl is not defined.
• avatarIsNoUser: Is the named a Nextcloud user name? If yes, the user's avatar image will be displayed. This value is passed to the Avatar component in WidgetItem component.
• overlayIconUrl: Small icon to display on the bottom-right corner of the avatar. Optional.
• mainText
• subText

Context menu

You can optionally pass an object in the "itemMenu" prop to define a context menu for each items. Each entry of this object must define "text" and "icon" properties.

When clicking the menu item, an event (named like the itemMenu key) will be emitted to the widget's parent.

const itemMenu = {
	// triggers an event named "markDone" when clicked
	'markDone': {
		text: t('app', 'Mark as done'),
		icon: 'icon-checkmark',
	},
	// triggers an event named "hide" when clicked
	'hide': {
		text: t('app', 'Hide'),
		icon: 'icon-toggle',
	}
}

Events

• for each menu item, an event named like its key is emitted with the item as a parameter

Simplest example

<template>
	<DashboardWidgetItem
		:target-url="targetUrl"
		:avatar-url="avatarUrl"
		:overlay-icon-url="overlayIconUrl"
		:main-text="mainText"
		:sub-text="subText" />
</template>

<script>
import { DashboardWidgetItem } from '@nextcloud/vue-dashboard'
const targetUrl = 'https://target.org'
const avatarUrl = 'https://avatar.url/img.png'
const overlayIconUrl = generateUrl('/svg/core/actions/sound?color=' + this.themingColor)
const mainText = 'I am an item'
const subText = 'and i can talk'
export default {
	name: 'MyRootComponentOrWhatever',
	props: [],
	components: {
		DashboardWidgetItem,
	},
	data() {
		return {
			targetUrl,
			avatarUrl,
			overlayIconUrl,
			mainText,
			subText,
		}
	},
}
</script>

Complete example

<template>
	<DashboardWidgetItem
		:id="myItemId"
		:target-url="targetUrl"
		:avatar-url="avatarUrl"
		:avatar-username="avatarUsername"
		:avatar-is-no-user="avatarIsNoUser"
		:overlay-icon-url="overlayIconUrl"
		:main-text="mainText"
		:sub-text="subText"
		:item-menu="itemMenu"
		@hide="onHide"
		@markDone="onMarkDone" />
</template>

<script>
import { DashboardWidgetItem } from '@nextcloud/vue-dashboard'

const myItemId = '123abc'
const targetUrl = 'https://target.org'
const avatarUrl = 'https://avatar.url/img.png'
const avatarUsername = 'Johnny'
const avatarIsNoUser = true
const overlayIconUrl = generateUrl('/svg/core/actions/sound?color=' + this.themingColor)
const mainText = 'I am an item'
const subText = 'and i can talk'
const myItemMenu = {
	// triggers an event named "markDone" when clicked
	'markDone': {
		text: t('app', 'Mark as done'),
		icon: 'icon-checkmark',
	},
	// triggers an event named "hide" when clicked
	'hide': {
		text: t('app', 'Hide'),
		icon: 'icon-toggle',
	}
}
export default {
	name: 'MyRootComponentOrWhatever',
	props: [],
	components: {
		DashboardWidgetItem,
	},
	data() {
		return {
			myItemId,
			targetUrl,
			avatarUrl,
			overlayIconUrl,
			mainText,
			subText,
			itemMenu: myItemMenu,
		}
	},
}
</script>