#Functional Page

Refers to a specific type of interface function, such as: login page, registration page, forgot password page, payment page, etc. The characteristic of such pages is that they have a single function, complete process, can be accessed independently, and have clear business entry and exit points.

Functional pages are registered through the framework function Page(), just like ordinary pages. After publishing, functional pages can be opened in other mini programs, enabling application page sharing and reuse.

Application example:

• Mini Program A - Has requirements for registration page, login page, forgot password page, etc.
• Mini Program B - Has requirements for registration page, login page, forgot password page, etc.

The registration page, login page, forgot password page, etc., of Mini Program A can be developed in the functional page mode. They can be self-referenced and provided to Mini Program B for introduction and use, achieving the capability of shared pages, and if other mini programs have such business needs later, they can also be introduced and used.

Environment Requirements

• Base library version: >= 2.12.0
• Container version: >= 3.5.0
• App public version: >= 5.0.0
• IDE version: >= 0.7.1

#Terminology

#Host Mini Program

Refers to the main mini program application that can import other functional mini programs for use. The source code path is miniprogramRoot.

#Functional Mini Program

Refers to mini-programs that can be imported into the host mini program. The source code path is funtionalRoot.

#Functional Page Examples

#Device Details

Device details provide a page carrying basic device information, including device name, device icon, device status, and device control. Each panel business should add the device details configuration.

{
    functionalPages: {
    settings: {
      appid: "tycryc71qaug8at6yt",
      entryCode: "entryyvaqnocapvsl1"
    },
  },
}

#Cool Play Bar

The Cool Play Bar is a page that combines features like scenario music rhythm, and the lighting device foundation and advanced capability sections, and it belongs to the type of value-added services.

{
    functionalPages: {
    rayPlayCoolFunctional: {
      appid: "tyg0szxsm3vog8nf6n"
    },
  },
}

#Timer Countdown

Timer countdown is a basic device capability for timed switching of devices, timer countdown, and other functions.

{
    functionalPages: {
    rayPlayCoolFunctional: {
      appid: "tyjks565yccrej3xvo"
    },
  },
}

#Circadian Rhythm

The circadian rhythm function can simulate the changes of natural light brightness and color temperature throughout a day, allowing us to feel the return to natural light.

{
    functionalPages: {
    rayPlayCoolFunctional: {
      appid: "ty53odnmk2cxnzcxm6"
    },
  },
}

#Functional Page Development

There is a separate directory for the source code of the functional page, and files including js, tyml, tyss, images, etc., in the miniprogramRoot widgetRoot directories cannot be referenced internally.

#Getting Started Quickly

#Build Environment and Mini Program Development Process

For functional page development, you must use a smart mini program to create a project, do not use a non-smart mini program. The project creation process is consistent with each smart mini program, and for specific instructions, please refer to Getting Started with Smart Mini Program.

#Project Configuration

project.tuya.json

To develop a functional page, you need to declare miniprogramRoot and functionalRoot in the project.tuya.json file to correspond respectively to the mini program code directory and functional page code directory. For businesses developed based on the native mini program syntax, you need to specify the development directory, and for businesses developed by the ray framework, you need to specify the ray compilation output directory.

• Configuration content

{
  projectname: 'functional-demo',
  i18n: true,
  miniprogramRoot: 'dist/tuya/miniprogram', // Mini program compiled source code
  functionalRoot: 'dist/tuya/functional', // Functional page compiled source code directory
  projectId: 'your_project_id',
  baseversion: '2.12.0',
  dependencies: {
    // ...
  },
}

• Corresponding directory structure

dist/ #compiled output
|--functional/ #compiled functional page source code
     └──├── functional.json  # Functional page configuration file
        ├── functional.tyss # Functional page global styles
        ├── theme.json # Functional page theme configuration, if any
        ├── assets/
        │   └── logo.png  # Resources inside the functional page
|--miniprogram/ # Compiled mini program source code
functional/  # Functional page ray source code. The directory name is fixed as functional
  └──├── functional.config.ts  # Functional page configuration file
  	 ├── functional.tyss # Functional page global styles
  	 └── theme.json # Functional page theme configuration, if any
src/ # Mini program functional page directory
project.tuya.json # Project configuration file

#Functional Page Configuration functional.config.ts

Used to describe information about the current functional page mini program.

#Configuration Fields

#Example

export default {
  routes: [
    {
      name: 'detail', // Publish detail page corresponding to the key under publicPages in the app.json file
      isPublic: true, // Whether to release externally
      route: '/detail',
      path: 'pages/detail/index',
    },
    {
      name: 'third',
      isPublic: false,
      route: '/third',
      path: '/pages/third/index',
    },
  ],
};

In the example above, the detail page is externally published, and you can navigate to the detail page using this route in the business.

Example:

// Correct call
ty.navigateTo({
  url: `functional://settings/detail?${deviceId}`,
  success: (res) => {
    console.log('Navigate to functional page success', `functional://settings/detail?${query}`, res);
  },
  fail: (err) => {
    console.error('Navigate to functional page fail', `functional://settings/detail?${query}`, err);
  }
});

// Since only detail is registered under publicPages, the following route cannot navigate
ty.navigateTo({
  url: `functional://settings/third?${deviceId}`,
  success: (res) => {
    console.log('Navigate to functional page success', `functional://settings/third?${deviceId}`, res);
  },
  fail: (err) => {
    console.error('Navigate to functional page fail', `functional://settings/third?${deviceId}`, err);
  }
});

#Development and Debugging of Functional Pages

#Declare Dependencies of Functional Pages in app.json

In the host mini program, import the functional page mini program through the functionalPages field in global.config.ts. Use key-value format, where the key is the name of the functional page plugin and the value is the configuration information for the functional page.

{
  functionalPages: {
    settings: {
      appid: "tycryc71qaug8at6yt",
      entryCode: "entryyvaqnocapvsl1",
    },
  },
}

appid is the mini program ID. If it is consistent with the projectId in the current mini program (project.tuya.json), it indicates the functionality page is referencing itself.

#Navigate to Functional Page

Use the routing API to navigate, only supporting the three methods: ty.navigateTo, ty.redirectTo, ty.reLaunch.

The format is functional://{Functional Page Plugin Name}/{Publicly Exposed Page Name}, supporting query parameters.

For example, the name of the device detail functional page is: settings (as introduced above, fixed name, business party cannot change it); external address: detail (fixed name, named by the developer of the device detail functional page)

<navigator url="functional://settings/detail?deviceId=xxxxx" open-type="navigate">
  Navigate to Functional Page
</navigator>

ty.navigateTo({
  url: 'functional://settings/detail?deviceId=xxxxx',
});

#Internal Navigation in Functional Pages

Within the functional page, use relative paths for navigation.

ty.navigateTo({
  url: '../detail/index',
});

#Publishing Functional Pages

After development is completed, publish the mini program that the functional page belongs to. The upload function has been removed internally from the IDE, and internal developers need to package and upload in the panel management platform.

#Advanced Development

#Overall Architecture

#Same Business Architecture

As shown in the figure above, the loading structure of functional pages in the same business is relatively simple, and the logic exists in one mini program package.

• Business Mini Program: Used to carry the entry of functional pages and multi-language.
  • Business Logic: Conventional business logic without special restrictions. The dependency on the functional page plugin and its name must be declared in the mini program.
  • Multi-language: Contains the multi-language used in the mini program and functional pages, using the same multi-language package as the functional page.
• Business Functional Pages:
  • During business development, extract public logic that can be used across businesses. Except for necessary parameters and multi-language, there are no other dependencies on business mini programs.
  • Multi-language: Uses the multi-language package of the belonging mini program.
  • External Routes: Declare in publicPages for pages to be released externally.

#Different Business Architecture

As shown in the figure above, a mini program business may use functional pages other than those extracted from itself and depend on other functional pages.

• Business Mini Program: Carries business functions and business multi-language.
  • Business Logic: Regular business logic with no special restrictions. The dependency and configuration of functional page plugins need to be declared in the mini program, and different plugins need to be configured for different functional pages.
  • Multi-language: Contains the multi-language used in the mini program and functional pages, using the same multi-language package as the functional page.
• Business Functional Pages: During business development, extract public logic usable across businesses. Except for necessary parameters and multi-language, they have no other dependencies on business mini programs. They are not necessary.
  • Multi-language: Uses the belonging mini program’s multi-language package.
  • External Routes: Declare in publicPages for pages to be released externally.
• Other Functional Pages: They carry some common business logic, generally for common business logic, with no mandatory dependency on host business.
  • Multi-language: The multi-language exists in the multi-language package of the functional page’s belonging mini program.
• Multi-language priority: Host mini-program multi-language > Functional page multi-language.
• If the host mini-program includes the functional page, the multi-language package of the functional page is shared with the host mini-program.
• When using functional pages that are not included in the host mini-program, the multi-language package of the functional page is independent of the multi-language package of the host mini-program.
• When the field key value in the multi-language package of the functional page is the same as the field key value in the multi-language package of the host mini-program, the field value in the multi-language package of the host mini-program is taken.
• Multi-language packages between multiple functional pages are independent and will not affect each other.
• Add prefix: When developing functional pages, in order to avoid the multi-language in the functional pages from being unconsciously covered by the host multi-language. It is recommended to add a specific prefix to the multi-language field key value, and it is recommended to start with the abbreviation of the project name: for example, the Lamp Mutation Functional page uses lmf_ as the prefix of the multi-language key value.

#Experience Version Dependency

The experience version dependency allows functional page developers to validate relevant features before release, improving the development experience.

In global.config.ts, the version control related fields in functionalPages can be configured selectively according to requirements:

• versionType: Indicates the version type of the dependent functional page. The optional values are release and preview. The default is release.
• version: Indicates the version number of the dependent functional page. After configuration, only the functional page of the specified version will be loaded. By default, it is not configured, and the latest online version is loaded.

{
  functionalPages: {
    settings: {
      appid: "tycryc71qaug8at6yt",
      entryCode: "entryyvaqnocapvsl1",
      versionType: "preview",
      version: "1.0.0"
    },
  },
}

#Loading Strategy

In actual business development, a mini program might rely on multiple functional pages, if reliance is excessive, the download time will be longer. Therefore, the loading strategy needs to be specified to ensure the effect of loading functional pages.

The strategy field in global.config.ts under functionalPages indicates which strategy to use for loading functional pages. Optional values are lazyload and preload, with preload as the default.

lazyload: Lazy loading mode, download when navigating to functional pages. preload: Preloading mode, download when opening host mini program, default value.

Example:

{
  functionalPages: {
    settings: {
      appid: "tycryc71qaug8at6yt",
      entryCode: "entryyvaqnocapvsl1",
      strategy: "lazyload"
    },
  },
}

#Cross-Page Event Communication

Supports the eventChannel communication mode. For specifics, refer to getOpenerEventChannel.

Reserve specific event names in functional page development in advance for host mini program calls.

#Preset Functional Page Initialization Data

When custom functional page data is needed or if many parameters need to be passed during page navigation causing the URL to possibly exceed its maximum length, you can use the ty.presetFunctionalData API.

It is used to set the initialization page data of functional pages. Once set, it takes effect permanently unless actively cleared.

// Custom data
ty.presetFunctionalData({
	url: 'functional://mySettings/home',
    data: { name: 'pre' }
})
// Execute navigation
ty.navigateTo({ url: 'functional://mySettings/home'})

// Clear data
ty.presetFunctionalData({
  url: 'functional://mySettings/home',
  data: null
})

After presetting data, functional page instances use Page instances' this.getPresetData() to obtain data:

import { usePageInstance } from '@ray-js/ray';

export default Index() {
  const page = usePageInstance();
  const presetData = page.getPresetData(); // {name:'pre'}
  return <View>...</View>
}

#Notes

1. Not affected by app.tyss styles, functional pages have their own styling.
2. Light / Dark development mode follows the host configuration.
3. Returns of getApp, getCurrentPages interfaces can only access data within their own space.
4. Multi-language in functional pages will merge with the host mini program's multi-language, with priority host multi-language > functional page multi-language.
5. Real machine debugging requires App version >= 5.18. IDE version requires >= 0.7.1.
6. When configuring the function pages that a business mini-program depends on, there may be cases where the version number of a specified function page is specified:

{
  functionalPages: {
    settings: {
      // Load the specified version of the function page
      appid: "tycryc71qaug8at6yt",
    },
    settings: {
      // Loading the feature page of version 1.0.0
      appid: "tycryc71qaug8at6yt",
      version: "1.0.0"
    },
    settings: {
      // Find the appid through the entryCode and load the latest available functional page online. entryCode takes precedence over appid
      entryCode: "entryyvaqnocapvsl1",
      // The appid and version fields will be ignored at this time.
      appid: "tycryc71qaug8at6yt",
      version: "1.0.0"
    },
  },
}

The following situations or exceptions may be encountered in this scenario:

• Only specify appid: In this case, the latest available version of the function page will be loaded. If no available version exists, it will be impossible to jump to the function page, and the jump interface will throw an exception.
• Specify appid and version: In this case, the specified version of the function page will be loaded. If the version does not exist, it will be impossible to jump to the function page, and the jump interface will throw an exception.
• Specify entryCode: In this case, the appid and version fields will be ignored. The appid will be found through entryCode. If found, the latest available version of the function page will be loaded; if not found, it will be impossible to jump to the function page, and the jump interface will throw an exception.