# App Service / Logic Layer

# 1. Introduction to the Logic Layer

The Mini-Program development framework uses a JavaScript engine for its Logic Layer, providing a runtime environment for the developer's JavaScript code along with specific functionalities of FinClip Mini-Programs.

The Logic Layer processes data and sends it to the View Layer, while also receiving event feedback from the View Layer.

All code written by the developer will eventually be packaged into a single JavaScript file, which runs when the Mini-Program starts and continues until the Mini-Program is destroyed. This behavior is similar to ServiceWorker, hence the Logic Layer is also referred to as the App Service.

Building upon JavaScript, we have added several features to facilitate Mini-Program development:

  • Added App and Page methods for program registration and page registration.
  • Added getApp and getCurrentPages methods to retrieve the App instance and the current page stack, respectively.
  • Provided modularization capabilities, with each page having its own independent scope.

# 2. Registering a Mini-Program

# App(Object)

The App() function is used to register a Mini-Program. It accepts an Object parameter.

App() must be called in app.js and can only be called once.

Object Parameter Description

Property Type Description Trigger Timing
onLaunch Function Lifecycle callback—listens for Mini-Program initialization Triggered when Mini-Program initialization is complete (triggered globally only once)
onShow Function Lifecycle callback—listens for Mini-Program display Triggered when the Mini-Program starts or comes to the foreground from the background
onHide Function Lifecycle callback—listens for Mini-Program hide Triggered when the Mini-Program moves from the foreground to the background
onError Function Error listener function Triggered when a script error occurs in the Mini-Program or an API call fails, includes error information
onPageNotFound Function Page not found listener function Triggered when the page the Mini-Program attempts to open does not exist, includes page information callback
Others Not restricted Developers can freely add any functions or data to the Object parameter, accessible via this

Foreground and Background Definitions

After the Mini-Program starts, if the user can see the current interface, the Mini-Program is in the foreground state. When the user closes the Mini-Program via the ellipse button in the upper right corner or leaves the Host-App, the Mini-Program does not terminate immediately but enters the background state, triggering the onHide callback event.

When the user re-enters the Host-App or re-opens the Mini-Program, the Mini-Program switches from the background to the foreground, triggering the onShow callback event. If the user does not open the Mini-Program for a long time or if system resources are tight, the Mini-Program may be destroyed, exiting completely.

Example Code

App({
  onLaunch: function(options) {
    console.log("launch parameters",options)
  },
  onShow: function(options) {
     console.log("onShow parameters",options)
  },
  onHide: function() {
  },
  onError: function(error) {
    console.log("Error information:",error)
  },
  globalData: ''
})

# onLaunch(Object)

Triggered when Mini-Program initialization is complete. Triggered globally only once.

Object Parameter Description

Field Type Description
path String The path used to open the Mini-Program
query Object The query field when opening the Mini-Program, configurable via sharing or invocation protocol
referrerInfo Object Returned when entering the Mini-Program from another Mini-Program or App
referrerInfo.appId String The appId of the source Mini-Program, see details below
referrerInfo.extraData Object Data passed from other sources

# onShow(Object)

Triggered when the Mini-Program starts or comes to the foreground from the background. Triggered every time it switches to the foreground.

Object Parameter Description

Same as onLaunch.

# onHide()

Triggered when the Mini-Program moves from the foreground to the background. Triggered every time it switches to the background.

# onError(String error)

Triggered when a script error occurs in the Mini-Program or an API call fails.

Parameter Description

Name Type Description
error String Error information including stack trace

# onPageNotFound(Object)

Triggered when the target page to be opened does not exist. Often used to catch situations where the target page of a route jump does not exist.

Parameter Description

Name Type Description
path String The path of the non-existent page
query Object The query parameters of the non-existent page
isEntryPage Boolean Whether it is the first page of this startup (e.g., entering from a share entry, the first page is the share page configured by the developer)

Developers can perform redirection handling in the onPageNotFound callback, but it must be handled synchronously within the callback; asynchronous handling is invalid.

Example Code

App({
  onPageNotFound(res) {
    jd.redirectTo({
      url: 'pages/index/index.fxml'
    }) 
  }
})

Note

  1. If the developer does not add an onPageNotFound listener, when the target page of a jump does not exist, it will be handled by the Host-App.
  2. Ensure that the target page redirected to in the onPageNotFound callback exists; otherwise, it will be handled by the Host-App, and onPageNotFound will not be called again to avoid infinite loops.

# getApp(Object)

Global method. The getApp() function can be used to obtain the Mini-Program App instance, commonly used in pages to access global data and methods of the APP instance. Note that within the APP() method in app.js, it can be obtained directly via this; in other pages, use the getApp() method.

Object Parameter Description

Field Type Description
allowDefault Boolean Returns a default implementation when the App is not defined. When the App is called, properties defined in the default implementation will be merged into the App.

Example Code

const APP = getApp();
console.log(APP.globalData) // Output global data

# 3. Registering Pages

# 3.1 Using the Page Constructor to Register Pages

The Page(Object) function is used to register a page. It accepts an Object type parameter, specifying the page's initial data, lifecycle callbacks, event handlers, etc.

Property Type Description
data Object The initial data of the page
onLoad Function Lifecycle callback—triggered when the page loads
onShow Function Lifecycle callback—listens for page display
onReady Function Lifecycle callback—listens for the completion of the page's initial rendering
onHide Function Lifecycle callback—listens for page hide
onUnload Function Lifecycle callback—listens for page unload
onPullDownRefresh Function Executed when pull-down refresh is triggered
onReachBottom Function Executed when the page reaches the bottom
onShareAppMessage Function Forward / Share
onPageScroll Function Handler function for page scroll events
onTabItemTap Function Triggered when a tab is clicked, if the current page is a tab page
Others Any Developers can add any functions or data to the Object parameter, accessible via this within the page's functions

Example Code

//index.js
Page({
  data: {
    userName: ""
  },
  onLoad: function(e) {
    this.getName();
  },
  onReady: function() {

  },
  onShow: function() {

  },
  onHide: function() {

  },
  onUnload: function() {

  },
  onPullDownRefresh: function() {

  },
  onReachBottom: function() {

  },
  onShareAppMessage: function () {

  },
  onPageScroll: function() {

  },
  onTabItemTap(item) {
    console.log("Currently clicked:",JSON.stringify(item))

  },
  // Event handler.
  getName: function() {
    this.setData({
      userName:"cortana"
    })
  },
  customData: {
    dName: 'cortana'
  }
})

For detailed parameter meanings and usage, please refer to the Page reference documentation.

# 3.1.1 Initial Data

data is the initial data used for the first rendering of the page.

Data in data must be of the following types: string, number, boolean, object, array.

The rendering layer can bind data via FXML.

Example Code

<view>{{userName}}</view>
<view>{{cover[0].url}}</view>
Page({
  data: {
    userName: 'cortana',
    cover: [{url: 'http://xxxxx.jpg',title:"avatar"}, {url: 'http://xxxxx.jpg',title:"detail"}]
  }
})

# 3.2 Lifecycle Callback Functions

For lifecycle triggers and page routing methods, please refer to the detailed documentation.

# onLoad(Object query)

Triggered when the page loads. Called only once per page. Parameters from the path used to open the current page can be obtained in the onLoad parameters.

Parameter Description

Name Type Description
query Object Parameters from the path used to open the current page

# onShow()

Triggered when the page is displayed/comes to the foreground.

# onReady()

Triggered when the page's initial rendering is complete. Called only once per page, indicating the page is ready and can interact with the View Layer.

Note

APIs that set interface content, such as jd.setNavigationBarTitle, should be called after onReady.

# onHide()

Triggered when the page is hidden/moves to the background. Examples: navigating to another page via navigateTo, switching to another page via bottom tab, Mini-Program moving to background, etc.

# onUnload()

Triggered when the page is unloaded. Examples: redirectTo or navigateBack to another page.

# 3.3 Page Event Handler Functions

# onPullDownRefresh()

Listens for the user's pull-down refresh event.

####onReachBottom() Listens for the user's reach bottom event.

# onPageScroll(Object)

Listens for the user's page scroll event.

Parameter Description

Property Type Description
scrollTop Number The distance the page has scrolled vertically (in px)

# onShareAppMessage(Object)

Listens for user clicks on the share button within the page (<button> component with open-type="share") or the "Recommend to Friends" button in the upper right corner menu. Supports custom sharing content. This event requires returning an Object to configure the sharing content. See "Sharing Content Configuration" for details.

Object Parameter Description

Property Type Description
from String Source of the share event. button: in-page share button; menu: "Recommend to Friends" menu in the upper right corner
target Object If from is button, then target is the button that triggered this share event; otherwise undefined
webViewUrl String When the page contains a <web-view> component, returns the current <web-view>'s url

Sharing Content Configuration

Property Type Required Description
mpId string No WeChat Mini-Program ID. Used when sharing to WeChat; after the user clicks the share card, they enter the WeChat Mini-Program corresponding to this appid, directing traffic to the WeChat Mini-Program.
title string No Share title
type number No Share type (0 - WeChat Mini-Program release version; 1 - WeChat Mini-Program development version; 2 - WeChat Mini-Program trial version)
path string No Mini-Program path
mpPath string No WeChat Mini-Program path
imageUrl string Yes Image address (Mini-Program cover image or H5 page cover)
channel string No Channel (defaults to WeChat Friends, WeChat Moments if not specified)
url string No H5 link address (for H5 sharing, defaults to intermediate page if not filled)
desc string No Share content summary

Example Code

Page({
  onShareAppMessage: function (res) {
    console.log(res.target);
    return {
     mpId: 'Shared WeChat Mini-Program appid',
     title: 'Shared title',
     type: 0,
     desc: 'Shared description, summary, etc.',
     imageUrl: 'http://pic30.finogeeks.com/20130619/9885883_210838271000_2.jpg',
     path: 'page/component/index',
     mpPath:'Shared WeChat Mini-Program path',
     channel:'Wxfriends,Wxmoments',
     url: 'https://super-apps.ai/develop/index/ao00f99475552b3131',
    }
  }
})

After sharing the example code to WeChat Friends, the corresponding release version WeChat Mini-Program will open; sharing to Moments will open the H5 page corresponding to the url.

# onTabItemTap(Object)

Triggered when a top or bottom tab is clicked.

Object Parameter Description

Parameter Type Description
index String The index of the clicked tabItem, starting from 0
pagePath String The page path of the clicked tabItem
text String The button text of the clicked tabItem

Example Code

Page({
  onTabItemTap(item) {
    console.log("Tab bar click:",item);
  }
})

# 3.4 Component Event Handler Functions

Event handler functions for components can also be defined in Page. In the .fxml file, add event bindings to components. When an event is triggered, the corresponding event handler function defined in Page will execute.

Example Code

<view bindtap="getUsername">Get Username</view>
Page({
  getUsername: function() {
    console.log("Clicked get username")
  }
})

# 3.5 Using the Component Constructor to Construct Pages

Supported since Base Library 1.6.3

The Page constructor is suitable for simple pages. However, for complex pages, the Page constructor might not be ideal.

In such cases, the Component constructor can be used to construct pages. The main difference with the Component constructor is that methods need to be placed inside methods: { }.

Code Example

Component({
  data: {
    text: "This is page data."
  },
  methods: {
    onLoad: function(options) {
      // Executed when the page is created
    },
    onPullDownRefresh: function() {
      // Executed during pull-down refresh
    },
    // Event response function
    viewTap: function() {
      // ...
    }
  }
})

This creation method is very similar to Custom Components and allows the use of advanced features like behaviors. Please refer to the Component Constructor chapter for specific details.

# Page.route

The path to the current page, type is String.

Example Code

<view bindtap="getCurrentRoute"> Click to view current page route </view>
Page({
  getCurrentRoute: function() {
    console.log("Current page route:",this.route)
  }
})

# Page.prototype.setData(Object data, Function callback)

The setData function is used to send data asynchronously from the Logic Layer to the View Layer, while also changing the corresponding value in this.data (synchronously).

Object Parameter Description

Field Type Required Description
data Object Yes The data to be changed this time
callback Function No Callback function after the interface update rendering caused by setData is complete

Object is represented in key: value form, changing the value corresponding to the key in this.data to value.

Note

  1. Directly modifying this.data cannot change the page's state.
  2. Only supports setting data that can be JSON serialized.
  3. The amount of data set in a single call should not be too large; cannot exceed 1024KB.
  4. Please do not manually set the value of any item in data to undefined.

Example Code

<!--index.fxml-->
<view>{{title}}</view>
<button bindtap="changeTitle"> Change String Type </button>
<view>{{num}}</view>
<button bindtap="changeNum"> Change Number Type</button>
<view>{{array[0].name}}</view>
<button bindtap="changeArray">Change Array Type </button>
<view>{{object.name}}</view>
<button bindtap="changeObject">Change Object Type </button>
//index.js
Page({
  data: {
    title: 'I am title',
    num: 0,
    array: [{name: 'cortana'}],
    object: {
      text: 'init data'
    }
  },
  changeText: function() {
    this.setData({
      title: 'New Title'
    })
  },
  changeNum: function() {

    this.setData({
      num: this.data.num +1 
    })
  },
  changeArray: function() {
    this.setData({
      'array[0].name':'Mary'
    })
  },
  changeObject: function(){
    this.setData({
      'object.name': 'Mary'
    });
  }
})

# 4. Page Configuration

Each Mini-Program page can also use a .json file to configure the window presentation for that page.

Page configuration can only set part of the window configuration items found in app.json. Configuration items in the page will override identical items in app.json's window. Configurable options are as follows:

Property Type Default Value Description
navigationBarBackgroundColor HexColor #000000 Navigation bar background color, e.g., #000000
navigationBarTextStyle String white Navigation bar title color, only supports black, white
navigationBarTitleText String Navigation bar title text content
navigationBarTitleFixed Boolean false Whether the title is fixed. If set to true, the title does not change with the H5 title when loading H5; if set to false, it changes with the H5 title
backgroundColor HexColor #ffffff Window background color
backgroundColorContent HexColor Page container background color, supported since SDK 2.46.13
backgroundTextStyle String dark Pull-down loading style, only supports dark, light

Example my.json:

{
  "navigationBarBackgroundColor": "#ffffff",
  "navigationBarTextStyle": "black",
  "navigationBarTitleText": "Personal Center",
  "backgroundColor": "#eeeeee",
  "backgroundTextStyle": "light"
}

# 4.1 Modularization

# 4.1.1 File Scope

Variables and methods declared in a .js file are only valid within that file; different files can declare variables and methods with the same name.

The global application instance can be obtained via the global function getApp(). If global data is needed, it can be set in App(), for example:

// app.js
App({
  globalData: "cortana"
})

# 4.1.2 Modularization

Common code can be extracted into a separate js file as a module. A module can only expose interfaces through module.exports or exports.

Mini-Programs currently do not support "directly importing node_modules". They need to be introduced via Building npm. If needed, code can also be copied directly into the Mini-Program directory for use.

// util.js
function getDate() {
  return new Date().toLocaleTimeString()
}

module.exports.getDate =getDate
exports.getDate = getDate

In files that need to use these modules, use require(path) to import the common code.

var util = require('util.js');
Page({
  getDate: function() {
    let d = util.getDate();
    console.log(d);
  }
})

Hint

Note that when using require to import a module, a relative path must be used.

# 5 API

The Mini-Program development framework provides rich native WeChat-style APIs to conveniently invoke capabilities provided by the platform, such as obtaining user information, local storage, payment functions, etc. For detailed introductions, please refer to the API Documentation.

Typically, Mini-Program APIs can be categorized into the following types:

# 5.1 Event Listening APIs

By convention, APIs starting with on are used to listen for the triggering of certain events, e.g., ft.onSocketOpen, ft.onCompassChange, etc.

These APIs accept a callback function as a parameter. When the event is triggered, this callback function is called, and relevant data is passed in as parameters.

ft.onCompassChange(function (res) {
  console.log(res.direction)
})

# 5.2 Synchronous APIs

By convention, APIs ending with Sync are synchronous APIs, e.g., ft.setStorageSync, ft.getSystemInfoSync, etc. Additionally, there are some other synchronous APIs, such as ft.createWorker, ft.getBackgroundAudioManager, etc. For details, refer to the descriptions in the API documentation.

The execution result of a synchronous API can be directly obtained via the function's return value. If an error occurs during execution, an exception is thrown.

try {
  ft.setStorageSync('key', 'value')
} catch (e) {
  console.error(e)
}

# 5.3 Asynchronous APIs

Most APIs are asynchronous APIs, e.g., ft.request, ft.getNetworkType, etc. These API interfaces typically accept an Object type parameter. This parameter supports optionally specifying the following fields to receive the interface call results:

Object Parameter Description

Parameter Name Type Required Description
success Function No Callback function for successful API call
fail Function No Callback function for failed API call
complete Function No Callback function for API call completion (called regardless of success or failure)
Others Any - Other parameters defined by the API

The execution result of an asynchronous API needs to be obtained through the corresponding callback function passed in the Object parameter. Some asynchronous APIs also have return values, which can be used to implement richer functionalities, such as ft.request, ft.connectSocket, etc.

ft.setStorage({
  key: "key",
  data: "value",
  success() {
    console.log('setStorage succeed');
  }
})

# 5.4 Asynchronous APIs Returning Promise

Starting from Base Library version 3.0.25, asynchronous APIs support both callback & promise calling methods. When the interface's Object parameter does not contain success/fail/complete, it will return a promise by default. Otherwise, it will still execute in callback mode and return no value.

Hints

  1. Some interfaces like downloadFile, request, uploadFile, connectSocket inherently have return values. Their promisify needs to be encapsulated by the developer.
  2. When there are no callback parameters, the asynchronous interface returns a promise. If the function call fails and enters the fail logic, it will report an error Uncaught (in promise), which developers can catch using .catch.
  3. ft.onUnhandledRejection can listen for unhandled Promise rejection events.
  4. On some Android devices due to system reasons, when using the promisify method to call an API, if then, catch, or finally is not subsequently called, the onUnhandledRejection listener will not be triggered when that API reports an error.
// callback form call
ft.chooseImage({
  success(res) {
    console.log('res:', res)
  }
})

// promise form call
ft.chooseImage().then(res => console.log('res: ', res))
© FinClip with ❤ , Since 2017