lucky-chen closed pull request #289: fix introduction link error && add doc
named
URL: https://github.com/apache/incubator-weex-site/pull/289
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/.vuepress/config.js b/docs/.vuepress/config.js
index 588c166a5..3d1445656 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -44,7 +44,8 @@ module.exports = {
['front-end-frameworks', 'Front-End Frameworks'],
['platform-difference', 'Platform Difference'],
['use-vue-in-weex', 'Use Vue in Weex'],
- ['use-rax-in-weex', 'Use Rax in Weex']
+ ['use-rax-in-weex', 'Use Rax in Weex'],
+ ['work-principles', 'How it works']
]
},
{
@@ -211,7 +212,8 @@ module.exports = {
['front-end-frameworks', '前端框架'],
['platform-difference', '平台差异'],
['use-vue-in-weex', '在Weex中使用Vue.js'],
- ['use-rax-in-weex', '在Weex中使用Rax.js']
+ ['use-rax-in-weex', '在Weex中使用Rax.js'],
+ ['work-principles', '工作原理']
]
},
{
diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md
index a87ad0db4..999bab3ce 100644
--- a/docs/guide/introduction.md
+++ b/docs/guide/introduction.md
@@ -32,7 +32,13 @@ In the example above, the `<div>` and the `<text>` elements
are rendered into co
-Weex implements render engines both on iOS and Android and provides a group of
[built-in components](../references/components/) for basic usage. Based on
these components, you can compose and wrap more custom components.
+Weex implements render engines both on iOS and Android and provides a group of
`built-in components` for basic usage. Based on these components, you can
compose and wrap more custom components. example:
+
+- [Text](../docs/components/text.html)
+- [Image](../docs/components/image.html)
+- [List](../docs/components/list.html)
+- [RichText](../docs/components/richtext.html)
+
Although the components in Weex look like HTML tags, you are not able to use
all of them, instead, you can only use the built-in components and your custom
components.
@@ -46,13 +52,18 @@ If you want to use additional native components, other than
the built-in compone
For those features that do not rely on the UI, Weex wraps them into
**modules**. You can use `weex.requireModule('xxx')` to require them. Weex
modules provide easy access to native capabilities in JavaScript, such as
network, storage, clipboard, and navigator. For example, you can [use `stream`
module to fetch the star count of
Vue.js](http://dotwe.org/vue/2ae062b6a04124a35bbe2da3b1e5c07b).
-Similarly, Weex provides a group of [built-in modules](../references/modules/)
for basic usage, and supports the integration of the existing native modules
into the Weex platform.
+Similarly, Weex provides a group of `built-in modules`for basic usage, and
supports the integration of the existing native modules into the Weex platform.
exapmle:
+
+- [storage](../docs/modules/storage.html)
+- [navigator](../docs/modules/navigator.html)
+- [animation](../docs/modules/animation.html)
+- [websockets](../docs/modules/websockets.html)
Here are some documents about how to extend native components and native
modules for Weex:
-- [Extend Web Render](./extend-web-render.html)
-- [Extend Android](./extend-android.html)
-- [Extend iOS](./extend-ios.html)
+- [Extend Web Render](../guide/extend/extend-web.html)
+- [Extend Android](../guide/extend/extend-android.html)
+- [Extend iOS](../guide/extend/extend-ios.html)
### Write Once, Run Everywhere
@@ -62,7 +73,7 @@ Using the same source code across different platforms can
dramatically increase
> You can read _[How it works](../wiki/index.html)_ and _[Design
> Principles](../wiki/design-principles.html)_ to know more about the
> technologies and ideas behind Weex.
-Although Weex uses a single codebase, you can still write platform specific
code. Weex provides `weex.config.env` and `WXEnvironment` (they are strictly
equal) to get the current runtime environment. You can use
`WXEnvironment.platform` to determine which platform the code is running on.
Except for the _platform_, `WXEnvironment` contains other information
pertaining to environment, such as _osVersion_ and _deviceModel_. Refer to
_[Weex variable](../references/weex-variable.html)_ for the complete list.
+Although Weex uses a single codebase, you can still write platform specific
code. Weex provides `weex.config.env` and `WXEnvironment` (they are strictly
equal) to get the current runtime environment. You can use
`WXEnvironment.platform` to determine which platform the code is running on.
Except for the _platform_, `WXEnvironment` contains other information
pertaining to environment, such as _osVersion_ and _deviceModel_. Refer to
_[Weex variable](../docs/api/weex-variable.html)_ for the complete list.
## Support For Multiple Front-End Frameworks
@@ -77,7 +88,7 @@ Weex supports [Vue.js](https://vuejs.org/) and
[Rax](https://alibaba.github.io/r
> Vue.js and Rax are already integrated into Weex SDK, you don't need to
> require them manually.
-However, Vue and Rax are not the only options. It is entirely possible to
integrate your favorite front-end framework into Weex! There is a document
_[Extend JS Framework](./extend-js-framework.html)_ that describes how to
integrate a different front-end framework, the process, however, is still
complicated and tricky. You need to understand many underlying details about
the js-native bridge and native render engines in order to successfully
integrate an alternate front-end framework.
+However, Vue and Rax are not the only options. It is entirely possible to
integrate your favorite front-end framework into Weex! There is a document
_[Extend JS Framework](../guide/extend/extend-framework.html)_ that describes
how to integrate a different front-end framework, the process, however, is
still complicated and tricky. You need to understand many underlying details
about the js-native bridge and native render engines in order to successfully
integrate an alternate front-end framework.
You can read _[Front-End Frameworks](./front-end-frameworks.html)_ for more
details.
@@ -89,19 +100,18 @@ At this point, you should have a general understanding of
Weex. The next step is
If you want to use weex right now:
- [Create new app](./develop/create-a-new-app.html)
-- [Integrate Weex to Your Existing App](./integrate-to-your-app.html)
-- [Set up Development Environment](./set-up-env.html)
-- [References](../references/)
+- [Integrate to existing Android app](./develop/integrate-to-android-app.html)
+- [Integrate to existing iOS app](./develop/integrate-to-iOS-app.html)
+- [Set up Development Environment](./develop/setup-develop-environment.html)
If you want to know the technologies and ideas behind Weex:
-- [How it Works](../wiki/index.html)
-- [Design Principles](../wiki/design-principles.html)
-- [Platform Differences between Weex and Web](../wiki/platform-difference.html)
+- [How it Works](./work-principles.html)
+- [Platform Differences between Weex and Web](./platform-difference.html)
After getting acquainted with Weex, if you want to contribute to make it even
better:
-- [Development Process](../development-process.html)
-- [How to Contribute](../contributing.html)
+- [Development Process](./contribute/development-process.html)
+- [How to Contribute](./contribute/how-to-contribute.html)
Considering that Weex is a cross-stack technology, fundamental knowledge of
front-end development, Vue.js, iOS, and Android would be especially helpful.
diff --git a/docs/guide/work-principles.md b/docs/guide/work-principles.md
new file mode 100644
index 000000000..3f658cc76
--- /dev/null
+++ b/docs/guide/work-principles.md
@@ -0,0 +1,71 @@
+---
+title: How it works
+type: wiki
+group: Design
+order: 1.1
+version: 2.1
+---
+
+<!-- toc -->
+
+## Overall Structure
+
+Weex is a client-side technology on the surface, but in fact it connects the
whole way from the local development environment to the cloud deployment and
distribution.
+
+Developers can first write an app page just like writing a web page, and then
compile the app page into a piece of JavaScript which is called Weex JS bundle.
+
+In the cloud, developers can deploy the generated JS bundle. And then it can
be requested or pre-fetched from a mobile app with WeexSDK.
+
+The WeexSDK would prepare a JavaScript engine to run corresponding JS bundle
when user opens a Weex page anytime. Usually the JS bundle will make some calls
to native-side through Weex JS bridge. They let native-side render the user
interface or handle user interactions, storage data, make network
communications, call device powers and so on.
+
+Even if a user does not install the App, he can still open a same web page in
the browser, using the same source code.
+
+
+
+## Local Development Environment
+
+The design of local development environment of Weex is based on the web
development experience. It help web developers writing mobile app UI with their
familiar HTML / CSS / JavaScript. At the same time Weex also do the official
support to [Vue.js](https://vuejs.org/), a very great front-end framework.
+
+In addition, the management of a Weex project is also very familiar with a web
project. First, web developers can use npm packages to manage dependencies.
Second, web developers can refer to all best practices from every process of a
web project such as scaffolding, development, preview, debugging, test etc.
+
+Also same as the best practice of web development, each Weex page will be
built into a JS bundle. In the browser, we put JS bundle into the web page as a
`<script>` tag. In the client, we put JS bundle into the local, and execute it
in WeexSDK.
+
+**Links**
+
+* [Platform differences between Weex and web](./platform-difference.html)
+* [use Vue in weex](./use-vue-in-weex.html)
+* [use Rax in weex](./use-rax-in-weex.html)
+
+
+## Cloud Deployment & Distribution
+
+Weex JS bundle can be deployed and distributed as a static resource. Almost
all current web development system and best practice can be applied to Weex
directly such as generating JS bundle through CMS system or deploying JS bundle
to static CDN, monitoring JS bundle traffic through server log, caching or
pre-fetching JS bundle to reduce networking cost etc.
+
+## Client-side JavaScript Engine
+
+Both iOS and Android client-side of Weex run a JavaScript engine to execute JS
bundles and send well defined instructions to the native render layers. We
choose JavaScriptCore in iOS and v8 in Android which provide strong performance
and stability.
+
+In order to make the mobile resources better utilized, we just run only one
instance of JavaScript for all Weex pages. That is, all JS bundles share the
same JavaScript instance, but each JS bundle context also isolated well by
default in the runtime. We also put Vue 2.0 as a built-in JS Framework,
developers do not have to pack it in each JS bundle, which save the size and
time of networking.
+
+## Client Rendering Layer
+
+Weex offers both iOS and Android native rendering layers. Each of them are
based on the Native DOM model and exposed to JavaScript APIs. At the same time
we provide a set of native components and modules to use. Also Weex has high
performance especially on first-screen loading time, memory cost and re-reuse
of long list, etc.
+
+Although Weex has provided a group of most commonly used components and
modules officially. But we definitely know they couldn't satisfy everyone. So
we design our native render as extendable as possible. You can extend more
components and modules on your own. We can build and share an Weex eco-system
together.
+
+**Links**
+
+* [Extend to iOS](./extend/extend-ios.html)
+* [Extend to Android](./extend/extend-android.html)
+* [iOS Api](../docs/api/ios-apis.html)
+* [Android Api](../docs/api/android-apis.html)
+
+## In the Browser
+
+Besides iOS and Android client, Weex also has a web version based on Vue 2.0.
Developers can just use Vue 2.0 to build the same page in browsers.
+
+**Links**
+
+* [Using js-service](../docs/api/js-service.html)
+* [Extend js framework](./extend/extend-framework.html)
+
diff --git a/docs/zh/guide/introduction.md b/docs/zh/guide/introduction.md
index d3f7b8f09..6a41981ec 100644
--- a/docs/zh/guide/introduction.md
+++ b/docs/zh/guide/introduction.md
@@ -18,7 +18,7 @@ Weex 的另一个主要目标是跟进当代先进的 Web 开发和原生开发
-这个例子在屏幕正中间渲染了一个单词 “Yo”。 如果你想在移动设备上预览渲染结果，你只需要安装[Weex playground
app](/cn/tools/playground.html) 或将 Weex SDK 集成到您自己的应用程序中，然后使用扫描网页右侧的二维码。
+这个例子在屏幕正中间渲染了一个单词 “Yo”。 如果你想在移动设备上预览渲染结果，你只需要安装[Weex playground
app](../tools/playground.html) 或将 Weex SDK 集成到您自己的应用程序中，然后使用扫描网页右侧的二维码。
在源代码的 `<template>` 中，`<div>` 你应该很熟悉了，它在 Weex 平台上也是一个通用容器。但是 `<text>` 组件是由 Weex
特有的，它是一个块级的文本容器，可以用来渲染文字。
@@ -32,7 +32,14 @@ Weex 的另一个主要目标是跟进当代先进的 Web 开发和原生开发
-Weex 提供了一套基础的[内置组件](../references/components/)。基于这些组件，你可以用 js 封装更多的上层组件。
+Weex 提供了一套基础的内置组件，比如
+
+- [Text](../docs/components/text.html)
+- [Image](../docs/components/image.html)
+- [List](../docs/components/list.html)
+- [RichText](../docs/components/richtext.html)
+
+基于这些组件，你可以用 js 封装更多的上层组件。
尽管 Weex 中的组件看起来很像 HTML 标签，但你无法使用所有 HTML 标签，只能使用内置组件和自定义组件。
@@ -46,13 +53,18 @@ Weex 提供了一套基础的[内置组件](../references/components/)。基于
对于那些不依赖于 UI 的功能，Weex 推荐将它们包装到**模块**中，然后使用 `weex.requireModule('xxx')` 来引入。
这是使用 javascript 调用原生功能的一种方法，如网络，存储，剪贴板和页面导航等功能。这里有一个[使用 `stream` 模块获取 Vue.js 的
star 数](http://dotwe.org/vue/2ae062b6a04124a35bbe2da3b1e5c07b) 的例子。
-同样，Weex 也提供了一套基础的[内置模块](../references/modules/)，也支持将已有的原生模块集成到 Weex 中。
+同样，Weex 也提供了一套基础的内置模块,比如
+
+- [storage](../docs/modules/storage.html)
+- [navigator](../docs/modules/navigator.html)
+- [animation](../docs/modules/animation.html)
+- [websockets](../docs/modules/websockets.html)
-关于如何扩展 Weex 的原生组件和原生模块，可以参考下列文档：
+也支持将已有的原生模块集成到 Weex 中。关于如何扩展 Weex 的原生组件和原生模块，可以参考下列文档：
-+ [扩展 Web 渲染器](./extend-web-render.html)
-+ [扩展 Android](./extend-android.html)
-+ [扩展 iOS](./extend-ios.html)
++ [扩展 Web](../guide/extend/extend-web.html)
++ [扩展 Android](../guide/extend/extend-android.html)
++ [扩展 iOS](../guide/extend/extend-ios.html)
### 一次编写，处处运行
@@ -60,7 +72,7 @@ Weex 可以只编写一份代码，开发出三端都可用的页面。
在多个端中使用相同的源代码可以显著提高开发效率，并简化测试，构建和发布流程。在此基础上，Weex
可以将前端的打包、测试流程与手机端监控、发布系统结合起来，提高开发效率。
-尽管 Weex 多端都是用的同一份代码，但是仍然支持针对特定的平台开发功能。Weex 提供了 `weex.config.env` 和
`WXEnvironment`（它们是相同的）来获得当前的运行时环境。你可以用 `WXEnvironment.platform`
来确定代码运行在哪个平台上。除了平台以外，`WXEnvironment` 还包含其他环境信息，如 *osVersion* 和 *deviceModel*，参考
*[Weex variable](../references/weex-variable.html)* 了解更多详细信息。
+尽管 Weex 多端都是用的同一份代码，但是仍然支持针对特定的平台开发功能。Weex 提供了 `weex.config.env` 和
`WXEnvironment`（它们是相同的）来获得当前的运行时环境。你可以用 `WXEnvironment.platform`
来确定代码运行在哪个平台上。除了平台以外，`WXEnvironment` 还包含其他环境信息，如 *osVersion* 和 *deviceModel*，参考
*[Weex variable](../docs/api/weex-variable.html)* 了解更多详细信息。
## 支持多个前端框架
@@ -75,9 +87,7 @@ Weex 可以只编写一份代码，开发出三端都可用的页面。
> Vue.js 和 Rax 都已经集成进了 Weex SDK，你不需要再额外引入。
-然而 Weex 也不是只支持 Vue 和 Rax，你也可以把自己喜欢的前端框架集成到 Weex
中。有一个文档*[扩展前端框架](/cn/guide/extend-js-framework.html)*描述了如何实现，但是这个过程仍然非常复杂和棘手，你需要了解关于
js-native 之间通信和原生渲染引擎的许多底层细节。
-
-
+然而 Weex 也不是只支持 Vue 和 Rax，你也可以把自己喜欢的前端框架集成到 Weex
中。有一个文档*[扩展前端框架](../guide/extend/extend-framework.html)*描述了如何实现，但是这个过程仍然非常复杂和棘手，你需要了解关于
js-native 之间通信和原生渲染引擎的许多底层细节。
## 下一步
@@ -86,19 +96,18 @@ Weex 可以只编写一份代码，开发出三端都可用的页面。
如果你想现在就用 Weex：
+ [创建一个 App](./develop/create-a-new-app.html)
-+ [将 Weex 集成到已有应用](./integrate-to-your-app.html)
-+ [配置开发环境](./set-up-env.html)
-+ [手册](../references/)
++ [将 Weex 集成到Android应用](./develop/integrate-to-android-app.html)
++ [将 Weex 集成到iOS应用](./develop/integrate-to-iOS-app.html)
++ [配置开发环境](./develop/setup-develop-environment.html)
如果你想了解 Weex 背后的原理：
-+ [Weex 是如何工作的](../wiki/index.html)
-+ [设计理念](../wiki/design-principles.html)
-+ [和 Web 平台的差异](../wiki/platform-difference.html)
++ [Weex 是如何工作的](./work-principles.html)
++ [和 Web 平台的差异](./platform-difference.html)
如果你想让 Weex 变得更好：
-+ [Weex 的开发流程](../development-process.html)
-+ [如何参与贡献](../contributing.html)
++ [Weex 的开发流程](./contribute/development-process.html)
++ [如何参与贡献](./contribute/how-to-contribute.html)
此外，Weex 是一个跨栈的技术，开发人员也是多样化的，学习一些前端开发、Vue.js、iOS 和 Android 的基本知识，会对你开发 Weex
有很大的帮助。
diff --git a/docs/zh/guide/work-principles.md b/docs/zh/guide/work-principles.md
new file mode 100644
index 000000000..056432aaf
--- /dev/null
+++ b/docs/zh/guide/work-principles.md
@@ -0,0 +1,61 @@
+---
+title: 工作原理
+type: wiki
+group: Design
+order: 1.1
+chapter_title: 优势介绍
+version: 2.1
+---
+
+<!-- toc -->
+
+## 整体架构
+
+Weex 表面上是一个客户端技术，但实际上它串联起了从本地开发、云端部署到分发的整个链路。开发者首先可在本地像编写 web 页面一样编写一个 app
的界面，然后通过命令行工具将之编译成一段 JavaScript 代码，生成一个 Weex 的 JS bundle；同时，开发者可以将生成的 JS bundle
部署至云端，然后通过网络请求或预下发的方式加载至用户的移动应用客户端；在移动应用客户端里，Weex SDK 会准备好一个 JavaScript
执行环境，并且在用户打开一个 Weex 页面时在这个执行环境中执行相应的 JS bundle，并将执行过程中产生的各种命令发送到 native
端进行界面渲染、数据存储、网络通信、调用设备功能及用户交互响应等功能；同时，如果用户希望使用浏览器访问这个界面，那么他可以在浏览器里打开一个相同的 web
页面，这个页面和移动应用使用相同的页面源代码，但被编译成适合Web展示的JS Bundle，通过浏览器里的 JavaScript 引擎及 Weex SDK
运行起来的。
+
+
+
+## 本地开发环境
+
+Weex 的本地开发环境基于 web 开发体验而设计，web 开发者可以通过自己熟悉的 HTML/CSS/JavaScript
技术和语法实现移动应用的界面。同时 Weex 也对 [Vue.js](https://vuejs.org/) 这一非常优秀的前端框架做了官方的支持。
+
+此外，Weex 的工程设计也是 web 开发者非常熟悉的，首先 web 开发者可以使用自己熟悉的 npm 进行依赖管理；其次 web
开发者在初始化工程、开发、调试、质量控制等各个环节，都可以参考 web 开发已有的最佳实践。
+
+和如今 web 开发的最佳实践一样，Weex 会把一个页面的源代码全部编译打包成一个 JS bundle，在浏览器中，我们需要把这个 JS bundle
作为一段 `<script>` 载入网页；而在客户端里，我们把这段 JS bundle 通过Weex SDK加载并直接执行。
+
+**相关阅读**
+
+* [Weex 和 Web 平台的差异](./platform-difference.html)
+* [在Weex使用Vue](./use-vue-in-weex.html)
+* [在Weex使用Rax](./use-rax-in-weex.html)
+
+## 云端部署和分发
+
+Weex 的 JS bundle 可以作为一段静态资源进行部署和下发，如同部署和下发 web 页面一样，几乎可以复用 HTML5
所有的工程体系和最佳实践。比如在本地开发环境通过部署工具将 JS bundle 部署到 CDN、通过 CMS
或搭建平台把业务数据和模块化的前端组件自动拼接生成 JS bundle、通过服务端 JS bundle 的流量和日志来统计页面的访问情况、通过
AppCache 或类似的方式对 JS bundle 在客户端进行缓存或预加载以降低网络通信的成本等。
+
+## 客户端 JavaScript 引擎
+
+Weex 的 iOS 和 Android 客户端中都会运行一个 JavaScript 引擎，来执行 JS
bundle，同时向各端的渲染层发送规范化的指令，调度客户端的渲染并实现其它各种能力。我们在 iOS 下选择了基于 JavaScriptCore
内核的iOS系统提供的 JSContext，在 Android 下也使用了 JavaScriptCore 内核的 JavaScript
引擎。经过长期优化与多种业务场景检验，JavaScriptCore 无论是从性能还是稳定性方面都为Weex提供了强有力的保障，同时也保证了双端
JavaScript 引擎的统一，更有利于开发者调试跨端的 JavaScript 错误。
+
+为了让整个移动应用的资源利用得更好，我们在客户端提供的 JavaScript 引擎是单例的，即所有 JS bundle 公用一个 JavaScript
执行环境实例，同时对每个 JS bundle 在运行时进行了上下文的隔离，使得每个 JS bundle 都能够高效安全的工作。我们还把 Vue 2.0 这样的
JS Framework 做了预置，开发者不必把 JS Framework 打包在每个 JS bundle 里，从而大大减少了 JS bundle
的体积，也就进一步保障了页面打开的速度。
+
+## 客户端渲染层
+
+Weex 目前提供了 iOS 和 Android 两个客户端的 native 渲染层。每个端都基于 DOM 模型设计并实现了标准的界面渲染接口供
JavaScript 引擎调用。并且结合 web 标准和 native 的特点和优势实现了一套统一的组件和模块。Weex
在性能方面的表现也是非常优异的，尤其是界面首屏加载时间、native 下长列表的资源开销和复用、CPU、内存、帧率等关键指标。当然，尽管 Weex
已经提供了一组开发者最常用的组件和模块，但面对丰富多样的移动应用研发需求，这些常用基础组件还是远远不够的，因此我们提供了灵活自由的能力扩展方式，开发者可以根据自身的情况定制属于自己的客户端组件和模块，进一步丰富
Weex 在客户端上的能力。
+
+**相关链接**
+
+* [如何扩展 iOS](./extend/extend-ios.html)
+* [如何扩展 Android](./extend/extend-android.html)
+* [iOS Api](../docs/api/ios-apis.html)
+* [Android Api](../docs/api/android-apis.html)
+
+
+## 浏览器渲染
+
+Weex 除了提供 iOS 和 Android 的客户端渲染层之外，还基于 Vue 2.0 对官方的所有组件和模块进行了 web 封装，开发者可以基于
Vue 2.0 用同一套源代码构建出在浏览器中相同效果的页面。并且同样可以横向扩展。
+
+**相关链接**
+
+* [如何使用 js-service](../docs/api/js-service.html)
+* [如何扩展 js framework](./extend/extend-framework.html)
----------------------------------------------------------------
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:
[email protected]
With regards,
Apache Git Services
