Skip to content

Commit

Permalink
Format articles
Browse files Browse the repository at this point in the history
  • Loading branch information
@RuochenLyu
RuochenLyu committed Apr 11, 2014
1 parent 28a9008 commit 683a244
Show file tree
Hide file tree
Showing 4 changed files with 65 additions and 65 deletions.
30 changes: 15 additions & 15 deletions site/tours/tour-button.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@ name: tour-button
root: ../
---

这篇教程主要介绍如何给Simditor编写一个undo按钮，点击undo按钮编辑器的内容会回退到上一个状态。
这篇教程主要介绍如何给 Simditor 编写一个 undo 按钮，点击 undo 按钮编辑器的内容会回退到上一个状态。


###基本结构

创建文件`simditor-undo.coffee`，输入Simditor按钮的基本结构：
创建文件 `simditor-undo.coffee`，输入 Simditor 按钮的基本结构：

```coffee
class UndoButton extends SimditorButton
Expand All @@ -24,23 +24,23 @@ class UndoButton extends SimditorButton
Simditor.Toolbar.addButton UndoButton
```

Simditor的按钮都继承自[Button类](https://github.com/mycolorway/simditor/blob/master/src/buttons/button.coffee)，跟扩展类似Simditor也提供一个方法用来添加按钮：`Simditor.Toolbar.addButton()`。
Simditor 的按钮都继承自 [Button 类](https://github.com/mycolorway/simditor/blob/master/src/buttons/button.coffee)，跟扩展类似 Simditor 也提供一个方法用来添加按钮：`Simditor.Toolbar.addButton()`。

Button类有这些可以设置的属性：
Button 类有这些可以设置的属性：

* `name` 按钮的名称，用于识别按钮，构造按钮的class `toolbar-item-[name]`
* `icon` 按钮icon的名称，对应FontAwesome的class名称 `fa-[icon]`
* `title` 按钮的title，鼠标悬停会显示的提示文本
* `htmlTag` 按钮对应的html标签名称，用于识别按钮的激活状态（例如加粗按钮）
* `disableTag` 在指定的html标签中禁用按钮（例如在代码标签中禁用链接按钮）
* `needFocus` 按钮的功能是否依赖编辑器处于focus状态
* `name` 按钮的名称，用于识别按钮，构造按钮的 class `toolbar-item-[name]`；
* `icon` 按钮icon的名称，对应FontAwesome的class名称 `fa-[icon]`；
* `title` 按钮的title，鼠标悬停会显示的提示文本；
* `htmlTag` 按钮对应的 html 标签名称，用于识别按钮的激活状态（例如加粗按钮）；
* `disableTag` 在指定的 html 标签中禁用按钮（例如在代码标签中禁用链接按钮）；
* `needFocus` 按钮的功能是否依赖编辑器处于 focus 状态。

更多关于Button类的说明请参考文档[Button]({{ page.root }}docs/doc-button.html)。
更多关于 Button 类的说明请参考文档 [Button]({{ page.root }}docs/doc-button.html)。


###按钮点击事件

按钮被点击之后，Simditor会调用Button的`command`方法，我们需要在这个方法里处理按钮的点击事件：
按钮被点击之后，Simditor 会调用 Button 的 `command` 方法，我们需要在这个方法里处理按钮的点击事件：

```coffee
class UndoButton extends SimditorButton
Expand All @@ -59,15 +59,15 @@ Simditor.Toolbar.addButton UndoButton

###引用并配置按钮

为了在工具栏上显示undo按钮，我们需要编译并引用新编写的按钮文件：
为了在工具栏上显示 undo 按钮，我们需要编译并引用新编写的按钮文件：

```html
<script type="text/javascript" src="[script path]/jquery-2.1.0.js"></script>
<script type="text/javascript" src="[script path]/simditor-all.js"></script>
<script type="text/javascript" src="[script path]/simditor-undo.js"></script>
```

然后修改编辑器的`toolbar`配置：
然后修改编辑器的 `toolbar` 配置：

```js
var editor = new Simditor({
Expand All @@ -76,4 +76,4 @@ var editor = new Simditor({
});
```

Simditor默认支持的按钮有：bold, italic, underline, strikethrough, ol, ul, blockquote, code, link, image, indent, outdent。
Simditor 默认支持的按钮有：bold, italic, underline, strikethrough, ol, ul, blockquote, code, link, image, indent, outdent。
28 changes: 14 additions & 14 deletions site/tours/tour-dev-env.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@ root: ../

###获取源代码

在Github上fork Simditor的源代码仓库（[什么是fork？](https://help.github.com/articles/fork-a-repo)）：
在 Github 上 fork Simditor 的源代码仓库（[什么是 fork？](https://help.github.com/articles/fork-a-repo)）：

![Fork Simditor](http://pic.yupoo.com/farthinker_v/DFeVxRCs/custom.jpg)

然后将fork之后的仓库clone到本地：
然后将 fork 之后的仓库 clone 到本地：

```bash
$ git clone [email protected]:[your username]/simditor.git
Expand All @@ -22,19 +22,19 @@ $ git clone [email protected]:[your username]/simditor.git

###安装Gem包

Simditor使用[Bundler](http://bundler.io/)来管理依赖的Ruby Gem：
Simditor 使用 [Bundler](http://bundler.io/) 来管理依赖的 Ruby Gem：

* [sass](https://github.com/nex3/sass)：用来将scss文件编译为css文件
* [coffee-script](https://github.com/josh/ruby-coffee-script): 用来将coffee文件编译为js文件
* [github-pages](https://github.com/github/pages-gem): 在本地安装[Github Pages](https://pages.github.com/)使用的[Jekyll](http://jekyllrb.com/)环境，用来生成Simditor的网站
* [sass](https://github.com/nex3/sass)：用来将 scss 文件编译为 css 文件
* [coffee-script](https://github.com/josh/ruby-coffee-script): 用来将 coffee 文件编译为 js 文件
* [github-pages](https://github.com/github/pages-gem): 在本地安装[Github Pages](https://pages.github.com/) 使用的 [Jekyll](http://jekyllrb.com/) 环境，用来生成 Simditor 的网站

首先，确保你的系统中已经安装了[Ruby](https://www.ruby-lang.org/en/installation/)，然后在命令行中安装Bundler：
首先，确保你的系统中已经安装了 [Ruby](https://www.ruby-lang.org/en/installation/)，然后在命令行中安装 Bundler：

```bash
$ gem install bundler
```

进入Simditor根目录，安装依赖的Gem包：
进入 Simditor 根目录，安装依赖的 Gem 包：

```bash
$ cd simditor
Expand All @@ -43,28 +43,28 @@ $ bundle install

###安装Grunt

Simditor使用[Grunt](http://gruntjs.com/)来实现本地的自动化任务，例如运行本地开发服务器、监视源代码文件并自动编译等等。
Simditor 使用 [Grunt](http://gruntjs.com/) 来实现本地的自动化任务，例如运行本地开发服务器、监视源代码文件并自动编译等等。

Grunt需要通过[Node.js](http://nodejs.org/)的包管理工具npm来安装，所以先确保你的系统已经安装了Node.js，然后通过npm安装Grunt的命令行工具：
Grunt 需要通过 [Node.js](http://nodejs.org/) 的包管理工具 npm 来安装，所以先确保你的系统已经安装了 Node.js，然后通过 npm 安装 Grunt 的命令行工具：

```bash
$ sudo npm install -g grunt-cli
```

最后安装`package.json`里配置的grunt 插件：
最后安装 `package.json` 里配置的 grunt 插件：

```bash
$ npm install
```

###开始开发

现在运行grunt的默认任务：
现在运行 grunt 的默认任务：

```bash
$ grunt
```

然后用浏览器访问`http://localhost:3000/demo.html`，就可以打开本地生成的Simditor网站了。这个时候修改Simditor的源代码，grunt会自动编译并重新生成网站，你只需要刷新页面就可以测试最新的改动。
然后用浏览器访问 `http://localhost:3000/demo.html`，就可以打开本地生成的 Simditor 网站了。这个时候修改 Simditor 的源代码，grunt 会自动编译并重新生成网站，你只需要刷新页面就可以测试最新的改动。

如果你需要测试上传功能，只需要给url增加一个upload参数就可以开启上传本地图片的功能：`http://localhost:3000/demo.html?upload`。
如果你需要测试上传功能，只需要给 url 增加一个 upload 参数就可以开启上传本地图片的功能：`http://localhost:3000/demo.html?upload`。
28 changes: 14 additions & 14 deletions site/tours/tour-plugin.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,16 @@ name: tour-plugin
root: ../
---

这篇教程主要介绍如何为Simditor编写一个自动保存扩展，这个扩展需要实现这些功能：
这篇教程主要介绍如何为 Simditor 编写一个自动保存扩展，这个扩展需要实现这些功能：

* 在编辑器的内容发生变化的时候，编辑器的内容会被自动保存到localStorage；
* 编辑器初始化的时候，如果发现localStorage里保存了上一次编辑的内容，扩展会将编辑器的默认值设置为上一次编辑的内容；
* 编辑器所在表单提交的时候，localStorage里保存的内容会被重置
* 在编辑器的内容发生变化的时候，编辑器的内容会被自动保存到 localStorage；
* 编辑器初始化的时候，如果发现 localStorage 里保存了上一次编辑的内容，扩展会将编辑器的默认值设置为上一次编辑的内容；
* 编辑器所在表单提交的时候，localStorage 里保存的内容会被重置


###扩展的基本结构

创建`simditor-autosave.coffee`，输入扩展的基本结构：
创建 `simditor-autosave.coffee`，输入扩展的基本结构：

```coffee
class SimditorAutosave extends Plugin
Expand All @@ -27,20 +27,20 @@ class SimditorAutosave extends Plugin
Simditor.connect SimditorAutosave
```

Simditor的扩展继承自[Simple Module](https://github.com/mycolorway/simple-module)的[Plugin类](https://github.com/mycolorway/simple-module/blob/master/src/module.coffee#L66)，并且Simditor提供一个类方法`connect`用来安装扩展。
Simditor 的扩展继承自 [Simple Module](https://github.com/mycolorway/simple-module) 的 [Plugin类](https://github.com/mycolorway/simple-module/blob/master/src/module.coffee#L66)，并且 Simditor 提供一个类方法 `connect` 用来安装扩展。

在初始化扩展的时候，Simditor会给Plugin的constructor方法传入自己的引用`@widget`。
在初始化扩展的时候，Simditor 会给 Plugin 的 constructor 方法传入自己的引用 `@widget`。

`_init`方法和`constructor`的区别是，constructor在Simditor初始化扩展的时候（Simditor自身初始化之前）调用，而`_init`方法会在Simditor自身初始化完成之后调用。所以，在`_init`方法中，@widget的这些属性才是可用的：
`_init` 方法和 `constructor` 的区别是，constructor 在 Simditor 初始化扩展的时候（Simditor 自身初始化之前）调用，而 `_init` 方法会在 Simditor 自身初始化完成之后调用。所以，在 `_init` 方法中，@widget 的这些属性才是可用的：

* `@widget.textarea`：与Simditor绑定的textarea元素
* `@widtet.el`：Simditor的容器元素`div.simditor`
* `@widget.body`：Simditor的内容元素`div.simditor-body[contenteditable=true]`
* `@widget.textarea`：与 Simditor 绑定的 textarea 元素；
* `@widtet.el`：Simditor 的容器元素 `div.simditor`；
* `@widget.body`：Simditor的内容元素 `div.simditor-body[contenteditable=true]`。


###扩展的初始化选项

我们需要给Simditor增加一个autosave选项，用来开关autosave功能并且构造localStorage的key：
我们需要给 Simditor 增加一个 autosave 选项，用来开关 autosave 功能并且构造 localStorage 的 key：

```coffee
class SimditorAutosave extends Plugin
Expand All @@ -59,7 +59,7 @@ class SimditorAutosave extends Plugin
Simditor.connect SimditorAutosave
```

Plugin的opts属性会与Simditor的opts保持同步，所以我们可以在`_init`方法里通过`@opts.autosave`来获取Simditor初始化时传入的autosave选项。
Plugin 的 opts 属性会与 Simditor 的 opts 保持同步，所以我们可以在 `_init` 方法里通过 `@opts.autosave` 来获取 Simditor 初始化时传入的 autosave 选项。


###添加核心逻辑
Expand Down Expand Up @@ -91,5 +91,5 @@ class SimditorAutosave extends Plugin
Simditor.connect SimditorAutosave
```

其中，`valuechanged`是Simditor的自定义事件，每当编辑器的内容发生变化时会被触发，更多关于该事件的信息请参考[事件文档]({{ page.root }}docs/doc-event.html)。
其中，`valuechanged` 是 Simditor 的自定义事件，每当编辑器的内容发生变化时会被触发，更多关于该事件的信息请参考[事件文档]({{ page.root }}docs/doc-event.html)。

44 changes: 22 additions & 22 deletions site/tours/tour-usage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ root: ../

###第一步：下载并引用

在[这里]({{ page.root }}download.html)下载并解压最新版的Simditor文件，然后在页面中引入这些文件：
在[这里]({{ page.root }}download.html)下载并解压最新版的 Simditor 文件，然后在页面中引入这些文件：

```html
<link rel="stylesheet" type="text/css" href="[style path]/font-awesome.css" />
Expand All @@ -21,12 +21,12 @@ root: ../

其中，

* Simditor基于[jQuery](http://jquery.com)开发，`jquery.js`是必需的；
* [font-awesome.css](http://fontawesome.io/)是一个图片字体icon库，Simditor基于它来定义工具栏的按钮样式。为了让icon能够正常显示，需要将font文件（fontawesome-webfont.xxx）放到正确的路径里：`../fonts/`（如果把font-awsome.css放在`styles`文件夹，那么就应该把font文件放在跟`styles`同级的`fonts`文件夹）。另外，如果想自定义工具栏按钮的样式就可以不必引用`font-awesome.css`；
* [module.js](http://https://github.com/mycolorway/simple-module)是彩程内部使用的CoffeeScript组件抽象类，Simditor基于这个类开发；
* [uploader.js](https://github.com/mycolorway/simple-uploader)是一个与UI无关的上传逻辑，如果你的项目不需要上传附件，那么可以不引用这个文件。
* Simditor基于 [jQuery](http://jquery.com) 开发，`jquery.js` 是必需的；
* [font-awesome.css](http://fontawesome.io/) 是一个图片字体 icon 库，Simditor 基于它来定义工具栏的按钮样式。为了让 icon 能够正常显示，需要将 font 文件（fontawesome-webfont.xxx）放到正确的路径里：`../fonts/`（如果把 font-awsome.css 放在 `styles` 文件夹，那么就应该把 font 文件放在跟 `styles` 同级的 `fonts` 文件夹）。另外，如果想自定义工具栏按钮的样式就可以不必引用 `font-awesome.css`；
* [module.js](http://https://github.com/mycolorway/simple-module) 是彩程内部使用的 CoffeeScript 组件抽象类，Simditor 基于这个类开发；
* [uploader.js](https://github.com/mycolorway/simple-uploader) 是一个与 UI 无关的上传逻辑，如果你的项目不需要上传附件，那么可以不引用这个文件。

如果觉得需要引用的脚本文件太多，可以用`simditor-all.js`（里面包含了`module.js``uploader.js`和`simditor.js`）替换：
如果觉得需要引用的脚本文件太多，可以用 `simditor-all.js`（里面包含了`module.js` `uploader.js` 和 `simditor.js`）替换：

```html
<link rel="stylesheet" type="text/css" href="[style path]/font-awesome.css" />
Expand All @@ -39,41 +39,41 @@ root: ../

###第二步，初始化配置

在使用Simditor的HTML页面里应该有一个对应的`textarea`文本框，例如：
在使用 Simditor 的 HTML 页面里应该有一个对应的 `textarea` 文本框，例如：

```html
<textarea id="editor" placeholder="这里输入内容" autofocus></textarea>
```

我们需要在这个页面的脚本里初始化Simditor：
我们需要在这个页面的脚本里初始化 Simditor：

```js
var editor = new Simditor({
textarea: $('#editor')
});
```

`textarea`是初始化Simditor的必需选项，可以接受jQuery Object、HTML Element或者Selector String。另外，Simditor还支持这些可选option：
`textarea` 是初始化 Simditor 的必需选项，可以接受 jQuery Object、HTML Element 或者 Selector String。另外，Simditor 还支持这些可选 option：

* `placeholder`（默认值：''）编辑器的placeholder，如果为空Simditor会取textarea的placeholder属性
* `toolbar` （默认值：true）是否显示工具栏按钮
* `toolbarFloat` （默认值：true）是否让工具栏按钮在页面滚动的过程中始终可见
* `defaultImage`（默认值：'images/image.png'）编辑器插入混排图片时使用的默认图片
* `tabIndent`（默认值：true）是否在编辑器中使用`tab`键来缩进
* `params`（默认值：{}）键值对，在编辑器中增加hidden字段（input:hidden），通常用于生成form表单的默认参数
* `upload`（默认值：false）false或者键值对，编辑器上传本地图片的配置，常用的属性有`url`和`params`
* `pasteImage`（默认值：false）是否允许粘贴上传图片，依赖`upload`选项，仅支持Firefox和Chrome浏览器
* `placeholder`（默认值：''）编辑器的 placeholder，如果为空 Simditor 会取 textarea 的 placeholder 属性；
* `toolbar` （默认值：true）是否显示工具栏按钮；
* `toolbarFloat` （默认值：true）是否让工具栏按钮在页面滚动的过程中始终可见；
* `defaultImage`（默认值：'images/image.png'）编辑器插入混排图片时使用的默认图片；
* `tabIndent`（默认值：true）是否在编辑器中使用 `tab` 键来缩进；
* `params`（默认值：{}）键值对，在编辑器中增加 hidden 字段（input:hidden），通常用于生成 form 表单的默认参数；
* `upload`（默认值：false）false 或者键值对，编辑器上传本地图片的配置，常用的属性有 `url` 和 `params`；
* `pasteImage`（默认值：false）是否允许粘贴上传图片，依赖 `upload` 选项，仅支持 Firefox 和 Chrome 浏览器。

更详细的配置说明可以参考Simditor的[配置文档]({{ page.root }}/docs/doc-config.html)。配置完成之后刷新页面，Simditor应该就可以正确加载了。
更详细的配置说明可以参考 Simditor 的[配置文档]({{ page.root }}/docs/doc-config.html)。配置完成之后刷新页面，Simditor 应该就可以正确加载了。

###最后，自定义样式和交互

每个项目都有不同的设计风格，大多数时候我们需要修改Simditor的样式，让它的样式跟项目的风格相符。
每个项目都有不同的设计风格，大多数时候我们需要修改 Simditor 的样式，让它的样式跟项目的风格相符。

`simditor.css`是通过[Sass](http://sass-lang.com/)自动生成的代码，所以推荐大家修改`simditor.scss`，然后再重新生成css代码。
`simditor.css` 是通过[Sass](http://sass-lang.com/)自动生成的代码，所以推荐大家修改 `simditor.scss`，然后再重新生成css代码。

`.editor-style`选择符下面的样式，是Simditor输出HTML的中文排版样式，大家可以根据自己项目的情况进行调整。另外，如果不想使用[font-awesome.css](http://fontawesome.io/)来实现工具栏按钮的icon，可以将`font-awesome.css`去掉，然后增加`.toolbar-item-[button name]`选择符来自定义按钮样式。
`.editor-style` 选择符下面的样式，是 Simditor 输出 HTML 的中文排版样式，大家可以根据自己项目的情况进行调整。另外，如果不想使用[font-awesome.css](http://fontawesome.io/) 来实现工具栏按钮的 icon，可以将 `font-awesome.css` 去掉，然后增加 `.toolbar-item-[button name]` 选择符来自定义按钮样式。

有的项目有一些特殊的交互需求，例如自动保存功能或者@人的功能，我们可以基于[Simple Module](http://https://github.com/mycolorway/simple-module)来给Simditor编写扩展。关于编写扩展更详细的介绍请参考教程[《编写扩展》]({{ page.root }}tours/tour-plugin.html)。
有的项目有一些特殊的交互需求，例如自动保存功能或者 @ 人的功能，我们可以基于 [Simple Module](http://https://github.com/mycolorway/simple-module) 来给 Simditor 编写扩展。关于编写扩展更详细的介绍请参考教程[《编写扩展》]({{ page.root }}tours/tour-plugin.html)。


0 comments on commit 683a244

Please sign in to comment.