README

AssetPicker 是一个免费的资产或文件选择器，旨在轻松集成到 Web 应用程序界面中。它具有文件抽象层，允许适配器连接到任何远程存储，无论是云存储如 Amazon S3、Google Drive 还是 Dropbox，还是来自自定义 Web 应用程序服务器的资产。与其他文件管理器或选择器不同，AssetPicker 适用于分层以及关联文件存储。

尝试演示

手册

工作原理
浏览器兼容性
安装
- CDN
- Docker
- Composer
- npm
配置
- config
- 选项
- 按钮
API
- 方法
- 事件
适配器
自定义应用程序
路线图

工作原理

AssetPicker 由两个包组成：选择器（在 picker.js 中的 AssetPicker）和应用程序（在 app.js 中的 AssetPickerApp）。选择器是一个没有依赖项的轻量级脚本，它将监听器添加到与配置的选择器匹配的元素。当点击其中一个时，它将从模板设置一个模态框，将其样式注入到标题中（模板和样式都是可自定义的），在模态框中加载应用程序，并通过配置将其传递给它。与 iframe 的通信是通过跨窗口消息完成的，因此它了解 CORS。

应用程序提供实际的用户界面和功能。它有一个默认配置，该配置将与传递给选择器的配置合并。配置的关键部分是存储，它将作为导航栏的顶级条目（以及当您使用多个存储时在启动屏幕上）挂载。每个存储都可以有单独的配置并使用其他适配器。它从配置中读取存储和适配器，并在使用时将适配器源脚本加载到 iframe 中，因此不需要的存储不会使应用程序的大小膨胀。

应用程序和适配器都是 Vue.js 组件，这使得应用程序结构现代化且易于维护。

除非您想自定义应用程序本身，否则选择器将是您必须使用的唯一 API。

浏览器兼容性

现代浏览器（IE >= 10）- 在 Chrome 53、Firefox 35-47、IE 10-11、Edge 上进行了测试

安装

CDN

将 AssetPicker 集成的最简单方法是使用 CDN 包含选择器脚本

<script src="https://cdn.rawgit.com/netresearch/assetpicker/1.3.4/dist/js/picker.js"></script>

<script>
    new AssetPicker(config, options);
</script>

<button rel="assetpicker">Select a file</button>

无论您是在 head 中还是在 footer 中包含脚本，它都会在 dom 准备就绪时注册。

如果您不想使用 CDN，您可以下载 dist 目录并将其上传到 Web 服务器，然后从那里包含 picker-min.js（dist 中的其他文件也必须可用）。

Docker

在您的服务器上托管 AssetPicker 的最佳方式是使用 Docker，甚至更简单的方式是使用 docker-compose。

git clone https://github.com/netresearch/assetpicker.git
cd assetpicker
docker-compose up -d

如果您想使用内置的代理，您需要运行以下命令一次：

docker exec -tiu www-data assetpicker_php '/bin/bash'
composer install

Composer

您可以使用 composer 轻松地将 AssetPicker 包含到您的 PHP 应用程序中（但您可能需要通过将其链接到适当的公共文件夹来使它位于 vendor 目录中的目录可用）。

composer require netresearch/assetpicker
ln -s vendor/netresearch/assetpicker web/assetpicker

Symphony 应用程序

请随意使用 AssetPicker Bundle。

npm

您可以使用 npm 高兴地安装 AssetPicker

npm install --save assetpicker

但您需要告诉它应用程序的源（如果您找到绕过这个问题的方法，请打开一个 issue 或 PR）

var AssetPicker = require('assetpicker');
new AssetPicker(
    config,
    {
        modal: {
            src: 'node_modules/assetpicker/dist'
        }
    }
);

有关使用 npm 设置 AssetPicker 的更多信息，请参阅以下内容。

配置

AssetPicker 构造函数接受两个参数：必需的 config（类型为 object）和可选的 options。config 是传递给 AssetPickerApp 的配置，而 options 可以包含拾取器和模态的选项。

new AssetPicker(config); /* or */ new AssetPicker(config, options);

请随意在演示页面上尝试一些选项。

config

选项

按钮

按钮上的数据属性可以控制可以拾取什么，以及拾取后应发生什么。

<button
    rel="assetpicker" 
    data-limit="0" 
    data-exts="jpeg,jpg,png">Select multiple images</button>

API

AssetPicker 提供了一个基本的 API，包括一些方法和一些事件。

方法

事件

拾取器提供了一个简单的事件 API，包括一些事件 - 监听器将始终绑定到拾取器实例，并接收根据事件传递的参数。按如下方式注册事件

var picker = new AssetPicker(config);
picker.on('pick', function(picked) {
  console.log(picked, this.element);
});

适配器

Google Drive

Google Drive 适配器利用 Google API 从用户的 Google Drive 账户检索资产，当用户拥有多个账户时，他将必须进行选择。为此，您需要在 Google API 控制台上注册您的项目并激活该项目的 Drive API。之后，您需要在项目的凭证区域创建一个 API 密钥和一个 OAuth 客户端 ID。

身份验证

Google Drive 适配器使用 Google Sign-In for Web - 这意味着您的用户将需要在弹出窗口中通过 Google 进行身份验证并授权 AssetPicker。然后 AssetPicker 将接收一个短期令牌以访问用户的 API - AssetPicker 不会存储任何其他信息。因此，当令牌过期时，AssetPicker 可能需要重新打开此窗口 - 由于弹出窗口拦截器可能会阻止自动弹出，因此您的用户将必须手动点击按钮来执行此操作，直到我们找到更好的解决方案。

配置

new AssetPicker({
    storages: {
        drive: {
            adapter: 'googledrive',
            // OAuth client id from API console, required
            client_id: 'xxx',
            // API key from API console, required
            api_key: 'xxx',
            // Google Apps Domain to which users must belong, optional
            hosted_domain: 'mycompany.com',
            // Requests to Google APIs are limited and AssetPicker requires some
            // of them to show the doc tree - use this to force start new requests
            // at least this amount of milliseconds after the last ones
            // (defaults for Google Drive adapter is 100), optional
            http: {
              throttle: 250
            }
        }
    }
});

GitHub

GitHub 适配器利用 GitHub API 向 AssetPicker 提供 GitHub 存储库中的文件和文件夹。为此，您需要一个 GitHub API 令牌或用户需要一个 GitHub 账户。

身份验证

如果您不提供 API 令牌，将提示用户输入他的 GitHub 凭证。这些凭据将仅用于创建个人访问令牌，该令牌将存储在用户的浏览器本地存储中。从那时起，此个人令牌将用于与 GitHub 的身份验证。**用户的登录名和密码不会以任何方式存储**。

配置

new AssetPicker({
    storages: {
        somegithubrepo: {
            adapter: 'github',
            // Owner of the repository, required:
            username: 'netresearch',
            // The repository name, required:
            repository: 'assetpicker'
        }
    },
    github: {
        // Token for authentication with GitHub API, optional (see above):
        token: '29782sdwhd2eu2e823jdjhw9832ijs92'
    }
});

EnterMediaDB

EnterMediaDB 适配器利用 EnterMediaDB API 向 AssetPicker 提供类别和资产。

身份验证

EnterMediaDB API 的身份验证基于会话，需要用户向 API 提供其凭据以进行身份验证。因此，您必须确保 AssetPicker 有权在 EnterMediaDB 中使用 API。请参阅 EnterMediaDB 的角色和权限。

配置

EnterMediaDB 目前不支持 CORS，因此，如果 AssetPicker 由与 EnterMediaDB 不同主机、协议或端口的源提供服务，您可能需要一个代理。

new AssetPicker({
    storages: {
        somegithubrepo: {
            adapter: 'entermediadb',
            // URL to the catalogue, required:
            url: 'http://em9.entermediadb.org/openinstitute',
            // Proxy is likely required 
            proxy: true
        }
    }
});

注册自己的适配器

适配器实际上是 vue 组件，其模板将在导航栏中渲染。项目的加载完全由事件控制。查看现有适配器以了解详细信息。

执行此操作的标准方法是为适配器创建一个独立的脚本，并在配置中引用它。该脚本需要独立运行，因为它不会在包含选择器的同一个窗口中加载，而是从 iframe 中加载。

以下示例展示了从端点加载层次结构的简单适配器

https://myapp.example.com/myadapter.js

AssetPickerAdapterMine = {
    events: {
        'load-items': function(tree) {
            this.http.get(this.config.url + '/files/' + (tree.item ? tree.item.id : '')).then(
                function(response) {
                    tree.items = response.data.map(this.createItem);
                }
            );
        }
    }
}

https://myapp.example.com/index.html（包含选择器的地方）

new AssetPicker({
    storages: {
        mystorage: {
            adapter: 'mine',
            url: 'https://example.com'
        }
    },
    adapters: {
        mine: 'https://myapp.example.com/myadapter.js'
    }
});

此外，您可以在使用 npm 安装应用程序时添加自定义适配器。以下是一个示例。

自定义应用程序

除了简单地分支此存储库之外，您还可以将应用程序包含到您的项目中。为此，您需要一个使用 browserify 构建的 npm 应用程序来自定义应用程序。AssetPickerApp 使用 [Vue.js]，因此您可能需要阅读它的文档。

初始化应用程序
```
npm init
npm install --save assetpicker
```

自定义 AssertPickerApp 或其组件

src/app.js

var Storage = require('assetpicker/src/js/app/components/storage');
Storage.components.myadapter = require('./myadapter');

var config  = require('assetpicker/src/js/app/config');
config.storages = {
    myadapterstorage: {
        adapter: 'myadapter',
        label: 'My Adapter'
        // ... options for myadapter
    }
}

module.exports = require('assetpicker/src/js/app');

为应用程序构建一个 HTML 页面

app.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>AssetPicker</title>
    <link rel="stylesheet" href="node_modules/assetpicker/dist/css/main.css"
</head>
<body>
<div id="app"></div>
<script src="dist/js/app.js"></script>
<script>
   new AssetPickerApp({el: '#app'});
</script>
</body>
</html>

构建一个包含选择器的 HTML 页面

index.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>AssetPicker</title>
</head>
<body>
<script src="node_modules/assetpicker/dist/js/picker.js"></script>
<script>
   new AssetPicker(null, {
        modal: {
             src: 'app.html'
        }
   });
</script>
<button rel="assetpicker">Pick an asset</button>
</body>
</html>

设置 gulp 或其他构建工具

npm install -g gulp
npm install -S browserify vinyl-source-stream

gulp.js

var gulp = require('gulp');
var browserify = require('browserify');
var source = require('vinyl-source-stream');

gulp.task('js', function () {
    var b = browserify({
        entries: './src/app.js',
        standalone: 'AssetPickerApp',
        debug: true
    });

    return b.bundle()
        .pipe(source('app.js'))
        .pipe(gulp.dest('./dist/js/'));
});

gulp js

路线图

适配器
- Amazon S3
- Dropbox
Google Drive
- IE 兼容性
- 无需用户交互即可重新认证
github
- 双因素认证
- 分支选择器
- 处理子模块和符号链接
如上传、重命名、移动等管理功能

netresearch / assetpicker

维护者

详细信息

README

尝试演示

工作原理

浏览器兼容性

安装

CDN

Docker

Composer

Symphony 应用程序

npm

配置

config

选项

按钮

API

方法

事件

适配器

Google Drive

身份验证

配置

GitHub

身份验证

配置

EnterMediaDB

身份验证

配置

注册自己的适配器

自定义应用程序

路线图