Cloud File Manager

The Cloud File Manager is a Javascript library that enables applications to save and load files from various file systems using a simple consistent API. Currently the following file system providers are supported:

Concord Document Store [DEPRECATED]
Google Drive (both normal files and realtime models backed by empty normal files)
Local and remote read-only files
Browser LocalStorage (used mostly for development/testing)

Development Setup

yarn install    # [or npm install]
gulp default
live-server

and navigate to http://localhost:8080/dist/examples/

Deployment

gulp deploy

This will clean and re-build the dist/ folder, and push the result to http://concord-consortium.github.io/cloud-file-manager/. The examples directory highlighting the different ways Cloud File Manager can be configurated will then be available at http://concord-consortium.github.io/cloud-file-manager/examples/.

Integrating Cloud File Manager

There are two ways to integrate Cloud File Manager into an application

Have Cloud File Manager create an iframe that wraps an application on the same domain - cross-domain frames are not supported by design.
Embed Cloud File Manager into the application and use as a library

Iframe Integration

On the same domain as your main application create an html file with the following structure:

<html>
  <head>
    <script type="text/javascript" src="/path/to/cloud-file-manager/js/globals.js"></script>
    <script type="text/javascript" src="/path/to/cloud-file-manager/js/app.js"></script>
    <link rel="stylesheet" href="/path/to/cloud-file-manager/css/app.css">
  </head>
  <body>
    <div id="wrapper">
    </div>
    <script>
      var options = {...};  // see below
      CloudFileManager.createFrame(options, "wrapper", function (event) {
        ... // optional event listener, see below
      });
    </script>
  </body>
</html>

where the options variable has the following optional or required settings:

var options = {
  app: "example-app", // required when iframing - relative path to the app to wrap
  mimeType: "application/json", // optional - defaults to text/plain
  appName: "CFM_Demo", // document store app name - required for sharing
  appVersion: "0.1", // document store app version - required for sharing
  appBuildNum: "1", // document store app build number - required for sharing
  providers: [...] // see below
  ui: {
    menu: CloudFileManager.DefaultMenu, // required - an array of string menu item names
    menuBar: {
      info: "Version 1.0.0", // optional - displayed on the right side of menubar when iframing
      help: "http://lmgtfy.com/" // optional - displayed on the right side of menubar with a ? icon when iframing
    }
  }
}

Translation/Localization

The master English strings file is src/code/utils/lang/en-US-master.json, which is a standard JSON file except that JavaScript-style comments are allowed. (Comments are stripped before use.) Changes to English strings should be made in the master English strings file. All other language files in src/code/utils/lang/*.json are output files generated by script. Translations for other languages are managed via the Cloud File Manager project (authentication required) on POEditor, which provides free hosting services for open source projects.

Development

After making changes to the master English strings file (src/code/utils/lang/en-US-master.json), run the strings:build script to strip comments and deploy the src/code/utils/lang/en-US.json file for building:

npm run strings:build

To push changes to the master English strings file to POEditor, run the strings:push script:

npm run strings:push -- -a <poeditor-api-token>

The API token must be provided as an argument to the strings:push script or it can be set as an environment variable:

export POEDITOR_API_TOKEN=<poeditor-api-token>

To update the strings files within the project, run the strings:pull script:

npm run strings:pull -- -a <poeditor-api-token>

As with the strings:push script, the API token must be provided or be set as an environment variable. The strings:pull script builds the English strings as well so all strings files will be up to date.

After pulling updated strings, the modified files can be committed to git, turned into a Github Pull Request, etc. Note that POEditor supports Github integration which could potentially automate part of this, but that requires further investigation.

Unicode escapes are converted to their UTF-8 equivalents when pushed, i.e. strings are viewed/edited in their "user" form in POEditor, and they remain in their UTF-8 form when pulled. For characters that are better left in their Unicode escape form, such as non-printable characters like ZERO-WIDTH-SPACE ("\u200b") and the RIGHT-TO-LEFT-MARK ("\u200f"), the scripts support a custom Unicode escape sequence such that "[u200b]" and "[u200f]" are converted to "\u200b" and "\u200f" respectively when pulled.

The ZERO-WIDTH-SPACE character can be used to indicate that the empty string is the correct translation for a string in a particular language. If the string were simply left untranslated, then POEditor would 1) show it as untranslated in the POEditor UI and 2) replace it with the English string when pulled. The ZERO-WIDTH-SPACE prevents POEditor from treating the string as untranslated, but it is rendered like an empty string.

Adding a language

To add a new language:

Add the language to the POEditor project
Add the language code to the list of languages in bin/strings-pull-project.sh
Load the new language file in src/code/utils/translate.coffee

Note that there is probably a way to eliminate the need for step 3 above by requiring all JSON files in the src/code/utils/lang directory (except for en-US-master.json), but that has not been implemented yet.

TBD:

Document provider options (see examples or look at code to see how they are configured for now)
Document using as a library
Draw a simple architecture diagram of how the client connects to the React UI using http://asciiflow.com/
Document how to add another provider
Document the event listener functions in both createFrame and clientConnect and how each can talk to each other

timothyshaw / cloud-file-manager Goto Github PK