@nextcloud/dialogs

@nextcloud/dialogs

Nextcloud dialog helpers

Installation

npm i -S @nextcloud/dialogs

Version compatibility

Since version 4.2 this package provides a Vue.js based file picker, so this package depends on @nextcloud/vue. So to not introduce style collisions stick with the supported versions:

@nextcloud/dialogs	maintained	@nextcloud/vue dependency	Nextcloud server version
6.x	✅	8.x	Nextcloud 29 and newer
5.x	❌	8.x	Nextcloud 28, 29, 30
4.2+	❌	7.12	Nextcloud 25, 26, 27, 27.1
4.1	❌	any	any

Usage

General

The styles for the components (Toasts and FilePicker) are provided in the style.css file. So make sure that the @nextcloud/dialogs/style.css file is included in your app to make sure that the toasts or FilePicker have a proper styling applied.

import '@nextcloud/dialogs/style.css'

Toasts

import { showMessage, showInfo, showSuccess, showWarning, showError } from '@nextcloud/dialogs'
import '@nextcloud/dialogs/style.css'

If you using @nextcloud/dialogs >= 4.0 you don't need any svg or scss loader in you projects anymore.

There are different toast styles available, that are exposed in separate functions:

showMessage('Message without a specific styling')
showInfo('Information')
showSuccess('Success')
showWarning('Warning')
showError('Error')

There are several options that can be passed in as a second parameter, like the timeout of a toast:

showError('This is an error shown without a timeout', { timeout: -1 })

A full list of available options can be found in the documentation.

FilePicker

There are two ways to spawn a FilePicker provided by the library:

Use the FilePickerBuilder

This way you do not need to use Vue, but can programatically spawn a FilePicker. The FilePickerBuilder is included in the main entry point of this library, so you can use it like this:

import { getFilePickerBuilder } from '@nextcloud/dialogs'
const filepicker = getFilePickerBuilder('Pick plain text files')
    .addMimeTypeFilter('text/plain')
    .addButton({
        label: 'Pick',
        callback: (nodes) => console.log('Picked', nodes),
    })
    .build()

// You get the file nodes by the button callback, but also the pick yields the paths of the picked files
const paths = await filepicker.pick()

Use the Vue component directly

[!WARNING]
The Vue component is deprecated and will no longer be exported in a future version.

We also provide the @nextcloud/dialogs/filepicker.js entry point to allow using the Vue component directly:

<template>
  <FilePicker name="Pick some files" :buttons="buttons" />
</template>
<script setup lang="ts">
  import {
    FilePickerVue as FilePicker,
    type IFilePickerButton,
  } from '@nextcloud/dialogs/filepicker.js'
  import type { Node } from '@nextcloud/files'
  import IconShare from 'vue-material-design-icons/Share.vue'

  const buttons: IFilePickerButton[] = [
    {
      label: 'Pick',
      callback: (nodes: Node[]) => console.log('Picked', nodes),
      type: 'primary'
    },
    {
      label: 'Share',
      callback: (nodes: Node[]) => console.log('Share picked files', nodes),
      type: 'secondary',
      icon: IconShare,
    }
  ]
</script>

Development

Testing

For testing all components provide data-testid attributes as selectors, so the tests are independent from code or styling changes.

Test selectors

data-testid	Intended purpose
select-all-checkbox	The select all checkbox of the file list
file-list-row	A row in the file list (tr), can be identified by data-filename
row-checkbox	Checkbox for selecting a row
row-name	Name of the row / file

📤 Releasing a new version

• Pull the latest changes from main or stableX
• Checkout a new branch with the tag name (e.g v4.0.1): git checkout -b v<version>
• Run npm version patch --no-git-tag-version (npm version minor --no-git-tag-version if minor). This will return a new version name, make sure it matches what you expect
• Generate the changelog content from the release page. Create a draft release, select the previous tag, click generate then paste the content to the CHANGELOG.md file
  • adjust the links to the merged pull requests and authors so that the changelog also works outside of GitHub by running npm run prerelease:format-changelog. This will apply this regex: by @([^ ]+) in ((https://github.com/)nextcloud-libraries/nextcloud-dialogs/pull/(\d+)) Which this as the replacement: [\#$4]($2) \([$1]($3$1)\)
  • use the the version as tag AND title (e.g v4.0.1)
  • add the changelog content as description
• Commit, push and create PR
• Get your PR reviewed and merged
• Create a milestone with the follow-up version at https://github.com/nextcloud-libraries/nextcloud-dialogs/milestones
• Move all open tickets and PRs to the follow-up
• Close the milestone of the version you release
• Publish the previously drafted release on GitHub