## 1. Project Overview & Quickstart (killme2008/README-EN) # README-EN Open-source repository killme2008/README-EN ### Repository Details - **Repository:** [killme2008/README-EN](https://github.com/killme2008/README-EN) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (killme2008/docs) ## File: README.md # LeanCloud Documentation [](https://travis-ci.org/leancloud/docs) [](https://david-dm.org/leancloud/docs#info=devDependencies) LeanCloud 开发者文档 ## 说明 这个项目是 LeanCloud [文档](http://leancloud.cn/docs/)上的所有文档的 Markdown 格式的源码，最终将渲染成你在网站上看到的 [HTML 文档](http://leancloud.cn/docs/)。 因此 Markdown 文件里部分链接写的是最终渲染后的链接，如果直接点击会发现 404 错误。 ## 贡献 我们欢迎所有用户提交 PR 或 issue 为我们贡献或者修正错误，LeanCloud 衷心感谢您的贡献。 **贡献方法及注意事项**： - `fork` 这个项目 - `npm install` 安装相关依赖 - 执行 `grunt server` 可以本地预览 - 修改 `/views` 目录中的文档 - `/views` 中是模板文件，会被编译为 `/md` 目录中对应的文档文件。 - 模板支持嵌套，如 `/views` 中 `a.md` 是可以被嵌套在 `a.tmpl` 中，方法参见下文 [一套模板多份渲染]（#一套模板多份渲染）。 - 相关图片放在 `/images` 目录中，引用格式为 ``。 - 由于文档会经过 Nunjucks 和 AngularJS 渲染，当文档中需要显示 `{{content}}` 这种格式时，需要： - 在文档开头增加 `{% set content = '{{content}}' %}`，如果没有声明 Nunjucks 会将其渲染为空白。 - 在正文中加上 `{{content}}`，避免被 AngularJS 渲染。 - 新增一个文档 - 命名使用中划线和小写字母，如 `livekit-android.md`、`quick-start-ios.md`。 - 如需要，更新文档首页 `templates/pages/index.html` 和顶部导航菜单 `templates/include/header.html`。 - 修改文中标题或文件名称 - 确认要修改的标题 h1-h6 或文件名称有没有被 `/views` 和 `/templates` 目录下任何文件所引用，以免产生断链。 - 系统自动生成的 h1-h6 标题的 id，会将所有空格、中西文标点替换为下划线，如 `## 调用 Console.log()` 会生成 `

`，在引用时需要留意，包括大小写。 - 提交修改并发起 `Pull Request` ## 内部贡献 为避免在所提交 PR 中出现与修改内容无关的 Merge pull request 的 commits，推荐使用以下流程提交 PR： 1. 本地切换到 master 分支 1. rebase 1. 新建分支 new branch 进行修改 1. 提交 PR，如有相关的 issue 在注释中增加 `Fixes #???`。问号为 issue 的编号。 合并 PR 时，如果 commits 历史不重要，可以选择 Squash and Merge 来合并，合并后删除相关的分支。 PR 合并后，要让改动最终生效还需要通过 Jenkins 执行 `cn-avoscloud-docs-prod-ucloud` 任务进行发布。 ## 目录结构 ``` ├── README.md // 说明文档 ├── archive // 已下线存档的文档，请勿更新 ├── custom // 文档页面样式及 JavaScript 代码 ├── images // 文档中引用的所有图片 ├── md // 临时目录（文档均为自动生成，因为不要修改） ├── dist // 编译之后生成的文件将会在此目录下 ├── private // 未完成、未发布的文档临时保存在这里，以便让重建全站文档索引的系统任务忽略这些文件 ├── react // 文档评论功能所需要用的 React 组件 ├── server_public // 文档评论功能所需要用的 React 组件 ├── templates // 文档网站的 HTML 页面模板 ├── views // Markdown 格式文档的模板文件和源文件，使用时会被编译到 md 目录中 ├── app.coffee ├── app.json ├── CHANGELOG.md // changelog 记录 ├── circle.yml ├── CONTRIBUTING.md // 贡献指南 ├── package.json └── ... ``` ## 预览 开发服务基于 Grunt，所以需要有 Nodejs 环境，通过 NPM 安装测试需要的依赖 安装 Grunt ```bash $ sudo npm install grunt-cli ``` 安装需要的依赖 ```bash $ npm install ``` 本地启动一个 HTTP Server，然后打开浏览器访问 即可 ```bash $ grunt server ``` ## 版本更新 - 请通过 `grunt release` 命令自动 bump `package.json`、自动打标签，请不要手动更新 - 请按照 `CONVENTIONS.md` 的格式书写有意义的 commits，`CHANGELOG.md` 会被自动生成，请不要手动修改 ## 一套模板多份渲染 有些文档的相似度非常高，所以可以使用一份模板，多分变量渲染的方式一次性生成多份文档，比如 「LeanEngine 指南」的文档就是这样生成的。这份文档分为三个运行时：Node.js、Python、云引擎 2.0。最终效果可见 [LeanEngine (Node.js 环境)](https://leancloud.cn/docs/leanengine_guide-node.html) 和 [LeanEngine（Python 环境）](https://leancloud.cn/docs/leanengine_guide-python.html)。这类文档编写方式如下： * 在 `views` 目录先编写一份「模板」（以 `tmpl` 作为扩展名），将文档的主体部分完成，将文档之间不一样的部分（比如不同语言的代码片段）使用： ``` {% block %}{% endblock %} ``` 括起来。可以参考 [leanengine_guide.tmpl](https://github.com/leancloud/docs/blob/master/views/leanengine_guide.tmpl)。 * 在 `views` 目录里编写多份渲染变量（以 `md` 作为文件扩展名）。第一行表明自己继承哪个模板： ``` {% extends "./" %} ``` 后续的内容就是用： ``` {% block %}<不同文档之间的差异>{% endblock%} ``` 来替换模板中存在的 block。可以参考 [leanengine_guide-node.tmpl](https://github.com/leancloud/docs/blob/master/views/leanengine_guide-node.md) * 生成文档：使用下列命令会在 md 文件夹中生成最终的 md 文件： ``` grunt nunjucks ``` 同样支持 `grunt server` 命令，该命令最终会执行 `watch` 插件，此时修改模板文件，或者变量文件都会自动重新生成最终的 md 文件（可能需要等待 2~4 秒）。 * 记得将这种方式生成的 md 文件添加到 [.gitignore](https://github.com/leancloud/docs/blob/master/.gitignore) 文件中，确保这类文件不会被提交。 **注意：如果在模板中需要渲染 `{{appid}}` 这样的 AngularJS 变量，则必须在模板文件的最上方先定义好一个新变量，如 `appid`，其值为 `'{{appid}}'`，例如：** ``` {% set appid = '{{appid}}' %} {% set appkey = '{{appkey}}' %} {% set masterkey = '{{masterkey}}' %} ``` 这样，在生成的 html 文档中，`{{appid}}` 才可以被正确渲染，否则，它会被替换为空值，原因是 nunjucks 在上下文中找不到该变量的定义。 其他常用的 [nunjucks 模板方法](https://mozilla.github.io/nunjucks/templating.html) 还有： ``` {# 这是注释，用 无效 #} {% if numUsers < 5 %}...{% endif %} {% if i != "String" %}...{% endif %} // boolean 的否定要用 not 而不是 ! {% if not isNew %}...{% endif %} {% if users and showUsers %}...{% endif %} {% if i == 0 and not hideFirst %}...{% endif %} {% if (x < 5 or y < 5) and foo %}...{% endif %} // 复用文档片断 {% macro ... %} {% include ... %} ``` ### 辅助工具 「一套模板多分渲染」的不同渲染文件编写起来比较困难，需要先从主模板上找到变量在对应到渲染文件，所以开发了一个简单的工具来简化这一步骤。使用方式如下： * 安装需要的依赖，该步骤只需要执行一次： ``` npm install ``` * 启动辅助工具的本地 webServer，使用以下命令： ``` $ node server ``` * 使用浏览器打开 http://localhost:3001，将会看到一个「选择模板」的下拉列表框，该列表框里会显示 `views/.tmpl` 的所有模板文件，文件名的 `tmplName` 部分是下拉列表框选项的名称。选择你需要编写的模板（比如 `leanengine_guide`）。 * 你会看到模板文件被读取，其中所有 `{% block %}{% endblock %}` 部分的下面都会有一些按钮。这些按钮表示该「模板」拥有的不同「渲染」，也就是对应的 `views/-.md` 文件，文件名的 `impl` 部分是按钮的名称。 * 点击对应的按钮，即可看到「渲染」文件中对应 `block` 的内容已经读取到一个文本域中，如果为空，表明该「渲染」文件未渲染该 block，或者内容为空。 * 在文本域中写入需要的内容，然后点击保存，编写的内容就会保存到对应的「渲染」文件的 block 中。 * 最后建议打开「渲染」文件确认下内容，没问题即可通过 `grunt server` 查看效果。当然整个过程打开 `grunt server` 也是没问题的，它会发现「渲染」文件变动后重新加载。 有问题请与 联系。 ## License LGPL-3.0 --- ## File: custom/js/lib/zeroclipboard/docs/releases.md ### ZeroClipboard 1.1.7 * [FEATURE] `data-clipboard-target` will look for an element by id, and get the value. * [FEATURE] `dataRequested` method will be called when the flash object is looking for data. * [FEATURE] Unregister events with .off #84 * [FEATURE] [AMD](https://github.com/amdjs/amdjs-api/wiki/AMD) support #99 * [BUG] Respect element scrollTo position #82 reverted 471974975064d710c15442c1170e9dbac9c542ec caused bugs #93 * [BUG] On some linux distros, the copied text couldn't be pasted into terminal. #78 * [BUG] Make ZeroClipboard XHTML compatible #95 ### ZeroClipboard 1.1.6 **IMPORTANT: WE NO LONGER ACCEPT QUERY STRINGS. INSTEAD PASS AN ELEMENT OR ARRAY OF ELEMENTS** **IMPORTANT: new ZeroClipboard.Client() is now new ZeroClipboard()** * [FEATURE] The selector `ZeroClipboard.$` was removed in favor of leaving it up to the user. #63 * [FEATURE] Creating new instance of the class is easier `new ZeroClipboard()` #65 * [FEATURE] Overhaul of the options setting and getting. Now via the constructor or setDefaults. * [BUG] It was possible to glue an element multiple times. * [BUG] Removing multiple functions for same action. Was causing multiple firings. * [BUG] After destroy, there was an error on mouseover of old client. ### ZeroClipboard 1.1.5 * [BUG] When the border is NaN, IE will throw errors. #57 * [CHORE] Bower component.json is now pointing at non-minified zeroclipboard src ### ZeroClipboard 1.1.4 To the future, 1.1.4 will address any bugs from the previous release. * [SECURITY] Removing `flash.system.Security.allowDomain("*");` default. now should be set via flashvars. * [SECURITY] XSS Vunerability, the clipText returned from the flash object needs to be escaped. * [CHORE] Renaming internal var from `.moviePath` to `._moviePath` shouldn't change anything in the api. ### ZeroClipboard 1.1.1, 1.1.2, 1.1.3 Emergency bug release. * [BUG] IE6/7/8 mouseup and mousedown bug. Events weren't being registered properly #55 ### ZeroClipboard 1.1.0 This release re-writes a lot of how zeroclipboard client works. Check the docs for more details. * [FEATURE] Replace dom selector with simple sizzler query selector * [FEATURE] Indicate via an event when there is no flash or flash is wrong version * [FEATURE] More meta info passed with each flash event. * [FEATURE] Register more than one event `.on("load complete", function() {})` * [FEATURE] Event handlers can now access the clicked element via `this` * [BUG] setText doesn't override the default data-clipboard-text attribute. * [BUG] When creating more than one clip, the second clip doesn't glue. * [BUG] If there is no currentElement return from reposition #51 * [BUG] ready() wasn't returning false when bridge wasn't ready. ### ZeroClipboard 1.0.9 * [FEATURE] Use `data-clipboard-text` as default text #35 * [FEATURE] When object contains `title` use put that title on swf object #15 #25 * [CHORE] Bower component file * [CHORE] Makefile for building * [CHORE] Unit tests with nodeunit and jsdom * [CHORE] Build scripts * [BUG] IE8 "Object doesn't support this property" #19 ### ZeroClipboard 1.0.8 This version was the first version under new management. Most of what occurred was re-organization and cleaning. But here are some bugs fixed. * [FEATURE] Vaadin plugin updates #4 * [FEATURE] Adding module export ability #8 #9 * [CHORE] Npm package install ce7b514f9f650f54e8cec0ef52457424e41edc71 * [BUG] XSS Vunerability #2 * [BUG] Fix swf position #16 ### Zero Clipboard 1.0.7 Released Zero Clipboard 1.0.7 can now copy **Rich HTML** to the clipboard. When this is pasted into an application that supports rich text, it will show up as fully rendered HTML (not the source that was copied). Since this feature only works in Flash Player 10, it is opt-in, and must be specifically enabled in your code. See the updated [Instructions](https://github.com/zeroclipboard/ZeroClipboard/blob/master/docs/instructions.md) for details. Thanks to jpp at cloudview for the patch! ### Zero Clipboard 1.0.5 Released Zero Clipboard 1.0.5 can now glue the Flash movie to a relatively positioned parent element (instead of the page body), resulting in perfect positioning of the movie on top of your copy button. This also allows you to use Zero Clipboard inside overflow:auto or position:fixed elements. The [Instructions](instructions.md) have been updated with details on how to use the new feature. The API is 100% backward compatible with previous versions. --- ## File: custom/js/lib/zeroclipboard/docs/roadmap.md # Roadmap These are things that we have expressed interest in, but haven't implemented yet. There is no order, if you feel like you can complete one of the tasks. Feel free to fork the project and send a pull request with the new code.
rich clipboard
The flash clipboard api supports RichText Data, and HTML Data. We want to enable that.
actionscript tests
We want to setup a unit test suite for the flash file.
HTML5 Clipboard API
In a perfect world we wouldn't need ZeroClipboard, and the browsers would just take care of it. I would like to write ZeroClipboard to use the browser clipboard api when available.
--- ## File: custom/js/lib/zeroclipboard/docs/security.md ### ZeroClipboard Security We try our best to keep ZeroClipboard secure, but there are some rules that you should follow to keep your site safe. #### Rules Basically, if an attacker gets access to the main window/global object via an XSS exploit, it's pretty much an instant "GAME OVER" unless **ALL** of the following are true: 1. The `ZeroClipboard` object itself is not globally accessible. 2. The `ZeroClipboard.prototype` object itself is not globally accessible. 3. No `ZeroClipboard` instances are globally accessible. 4. No callback functions for dispatched ZeroClipboard events are globally accessible. 5. If a variable is used to set the path to the SWF via `ZeroClipboard#setDefaults`, that variable must not be globally accessible. #### Examples 1. Having `ZeroClipboard` instances globally accessible (versus encapsulated in a closure). This allows an attacker to manually call a client's `setText` method and inject their own text. 2. As with all globally accessible functions in JavaScript, any globally accessible callback functions (hooked to events) can be overridden by an attacker. This isn't terribly dangerous but could be annoying. 3. **If** we add a `"dataRequested"` event (see #46), then users would need to apply the safety precautions mentioned in_**both**_ of the aforementioned examples to avoid allowing an attacker to inject their own text. 4. Overriding any of the `ZeroClipboard`, `ZeroClipboard`, or `ZeroClipboard.prototype` properties or methods, if globally accessible. ### Responsible Disclosure If you find any security holes, please submit a pull request, or file an issue. We will be very appreciative.