We wrote a multi-faceted project in five minutes

CML (Chameleon Chameleon), as a framework for truly making a set of code run multi-terminal, provides standard MVVM mode for unified development of various terminals.

At the same time, it has independent runtime framework (Runtime), data management (Store), component library (UI), interface (API).

In addition, CML has done a lot of work in strengthening cross-end capabilities, unifying capabilities, and performing consistently.

Today, in order to make your project elegant upgrade, fast access, bring you a sumptuous CML migration guide ~

---

Send you a 5 minute video tutorial

---

Source code address: github.com/jalonjs/cml…

The directory structure

Like wechat applets, CML consists of an APP that describes the overall program and multiple pages that describe their respective pages.

Applets directory structure

. ├ ─ ─ the components// Contains each component├ ─ ─ pages// contains each page├ ─ ─ app. Js// Contains each component├ ─ ─ app. Js// App startup entry├ ─ ─ app. Json// Global configuration├ ─ ─ app. WXSS// Global style└ ─ ─ project. Config. Json// Project configuration file

Copy the code

CML directory structure

. ├ ─ ─ dist// Each end builds the result│ ├ ─ ─ alipay │ ├ ─ ─ they │ ├ ─ ─ wx │ ├ ─ ─ web │ ├ ─ ─ weex │ └ ─ ─ config. The json// Configure the map mapping table on both ends├ ─ ─ node_modules// Third-party libraries├ ─ ─ the mock// Simulate interface data and template data├ ─ ─ the SRC// Source code development directory│ ├ ─ ─ the app// App startup entry│ ├ ─ ─ assets// Static resources│ ├ ─ ─ the components// Contains components│ ├ ─ ─ pages// Include pages│ ├ ─ ─ store// Data management│ └ ─ ─ the router. Config. Json// Route configuration file├ ─ ─ chameleon. Config. Js// Project configuration file└ ─ ─ package. Json// NPM package configuration file

Copy the code

How to Modify the Configuration

In the small program project, divided into:

Applets – Project configuration

The project can be configured using the project.config.json file in the project root directory.

Configuration example:

{
  "miniprogramRoot": "./src"."debugOptions": {}}Copy the code

Applets – global configuration

The app.json file in the root directory of the applets is used for global configuration of wechat applets, determining the path of page files, window performance, setting network timeout, setting multiple tabs, etc

Configuration example:

{
  "pages": ["pages/index/index"."pages/logs/index"]."window": {
    "navigationBarTitleText": "Demo"
  },
  "networkTimeout": {
    "request": 10000."downloadFile": 10000}}Copy the code

Applets – page configuration

Each applet page can also use a.json file to configure the window appearance of the page.

The configuration of the page can only set part of the window configuration items in app.json. The configuration items in the page overwrite the same configuration items in the window of app.json.

Configuration example:

{
  "navigationBarBackgroundColor": "#ffffff"."navigationBarTextStyle": "black"."navigationBarTitleText": "Wechat Interface Function Demonstration"."backgroundColor": "#eeeeee"."backgroundTextStyle": "light"
}
Copy the code

Similarly, the CML project is divided into:

CML — Project configuration

Chameleon.config. js is a configuration file for your project that you can customize to build, such as hash, compression, etc.

Configuration example:

// Set an online path for the static resource
const publicPath = '//www.static.chameleon.com/static';
// Set the API request prefix
const apiPrefix = 'https://api.chameleon.com';
// Merge the configuration
cml.config.merge({
  wx: {
    build: {apiPrefix}
  },
  alipay: {
    build: {apiPrefix}
  },
  baidu: {
    build: {apiPrefix}
  },
  web: {
    dev: {
      hot: true.console: true
    },
    build: {
      publicPath: `${publicPath}/web`,
      apiPrefix
    }
  },
  weex: {
    build: {
      publicPath: `${publicPath}/weex`,
      apiPrefix
    }
  }
})

Copy the code

CML — Global configuration

The of the app. CML file in the APP directory of the CML project is used to configure CML applications globally, with cross-end configuration and differentiation capabilities

Configuration example:

<script cml-type="json">
{
  "base": {
    "window": {
      "navigationBarTitleText": "All ends share title",},"permission": {
      "scope.userLocation": {
        "desc": "Your location information will be used to display the effects of the applet location interface."}}},"wx": {
    "window": {
      "backgroundTextStyle":"light"."navigationBarBackgroundColor": "#fff"."navigationBarTitleText": "Differentiated title"."navigationBarTextStyle":"black"}},"baidu": {
    "window": {
      "backgroundTextStyle": "light"}},"alipay": {
      "window": {
        "defaultTitle": "Chameleon"}}}</script>
Copy the code

CML — Page/component configuration

The referenced component is registered through the usingComponents configuration path.

Configuration example:

<script cml-type="json">
{
  "base": {
    "usingComponents": {
      "navi": "/components/navi/navi"."navi-npm": "cml-test-ui/navi/navi"}},"wx": {},"alipay": {},"baidu": {},"web": {},"weex": {}}</script>
Copy the code

How do I use routing capabilities

Applets configure routes

The Pages field in the app.json configuration item list is used to specify which pages the applet consists of, and each item corresponds to the path + file name information of a page.

The first entry in the array represents the initial page (home page) of the applet. Add/reduce pages, need topagesArray is modified.

If the project has pages/index/index.wxml and pages/logs/logs. WXML, it needs to be written in app.json

{
  "pages": ["pages/index/index"."pages/logs/logs"]}Copy the code

CML configures routes

SRC /router.config.json is a route configuration file. CML has a set of built-in route management modes for all ends. The corresponding CML route configuration mapping is as follows:

{
  "mode": "history"."domain": "https://www.chameleon.com"."routes":[
    {
      "url": "/cml/h5/index"."path": "/pages/index/index"."mock": "index.php"
    },
    {
      "url": "/cml/h5/logs"."path": "pages/logs/logs"."mock": "logs.php"}}]Copy the code

File names do not need to be suffixed, and the CML framework will automatically find.cML files for processing.

Applets use routing

• Open a new page: call API wx.navigateTo
• Page redirection: Call API wx.redirectTo
• NavigateBack: call API wx.navigateBack
• Open another small program: call API Wx. navigateToMiniProgram
• Return to a small program: call API wx. NavigateBackMiniProgram

CML uses routing

Adaptively open the same route PATH in different environments according to the uniform resource index URI:

• Open a new page: call chameleon-api cmL. navigateTo
• Page redirection: Call chameleon-API cmL.redirectto
• NavigateBack: call chameleon-api cmL. navigateBack
• Open another cross-application: call chameleon-api cmL.open
• Go back to the previous cross-application: call chameleon-api cmL.close

How to sign up

How to register the program

Applet registration program

In the applet project, the App() function is used to register a applet. Accepts an Object parameter that specifies the life cycle callback of the applet, etc.

The sample code

App({
  onLaunch(options) {
    // Do something initial when launch.
  },
  globalData: 'I am global data'
})
Copy the code

CML registration program

The sample code

<script>
import store from '.. /store/index.js'
import routerConfig from '.. /router.config.json';

class App {
  data = {
    store,
    routerConfig
  }
  created(res) {
  }
}

export default new App();
</script>
Copy the code

Careful you will find,

The mapping between app.json app.js app.wxss and SRC /app/app.cml is as follows

Small program app. Js	CML project SRC/app/app. CML
app.js	<script></script>
app.wxss	<style></style>
app.json	<script cml-type="json"></script>

How to Register page

Applets registration page

In applets, the Page(Object) function is used to register a Page. Accepts an Object parameter that specifies the page’s initial data, lifecycle callbacks, event handlers, and so on.

Sample code:

// index.js
Page({
  data: {
    text: 'This is page data.'
  },
  changeText: function(e) {
    // sent data change to view
    this.setData({
      text: 'CML'})}})Copy the code

CML registration page

The sample code

<script>
class Index {
  data = {
    text: 'Chameleon'
  }
  methods = {
    changeText: function(e) {
      // sent data change to view
      this.text = 'CML';
    }
  }
  computed = {}
  watch = {}
};
export default new Index();
</script>
Copy the code

How to register a component

Applets register components

In an applet project, the Component(Object) constructor can be used to define a Component. The Component constructor can be called to specify its properties, data, methods, and so on.

The sample code

Component({
  properties: {
    myProperty: { / / the property name
      type: String.// Type (required)
      value: ' ' // Attribute initial value (optional)
    },
    myProperty2: String // A simplified definition
  },
  data: {
    text: ' '
  }, // Private data that can be used for template rendering

  // The lifecycle function can be a function, or a method name defined in the Methods section
  attached() { }, 
  ready() { },
  methods: {
    onMyButtonTap() {
      this.setData({
        // Attributes and data are updated in a similar way to page data
        text: 'wx'}}}})Copy the code

CML registers components

The sample code

<script>
class MyComponent {
  props = {
    myProperty: { / / the property name
      type: String.// Type (required)
      default: ' ' // Attribute initial value (optional)
    },
    myProperty2: String // A simplified definition
  }
  data =  {
    text: ' '
  } // Private data that can be used for template rendering

  beforeMount() {}
  mounted() {}
  methods = {
    onMyButtonTap() {
      this.text = 'cml'
    }
  }
  computed = {}
  watch = {}
};
export default new MyComponent();
</script>
Copy the code

How do I declare the life cycle

Unifying the definition of application life cycle is an important component of cross-end framework and the only way to migrate.

Applets declare life cycles

You can pass the Object argument to App(Object), Page(Object), Component(Object), which specifies the life cycle callback of the applet, etc

Code sample

// index.js
Page({
  onLoad(options) {
    // Do some initialize when page load.
  },
  onReady() {
    // Do something when page ready.
  },
  onShow() {
    // Do something when page show.
  },
  onHide() {
    // Do something when page hide.
  },
  onUnload() {
    // Do something when page close.
  },
  onShareAppMessage() {
    // return custom share data when user share.}})Copy the code

CML declares the life cycle

An instance of an object returned in the.cML file code block that specifies the lifecycle callback

The sample code

<script>
class Index {
  beforeCreate(query) {
    // Before data data is mounted to the this root, and before methods all methods are mounted to the instance root
    // Note that only the page beforeCreate hook will return the page query
    console.log('App beforeCreate: Opens the current page path with the parameter is', query)
  }
  created() {
    // These events in data,methods are mounted
    console.log('App created')
  }
  beforeMount() {
    // Start to mount the compiled CML to the corresponding node
    console.log('App beforeMount')
  }
  mounted() {
    // The CML template is compiled and rendered into the DOM only once in its lifetime
    console.log('App mounted')
  }
  beforeDestroy() {
    // Before instance destruction
    console.log('App beforeDestroy')
  }
  destroyed() {
    // After the instance is destroyed
    console.log('App destroyed')}};export default new Index();
</script>
Copy the code

App lifecycle mapping

App.js -> CML SRC /app/app.cml

Small program	chameleon
onLaunch	beforeCreate
onShow	mounted
onHide	destroyed

Page life cycle mapping

In the life cycle of small programs Page () – > CML SRC/pages/mypage/mypage. CML

Small program	chameleon
onLoad	beforeCreate
onShow	mounted
onUnload	destroyed
onReady	Life cycle polymorphism
onHide	Life cycle polymorphism
onShareAppMessage	Life cycle polymorphism

Component lifecycle mapping

Small application Component () – > in the life cycle of CML SRC/components/mycomponent/mycomponent CML

Small program	chameleon
created	created
attached	beforeMount
ready	mounted
detached	destroyed

Life cycle summary

Each CML instance (App, Page, Component) goes through a series of initialization procedures when it is created ————

For example, you need to set up data listening, compile templates, mount instances to CML nodes and update CML nodes when data changes, and so on. There are also functions called lifecycle hooks that run along the way, giving developers the opportunity to add their own code at different stages.

CML provides a series of life cycle events for apps, pages, and components to ensure orderly application execution.

Alternatively, if you want to use an end-specific lifecycle, you can use lifecycle polymorphism from a business perspective.

How does the data respond to the view

Today, two-way data binding and one-way data flow are common to developers, and THE MVMM development model is standard in the framework.

How are data binding, conditional rendering, and list rendering written?

The sample code

Applets use data responses

<! --wxml-->
<view class="scroller-wrap">
    <! -- Data binding -->
  <view>{{message}}</view>
  <! -- Conditional Render -->
  <view wx:if="{{view == 'WEBVIEW'}}">WEBVIEW</view>
  <view wx:elif="{{view == 'APP'}}">APP</view>
  <view wx:else="{{view == 'MINA'}}">MINA</view>
    <! -- List render -->
  <view wx:for="{{array}}" wx:for-index="index" wx:for-item="item">{{item}}</view>
</view>
Copy the code

// page.js
Page({
  data: {
    message: 'Hello MINA! '.view: 'MINA'.array: [1.2.3.4.5]
  },
  onLoad() {
    this.setData({
      message: 'wx'})}})Copy the code

CML uses data responses

<template>
<! --index.cml-->
<view class="scroller-wrap">
    <! -- Data binding -->
  <view>{{message}}</view>
  <! -- Conditional Render -->
  <view c-if="{{view == 'WEBVIEW'}}">WEBVIEW</view>
  <view c-else-if="{{view == 'APP'}}">APP</view>
  <view c-else="{{view == 'MINA'}}">MINA</view>
    <! -- List render -->
  <view c-for="{{array}}" c-for-index="index" c-for-item="item">{{item}}</view>
</view>
</template>
<script>
class Index {
  data =  {
    message: 'Hello MINA! '.view: 'MINA'.array: [1.2.3.4.5]
  }

  beforeCreate () {
    this.message = 'cml'}};export default new Index();
</script>
Copy the code

Summary of data response

The CML runtime framework provides a cross-end responsive Data binding system. When Data is modified, only the Data needs to be modified in the logical layer, and the view layer will make corresponding updates.

Just need to view<–>model interaction part of the logic, simple migration, can make it become a multi-terminal data response system.

Event interaction

CML supports some basic events to ensure that all side effects (types, bindings, event objects) run consistently.

The sample code

Applets use events

<! --wxml-->
<view id="tapTest" data-hi="WeChat" bindtap="tapName">Click me!</view>
Copy the code

// page.js
Page({
  tapName(event) {
    console.log(event)
  }
})
Copy the code

CML usage events

<template>
  <view id="tapTest" data-hi="WeChat" c-bind:tap="tapName">
    <text>Click me!</text>
  </view>
</template>
<script>
class Index {
  methods = {
    tapName(e) {
      // Prints the event object
      console.log('Event object :', e); }}}export default new Index();
</script>
Copy the code

Event Usage Summary

Custom events are also supported for communication between parent and child components.

In addition, CML does not limit your freedom if you want to use end-specific events, you can use component polymorphism or interface polymorphism differentiation for business purposes.

Layout and appearance

There are differences in cascading style sheet (CSS) implementations that describe layout and appearance at each end, including but not limited to layout, box models, positioning, and text.

As a result, the CML framework has built-in cross-end consistency base styling capabilities.

Also, a Style specification CMSS(Chameleon Style Sheet) for describing pages is defined.

How do I import external styles

The @import statement can be used to import an external style sheet, followed by the relative path of the external style sheet to be imported, using; Indicates the end of the statement.

Applets import external styles

Sample code:

/** common.wxss **/
.small-p {
  padding:5px;
}
Copy the code

/** app.wxss **/
@import "common.wxss";
.middle-p {
  padding:15px;
}
Copy the code

CML imports external styles

Detailed documentation

Sample code:

/** common.css **/
.small-p {
  padding: 5px;
}
Copy the code

<! -- app.cml -->
<style>
  @import './common.css';
  .middle-p {
    padding:15 cpx;
  }
</style>
Copy the code

Summary of style usage

At the same time, in order to unify the multi-end size units and render the same effect, as well as the responsive layout of the page, THE CML project uniformly adopts CPX as the size unit and stipulates that the screen 750px (full screen) visual draft is taken as the standard.

Moreover, each side of the stylesheet has different capabilities and is one of the main areas of project migration.

In addition, CML does not limit your freedom if you want to use end-specific style capabilities, you can use style polymorphism for business purposes

Note: Because chameleon applications are multi-facetedWeb Native appletsFrame if needed acrossnative, must be usedflexboxStyle layout!!

component

CML projects are all components. Components are the basic building blocks of a view.

Frameworks provide developers with a set of basic components that can be combined for rapid development.

Such as:

<template>
  <view>
    <view>View Basic Components</view>
    <text>Text Base Component</text>
  </view>
</template>
Copy the code

At the same time, CML supports concise componentized programming.

Custom Components

Developers can abstract functional modules within a page into custom components that can be reused across different pages. Custom components are very similar to the base components when used.

How do I create custom components

Applets create custom components

Code examples:

Component({
  properties: {
    // Here we define the innerText property, whose value can be specified when the component uses it
    innerText: {
      type: String.value: 'default value',}},data: {
    // Here is some internal component data
    someData: {}
  },
  methods: {
    // Here is a custom method
    customMethod() {}
  }
})
Copy the code

CML creates custom components

The sample code

<script>
class MyComponent {
  props = {
    // Here we define the innerText property, whose value can be specified when the component uses it
    innerText: {
      type: String.value: 'default value',
    }
  }
  data = {
    // Here is some internal component data
    someData: {}
  }
  methods = {
    // Here is a custom method
    customMethod() {}
  }
  computed = {}
  watch = {}
};
export default new MyComponent();
</script>
Copy the code

How to use custom components

Before using a registered custom component, a reference is declared. In this case, you need to provide the label name of each user-defined component and the path to the user-defined component file.

Applets use custom components

Code examples:

Declare references in page.json

{
  "usingComponents": {
    "component-tag-name": "path/to/the/custom/component"}}Copy the code

Used in page.wxml

<view>
  <! The following is a reference to a custom component -->
  <component-tag-name inner-text="Some text"></component-tag-name>
</view>
Copy the code

CML uses custom components

Code examples:

In page. CML for reference declaration

<script cml-type="json">
{
  "base": {
      "usingComponents": {
        "component-tag-name": "path/to/the/custom/component"}}}</script>
Copy the code

is used in page.cml

<template>
<view>
  <! The following is a reference to a custom component -->
  <component-tag-name inner-text="Some text"></component-tag-name>
</view>
</template>
Copy the code

How to implement parent-child component event communication

Event system is one of the main ways of communication between components. Custom components can trigger arbitrary events that pages referencing components can listen for.

Applets component communication

Code examples:

<! -- page page.wxml -->
<view>
  <my-component bindcustomevent="onMyEvent"></my-component>
</view>
Copy the code

/ / page page. Js
Page({
  methods: {
    onMyEvent(e) {
      console.log(e.detail) // Customize the detail object provided when the component fires an event}}})Copy the code

<! My-component.wxml -->
<view>
  <button bindtap="onTap">Clicking this button will trigger the "myevent" event</button>
</view>
Copy the code

/ / component my - component. Js
Component({
  methods: {
    onTap() {
      this.triggerEvent('customevent', {}) // Triggers custom component events}}})Copy the code

CML component communication

Code examples:

<! -- page page.cml -->
<template>
  <view>
    <my-component c-bind:customevent="onMyEvent"></my-component>
  </view>
</template>
<script>
class Index {
  methods = {
    // Here is a custom method
    onMyEvent(e) {
      console.log(e.detail) // Customize the detail object provided when the component fires an event}}};export default new Index();
</script>
<script cml-type="json">
{
  "base": {
      "usingComponents": {
        "my-component": "path/to/the/custom/component"}}}</script>
Copy the code

<! - page path/to/the/custom/component. The CML - >
<template>
  <view>
    <button c-bind:tap="onTap">Clicking this button will trigger the "myevent" event</button>
  </view>
</template>
<script>
class MyComponent {
  methods = {
    // Here is a custom method
    onTap() {
      this.$cmlEmit('customevent', {}) // Triggers custom component events}}};export default new MyComponent();
</script>
<script cml-type="json">
{}
</script>
Copy the code

Component Usage Summary

Like applets, the CML framework provides a number of built-in components and extension components that smooth out the differences and make it easy for developers to combine these components to create powerful applications.

Extension components need to be brought in extra. Such as:

<script cml-type="json">
{
  "base": {
      "usingComponents": {
        "c-dialog": "cml-ui/components/c-dialog/c-dialog"}}}</script>
Copy the code

When CML build build packaging is performed, the CML framework packages referenced built-in components and extension components as needed, slimming down the code.

Both built-in components and extension components are supported across multiple endpoints. For some components that do not provide one end, component polymorphism can be implemented.

If you want to use native components on the applet side, you can prefix the native tag with Origin -* and the CML framework will render the native component reference

Note:origin-*Only in theGrayscale fileIn use!!

If using the native map component

in map.wx. CML:

<! -- map.wx.cml -->
<template>
  <origin-map
    id="map"
    longitude="113.324520"
    latitude="23.099994"
    controls="{{controls}}"
    bindcontroltap="controltap"
    style="width: 100%; height: 300px;"
  ></origin-map>
</template>
Copy the code

How to invoke platform interface capabilities

In the mini program, you can use wechat’s native API to enable functions such as access to user information, local storage, and payment.

The sample code

try {
  wx.setStorageSync('name'.'Hanks')}catch (e) {
  console.error(e)
}
Copy the code

Also, in a CML project you can call this:

The sample code

import cml from 'chameleon-api'
cml.setStorage('name'.'Hanks').then((res) = >{
  console.log(res)
},function(e){
  console.error(e)
})
Copy the code

Summary of Interface usage

CML framework provides a rich polymorphic interface, which can be used to adjust the native capabilities provided by each end, such as system information, element node information, animation effects, local storage, network requests, geographical location, etc. Please refer to the API documentation.

Chameleon-api provides interfaces that support cross-endpoints. For some native interfaces that are not provided, they can be called through interface polymorphism.

Migrating instance

The CML guide for migrating each end (VUE, WEEX, and applet) and the specific migration document for exporting CML components to each end are given below:

• How do I migrate a Vue project to Chameleon
• How do I migrate a Weex project to Chameleon
• How to migrate a wechat applets to Chameleon
• A normal project uses the Chameleon cross-dialog component