[GitHub] zshshr closed pull request #253: Update the document of front-end-frameworks

[GitBox <gi...@apache.org>]

zshshr closed pull request #253: Update the document of front-end-frameworks
URL: https://github.com/apache/incubator-weex-site/pull/253
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/docs/guide/front-end-frameworks.md b/docs/guide/front-end-frameworks.md
index 43d664552..4097e8f57 100644
--- a/docs/guide/front-end-frameworks.md
+++ b/docs/guide/front-end-frameworks.md
@@ -14,11 +14,70 @@ Currently, Weex mainly supports [Vue.js](https://vuejs.org/) and [Rax](https://a
 
 It is better to learn some basics of Vue.js or Rax before using Weex.
 
+## Framework Type Annotation
+
+Weex only determined which front-end framework is used of a specific page at runtime (just before rendering the page). So you have to mark what type of front-end framework you are using in the js bundle.
+
+### Using Comment
+
+In v0.16 and earlier, Weex is using specific format comments to annotate the framework type, the format is `// { "framework": "Xxx" }`, the `Xxx` in it is the name of front-end framework.
+
+> NOTICE: **The comment type annotation must be placed at the beginning of the code.** Only spaces or blank lines can be put before it.
+
+For example, the comment type annotation of Vue is:
+
+```js
+// { "framework": "Vue" }
+```
+
+The comment type annotation of Rax is:
+
+```js
+// { "framework": "Rax" }
+```
+
+### Using Directive Prologue <badge text="0.17+" type="warn" vertical="middle"/>
+
+Using comments is not a robust way to declare the framework type, because it may be removed during compiling or packaging. Since the v0.17, Weex supports using [Directive Prologue](http://ecma-international.org/ecma-262/5.1/#sec-14.1)）to indicate the framework type. The format of directive prologue type annotation is `"use weex:xxx";`, the `Xxx` in it is the name of front-end framework. Both `'` (single quote) and `"` (double quotes) are fine, but must be lower case.
+
+
+> NOTICE: **The directive prologue type annotation must be placed before all runnable codes.** Only spaces, blank lines or comments can be put before it.
+
+For example, the directive prologue type annotation of Vue is:
+
+```js
+"use weex:vue";
+```
+
+The directive prologue type annotation of Rax is:
+
+```js
+"use weex:rax";
+```
+
+### Be Compatible with All Versions of Weex
+
+If you are using v0.17 or higher version of Weex SDK, recommend you to use `"use weex:xxx";` as the type annotation. But if consider to be compatible with all versions of Weex, you can use both comments and directive prologue.
+
+For example, the compatible type annotation of Vue is:
+
+```js
+// { "framework": "Vue" }
+"use weex:vue";
+```
+
+The compatible type annotation of Rax is:
+
+```js
+// { "framework": "Rax" }
+"use weex:rax";
+```
+
 ## Vue.js
 
 Weex integrated the v2 version of Vue.js since WeexSDK [v0.10.0](https://github.com/alibaba/weex/releases/tag/v0.10.0) is released at 2017/02/17. Vue (pronounced /vjuː/, like view) is a progressive front-end framework for building user interfaces. Please refer to its [official website](https://vuejs.org/) for more information.
 
-Please refer to [Use Vue.js on Weex](./use-vue.html) document to learn more technics about Weex and Vue.
+Please refer to [Use Vue.js on Weex](./use-vue-in-weex.html) document to learn more technics about Weex and Vue.
 
 ## Rax
 
diff --git a/docs/zh/guide/front-end-frameworks.md b/docs/zh/guide/front-end-frameworks.md
index ee6dc49bb..b58dac75e 100644
--- a/docs/zh/guide/front-end-frameworks.md
+++ b/docs/zh/guide/front-end-frameworks.md
@@ -12,11 +12,69 @@
 
 > **学习一些 Vue 和 Rax 的基础知识，对使用 Weex 非常有帮助。**
 
+## 框架类型标记
+
+Weex 仅在运行时（开始渲染页面之前）才会确定页面使用哪种 DSL，因此要在页面代码中标记使用的是哪种类型的前端框架。
+
+### 使用注释标记
+
+在 Weex v0.16 以及更早的版本中，使用特定格式的注释来标记框架类型，格式是 `// { "framework": "xxx" }`，其中的 `xxx` 指的是前端框架的名字（首字母大写）。
+
+> 注意： **注释类型标记必须放在代码最前面。** 标记之前只能有空格或者空行，不能有其他类型的字符。
+
+例如 Vue 框架的类型标记如下：
+
+```js
+// { "framework": "Vue" }
+```
+
+Rax 框架的类型标记如下：
+
+```js
+// { "framework": "Rax" }
+```
+
+### 使用字符串标记  <badge text="0.17+" type="warn" vertical="middle"/>
+
+使用注释作为框架标记不够稳妥，在打包过程中有可能会被移除掉，因此从 v0.17 版本开始 Weex 支持使用 ECMAScript 规范中的“指令序言”（[Directive Prologue](http://ecma-international.org/ecma-262/5.1/#sec-14.1)）来标记各种前端框架的类型，标记的格式是 `"use weex:xxx";`，其中的 `xxx` 指的是前端框架的名字，兼容单引号和双引号，字符串内容保持小写。
+
+> 注意： **字符串类型标记必须放在所有可代码之前。** 标记之前可以有空格、空行或者注释，但是不能有可执行的代码。
+
+例如 Vue 框架的类型标记如下：
+
+```js
+"use weex:vue";
+```
+
+Rax 框架的类型标记如下：
+
+```js
+"use weex:rax";
+```
+
+### 兼容所有版本的写法
+
+如果你集成 Weex SDK 都在 0.17 版本之上，建议使用 `"use weex:vue";` 作为框架类型标记。如果考虑兼容更早的版本，可以同时使用两种类型标记。
+
+例如 Vue 框架的类型标记如下：
+
+```js
+// { "framework": "Vue" }
+"use weex:vue";
+```
+
+Rax 框架的类型标记如下：
+
+```js
+// { "framework": "Rax" }
+"use weex:rax";
+```
+
 ## Vue.js
 
 Weex 从 [v0.10.0](https://github.com/alibaba/weex/releases/tag/v0.10.0)（发布于 2017/02/17）这个版本开始，就集成了 v2 版本的 Vue.js。Vue.js 是一套用于构建用户界面的渐进式框架，详情请参阅其[官方网站](https://vuejs.org/)。
 
-关于在 Weex 中使用 Vue 的技巧请参阅：[《使用 Vue》](./use-vue.html)。
+关于在 Weex 中使用 Vue 的技巧请参阅：[《在 Weex 中使用 Vue.js》](./use-vue-in-weex.html)。
 
 ## Rax
 


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services