Skip to content

Latest commit

 

History

History
179 lines (154 loc) · 6.07 KB

README.md

File metadata and controls

179 lines (154 loc) · 6.07 KB
Raw

Files viewer for nextcloud

REUSE status

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!

viewer

📋 Current support

  • Images
  • Videos

🏗 Development setup

  1. ☁ Clone this app into the apps folder of your Nextcloud: git clone https://github.com/nextcloud/viewer.git
  2. 👩‍💻 In the folder of the app, install dependencies with npm ci and build the Javascript with npm run build.
  3. 🎉 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

  1. Open a file on WebDAV and let the viewer fetch the folder data
OCA.Viewer.open({path: '/path/to/file.jpg'})
  1. 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.

  1. 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

  1. Create a vue component which use the path and mime props (they will be automatically passed by the viewer)
  2. 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
 })
  3. 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 the components directory. Please have a look at what's already here and take example of it. 🙇‍♀️