Customize multi-level selections

The super app can customize the cascading multi-level selector within mini programs to ensure a consistent user interface. The multi-level/cascade selector appears when mini programs call the my.multiLevelSelect JSAPI to enable users to select multiple levels of associated data, such as province, city and district.

Default user interface

The following figure shows the UI examples of the default multi-level selector:

Before you begin

Ensure that the integrated iOS IAPMiniProgram SDK is version 2.65.0 or later. For more information, see SDK release notes.

Procedure

To customize the cascading multi-level selector, take the following steps:

Step 1: Implement the GRVMultiLevelSelectDelegate protocol

Create a class that implements the GRVMultiLevelSelectDelegate protocol. Within the class, override the showMultilevelPicker function. Refer to the following code for a sample implementation.

For more information about the interface and its methods, refer to the GRVMultiLevelSelectDelegate protocol.

class DemoMultiLevelSelectImpl: NSObject, GRVMultiLevelSelectDelegate {
    func showMultilevelPicker(with param: GRVMultiLevelSelectParam, finishHandler: @escaping (IndexPath) -> Void, cancelHandler: @escaping () -> Void) {
        // customize the multi-level UI selector/picker 
    }

Step 2: Configure multiLevelSelectDelegate

After initialize the SDK, configure the multiLevelSelectDelegate to register the GRVMultiLevelSelectDelegate protocol.

Refer to the following code for a sample configuration:

let extensionDelegate = GRVExtensionDelegate()
extensionDelegate.uiProvider.multiLevelSelectDelegate = DemoMultiLevelSelectImpl()

Protocol

GRVMultiLevelSelectDelegate protocol

The GRVMultiLevelSelectDelegate protocol defines functions for the super app to customize a multi-level picker/selector, which the SDK then calls to render the customized cascading selection UI. Refer to the following code for the interface definition:

@protocol GRVMultiLevelSelectDelegate <NSObject>

/// Display a custom cascading selector.
/// - Parameters:
///   - param: Parameter
///   - finishHandler: Completion handler (receives the index of each selected level as NSIndexPath)
///   - cancelHandler: Cancel handler
- (void)showMultilevelPickerWithParam:(GRVMultiLevelSelectParam *)param
                        finishHandler:(void(^)(NSIndexPath *selectedIndexPath))finishHandler
                        cancelHandler:(void(^)(void))cancelHandler;

@end

The following table lists the details of the defined functions:

showMultilevelPickerWithParam:finishHandler:cancelHandler: function

This function has the following input parameters whose values are passed by the SDK.

GRVMultiLevelSelectParam

Refer to the following code:

@class GRVCascadeSelectNode;
@interface GRVMultiLevelSelectParam : NSObject

/// Current view controller.
@property (nonatomic, weak, nullable) UIViewController *currentViewController;

/// Title.
@property (nonatomic, copy, nullable, readonly) NSString *title;

/// Selection data list (Note: Data limit less than 200KB).
@property (nonatomic, copy, readonly) NSArray<GRVCascadeSelectNode *> *list;


@end


/* ============== GRVCascadeSelectNode ================== */
@interface GRVCascadeSelectNode : NSObject

/// Item name.
@property (nonatomic, copy, readonly) NSString *name;

/// Child item list, the structure of subList is the same as list, supporting multi-level nesting.
@property (nonatomic, copy, nullable, readonly) NSArray<GRVCascadeSelectNode *> *subList;

@end

GRVCascadeSelectNode

finishHandler function

This function has the following parameters: