Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nextcloud-libraries/nextcloud-dialogs
Nextcloud dialog helpers https://npmjs.org/@nextcloud/dialogs
https://github.com/nextcloud-libraries/nextcloud-dialogs
dialogs javascript-library nextcloud nextcloud-plugin
Last synced: about 1 month ago
JSON representation
Nextcloud dialog helpers https://npmjs.org/@nextcloud/dialogs
- Host: GitHub
- URL: https://github.com/nextcloud-libraries/nextcloud-dialogs
- Owner: nextcloud-libraries
- License: agpl-3.0
- Created: 2019-06-18T13:53:20.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-10-06T03:06:50.000Z (about 1 month ago)
- Last Synced: 2024-10-06T21:07:43.241Z (about 1 month ago)
- Topics: dialogs, javascript-library, nextcloud, nextcloud-plugin
- Language: TypeScript
- Homepage: https://nextcloud-libraries.github.io/nextcloud-dialogs/
- Size: 6.88 MB
- Stars: 19
- Watchers: 3
- Forks: 9
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @nextcloud/dialogs
[](https://api.reuse.software/info/github.com/nextcloud-libraries/nextcloud-dialogs) [](https://www.npmjs.com/package/@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` | `@nextcloud/vue` | 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.
```js
import '@nextcloud/dialogs/style.css'
```
### Toasts
```js
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](https://nextcloud-libraries.github.io/nextcloud-dialogs/).
### 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:
```js
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
We also provide the `@nextcloud/dialogs/filepicker.js` entry point to allow using the Vue component directly:
```vue
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,
}
]
```
## 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`;
- 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;
- Commit, push and create PR;
- Add the change log content from the 'Changelog' action on Github to `CHANGELOG.md`;
- Commit and push;
- Get your PR reviewed and merged;
- Create [a release on github](https://github.com/nextcloud-libraries/nextcloud-dialogs/releases) with the version as tag (e.g `v4.0.1`) and add the changelog content as description
