Skip to content
This repository has been archived by the owner on Aug 31, 2021. It is now read-only.

Creating a new provider

Jump to bottom
Giles Lavelle edited this page Sep 2, 2014 · 12 revisions

Getting started

To scaffold the basic structure for a new provider, run node tools/scaffold.js from the root directory and follow the instructions. A new folder will be created for your provider in a new directory the top level of the repository, and you can use this as the starting point to build out your own code.

Your provider will communicate with the Chrome OS Files app via the [fileSystemProvider][fsp] API.

Structure

Required

Each provider directory has common elements:

  • An extension directory containing assets that should be included for distribution, including
    • The [manifest][] (manifest.json)
    • The [icons][] in the icon directory
    • Any [localisation strings][i18n] in the _locales directory
    • Any scripts, stylesheets and HTML pages your provider needs. These can either be included directory or generated from other source files by your build process
  • A test directory containing Mocha unit tests
  • A readme.md file describing any instructions specific to your provider

Optional

Scripts

For simple providers you can keep all your scripts in the extension directory, but for more complex ones with multiple modules or dependencies on third party libraries, we encourage you to keep your scripts in a separate JS directory and use [Browserify][] to bundle them into a single file in extension. You can use the [Grunt plugin][grunt-browserify] to automate this.

UI

Most providers will also need a UI. You can include the necessary HTML, CSS and JS for this in the extension directory directly if you want, but we encourage you to use [Polymer][] UI components for better user experience. If so, you will need to store your UI files in a separate ui directory, and build them using [Vulcanize][] to the extension directory, to avoid [CSP issues][csp]. We recommend the [Grunt plugin][grunt-vulcanize] to automate this.

Tools

If you use any of these build tools you will probably want a Gruntfile.js and a package.json in your project too to manage dependencies and build configurations.

Testing

Shared suite

This repository already contains a full set of unit tests for the behaviour of the main FSP event handlers, such as onOpenFileRequested and onReadDirectoryRequested. You should use these in your test suite to ensure the external behaviour of your provider is the same as the others. These files are stored in the shared_tests directory in the top level of this repository. They are CommonJS modules and as such can be imported into your provider's test suite using Browserify. Any other tests specific to the internal behaviour of your provider should be kept within its own test directory.

If you find any tests that rely on any specific implementation details of WebDAV (such as ordering in directory listings, for example) that need to be made more generic to be shared with your provider, please file an issue.

Shared filesystem

The shared test suite assumes that the contents of the filesystem being tested are the same as those served by the sample WebDAV server in testserver/assets. To use the shared suite, your filesystem needs to match this. The recommended approach for this is to create a mock version of whatever API you use, that fetches data from the canonical WebDAV server and converts it into the correct format. This is the approach taken by the S3 provider in s3fs/test/spec/s3mock.js.

We recommend that you use this approach for testing rather than loading data from your own remote server because it is both faster (no external network requests) and more open-source friendly (other people can edit the test cases).

If this is not possible, or you just want to get started with testing your system quickly, we still recommend that we upload the contents of testserver/assets to your server for testing for consistency with other providers. [manifest]: https://developer.chrome.com/extensions/manifest [icons]: https://developer.chrome.com/extensions/manifest/icons [i18n]: https://developer.chrome.com/extensions/i18n [polymer]: http://www.polymer-project.org/ [vulcanize]: https://github.com/Polymer/vulcanize [csp]: https://developer.chrome.com/extensions/contentSecurityPolicy [grunt-vulcanize]: https://www.npmjs.org/package/grunt-vulcanize [browserify]: http://browserify.org/ [grunt-browserify]: https://github.com/jmreidy/grunt-browserify [fsp]: https://developer.chrome.com/apps/fileSystemProvider

Clone this wiki locally