README.md
Files viewer for nextcloud
Show your latest holiday photos and videos like in the movies. Show a glimpse of your latest novel directly from your nextcloud. Choose the best GIF of your collection thanks to the direct view of your favorites files!
📋 Current support
- Images
- Videos
🏗 Development setup
- ☁ Clone this app into the
apps
folder of your Nextcloud:git clone https://github.com/nextcloud/viewer.git
- 👩💻 In the folder of the app, install dependencies with
npm ci
and build the Javascript withnpm run build
. - 🎉 Partytime!
🧙 Advanced development stuff
To build the Javascript whenever you make changes, you can also run npm run dev
for development builds.
📷 Running cypress tests
To run e2e cypress tests, execute npm run cypress
.
The visual-regression
tests require additional care as they depend on installation of fonts in the application. To achieve repeatable results run the tests using npm run cypress:visual-regression
. This will build the app with the required fonts and run the tests.
If changes are required to the reference (base) screenshots used by the visual-regression
tests, run cypress:update-snapshots
and commit the updated screenshots.
API
Add the viewer to your app
In php, on your page, emit the LoadViewer event. Check the documentation/tutorial for more info on this type of page controller sample.
use OCA\Viewer\Event\LoadViewer;
use OCP\AppFramework\Controller;
use OCP\AppFramework\Http\TemplateResponse;
use OCP\EventDispatcher\IEventDispatcher;
use OCP\IRequest;
class PageController extends Controller {
protected $appName;
/** @var IEventDispatcher */
private $eventDispatcher;
public function __construct($appName,
IRequest $request,
IEventDispatcher $eventDispatcher) {
parent::__construct($appName, $request);
$this->appName = $appName;
$this->eventDispatcher = $eventDispatcher;
}
/**
* @NoAdminRequired
* @NoCSRFRequired
* Render default index template
*
* @return TemplateResponse
*/
public function index(): TemplateResponse {
$this->eventDispatcher->dispatch(LoadViewer::class, new LoadViewer());
$response = new TemplateResponse($this->appName, 'main');
return $response;
}
}
This will load all the necessary scripts and make the Viewer accessible trough javascript at OCA.Viewer
Open a file
- Open a file on WebDAV and let the viewer fetch the folder data
OCA.Viewer.open({path: '/path/to/file.jpg'})
- Open a file on WebDAV and provide a list of files
OCA.Viewer.open({
path: '/path/to/file.jpg',
list: [
{
basename: 'file.jpg',
filename: '/path/to/file.jpg',
...
},
...
],
})
// Alternative: pass known file info so it doesn't need to be fetched
const fileInfo = {
filename: '/path/to/file.jpg',
basename: 'file.jpg',
mime: 'image/jpeg',
etag: 'xyz987',
hasPreview: true,
fileid: 13579,
}
OCA.Viewer.open({
fileinfo: fileInfo,
list: [fileInfo],
})
The list parameter requires an array of fileinfo. You can check how we generate a fileinfo object here from a dav PROPFIND request data. There is currently no dedicated package for it, but this is coming. You can check the photos repository where we also use it.
- Open a file from an app's route
const fileInfo1 = {
filename: 'https://next.cloud/apps/pizza/topping/pineapple.jpg',
basename: 'pineapple.jpg',
source: 'https://next.cloud/apps/pizza/topping/pineapple.jpg',
mime: 'image/jpeg',
etag: 'abc123',
hasPreview: false,
fileid: 12345,
}
const fileInfo2 = {
filename: 'https://next.cloud/apps/pizza/topping/garlic.jpg',
basename: 'garlic.jpg',
source: 'https://next.cloud/apps/pizza/topping/garlic.jpg',
mime: 'image/jpeg',
etag: 'def456',
hasPreview: false,
fileid: 67890,
}
OCA.Viewer.open({
fileInfo: fileInfo1,
list: [fileInfo1, fileInfo2],
})
In order to open a shared file you will need to provide the share token
so the Viewer can use it to authenticate the requests to the server.
See the files_sharing
app
controller
and
template
for an example.
Close the viewer
OCA.Viewer.close()
🔍 Add you own file view
If you want to make your app compatible with this app, you can use the OCA.Viewer
methods
- Create a vue component which use the
path
andmime
props (they will be automatically passed by the viewer) - Register your mime viewer with the following:
import VideoView from 'VideoView.vue' OCA.Viewer.registerHandler({ // unique id id: 'video', // optional, it will group every view of this group and // use the proper view when building the file list // of the slideshow. // e.g. you open an image/jpeg that have the `media` group // you will be able to see the video/mpeg from the `video` handler // files that also have the `media` group set. group: 'media', // the list of mimes your component is able to display mimes: [ 'video/mpeg', 'video/ogg', 'video/webm', 'video/mp4' ], // your vue component view component: VideoView })
- if you feel like your mime should be integrated on this repo, you can also create a pull request with your object on the
models
directory and the view on thecomponents
directory. Please have a look at what's already here and take example of it. 🙇♀️