UI Extensibility (UI Layer)#

Method 1: Different Layout via Subclass#

Subclass the framework’s view controller and override nibName to point at your own .xib. Default behavior is preserved; only the layout file changes.

final class MyFormViewController: FormViewController {
    override var nibName: String? {
        "MyFormLayout"      // refers to MyFormLayout.xib in the app bundle
    }
}

let registry = ViewControllerFactoryRegistry()
registry.register(modelType: FormModel.self) { uiModel in
    MyFormViewController(uiModel: uiModel)
}

Your .xib must wire up the same @IBOutlets the parent class expects. Inspect FormViewController’s outlets in the autodoc; any missing outlet crashes at view-load time.

Method 2: Subclass and Override Behavior#

Subclass to inject application state, override lifecycle hooks, or change how user input is processed. Call super on every override so the framework’s flow management still runs.

final class MyFormViewController: FormViewController {
    override func viewDidLoad() {
        super.viewDidLoad()                  // required
        applyFeatureFlagOverrides()
    }

    override func submitForm() {
        analytics.log("form_submitted")
        super.submitForm()                   // required — forwards to flow
    }

    private func applyFeatureFlagOverrides() { /* app-specific */ }
}

Register the subclass the same way as Method 1.

What it looks like. A SelectorViewController subclass can inject extra views on top of the framework’s standard selector layout. The screenshot below shows a custom subclass that adds an ad banner above the authenticator picker — the framework still drives the HAAPI flow and dispatches user-selected actions; only the rendered chrome is yours.

Method 2 — SelectorViewController subclass with an extra ad-banner UIView layered above the framework’s default selector. The selector buttons and flow dispatch are unchanged.

Method 3: Replace the View Controller Entirely#

Register a custom class conforming to HaapiUIViewController directly. You own the full lifecycle; the framework still drives the HAAPI flow underneath but does not provide any layout or behavior for you.

final class MyCompletelyCustomFormVC: UIViewController, HaapiUIViewController {
    let uiModel: FormModel
    init(uiModel: FormModel) {
        self.uiModel = uiModel
        super.init(nibName: nil, bundle: nil)
    }
    required init?(coder: NSCoder) { fatalError() }

    override func viewDidLoad() {
        super.viewDidLoad()
        // Build the UI from scratch reading uiModel
    }

    // Implement HaapiUIViewController's required methods so the
    // framework can deliver state updates and receive user actions.
}

let registry = ViewControllerFactoryRegistry()
registry.register(modelType: FormModel.self) { uiModel in
    MyCompletelyCustomFormVC(uiModel: uiModel)
}

haapiUIKitApplication = HaapiUIKitApplicationBuilder(
    haapiUIKitConfiguration: haapiUIKitConfiguration
)
.setViewControllerFactoryRegistry(registry)
.build()

What it looks like. A class conforming to HaapiUIViewController can render any UI you want. The screenshot below shows a fully custom login screen — branded header, custom field styling, custom button layout — replacing the framework’s default FormViewController. The framework still delivers the FormModel to your init(uiModel:), drives the underlying HAAPI flow, and receives user actions through the methods you implement.

Method 3 — the entire FormViewController swapped out for a HaapiUIViewController implementation. Visual design, layout, and field styling are owned by the host app; the HAAPI flow contract is preserved.

Customizing Data Mappings#

When the issue is what data reaches the view rather than how it’s rendered, register a DataMapper against the relevant input type. The framework converts HAAPI server responses into UIModel instances through a chain of mappers; your mapper can inject extra fields, transform existing fields, or return an app-specific subclass that your custom view reads:

let dataMapperRegistry = DataMapperRegistry()
dataMapperRegistry.register(modelType: FormModel.self) { input in
    var model = FormModel(from: input)
    model.extraField = FeatureFlags.formExtraField()
    return model
}

haapiUIKitApplication = HaapiUIKitApplicationBuilder(
    haapiUIKitConfiguration: haapiUIKitConfiguration
)
.setDataMapperRegistry(dataMapperRegistry)
.build()

Data-mapping customizations layer cleanly with view-class customizations — replace the mapping, then write a custom view that consumes the new fields. See the DataMappers reference in IdsvrHaapiUIKit/docs/ui_extensibility/ for the upstream detail.

Method 1: Different XML Layout via Subclass#

Subclass the framework’s fragment and override the layout-resource hook to point at your own R.layout.*. Default behavior is preserved; only the XML file changes.

class MyFormFragment : FormFragment() {
    override val layoutResource: Int = R.layout.my_form_layout

    companion object {
        fun newInstance(uiModel: FormModel) = MyFormFragment().apply {
            arguments = bundleOf(/* framework-required keys */)
        }
    }
}

// Wire the subclass into the fragment resolver
override val fragmentResolver: FragmentResolver =
    HaapiFlowFragmentResolver.Builder()
        .customize(FormModel::class.java, MyFormFragment::newInstance)
        .build()

Your custom layout must keep the IDs the parent fragment binds to (@+id/hui_form_username, etc.). Missing IDs crash at view-binding time.

Method 2: Subclass and Override Behavior#

Subclass to inject application state, override lifecycle hooks, or change how user input is processed. Call super on every override so the framework’s flow management still runs.

class MyFormFragment : FormFragment() {
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)  // required
        applyFeatureFlagOverrides()
    }

    override fun onSubmit() {
        analytics.log("form_submitted")
        super.onSubmit()                               // required — forwards to flow
    }

    private fun applyFeatureFlagOverrides() { /* app-specific */ }

    companion object {
        fun newInstance(uiModel: FormModel) = MyFormFragment().apply { /* ... */ }
    }
}

Register the subclass through HaapiFlowFragmentResolver.Builder the same way as Method 1.

Method 3: Replace the Fragment Entirely#

Provide a fragment that extends HaapiFlowFragment<FormModel> directly (not the framework’s FormFragment). You own the full lifecycle; the framework still drives the HAAPI flow underneath but does not provide any layout or behavior for you.

class MyCompletelyCustomFormFragment : HaapiFlowFragment<FormModel>() {
    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        // Inflate your custom view, bind to uiModel via the framework property
        return inflater.inflate(R.layout.my_custom_form_from_scratch, container, false)
    }

    // Implement HaapiFlowFragment's required hooks so the framework
    // can deliver state updates and receive user actions.

    companion object {
        fun newInstance(uiModel: FormModel) = MyCompletelyCustomFormFragment().apply { /* ... */ }
    }
}

override val fragmentResolver: FragmentResolver =
    HaapiFlowFragmentResolver.Builder()
        .customize(FormModel::class.java, MyCompletelyCustomFormFragment::newInstance)
        .build()

Customizing Data Mappings#

When the issue is what data reaches the view rather than how it’s rendered, provide a custom Representation mapper through the framework’s representation-mapping registry. The framework converts HAAPI server responses into UIModel instances through a chain of mappers; your mapper can inject extra fields, transform existing fields, or return an app-specific subclass that your custom view reads:

class CustomFormRepresentation : Representation<FormModel> {
    override fun map(serverResponse: ServerResponse): FormModel {
        val base = FormModel.from(serverResponse)
        return base.copy(extraField = FeatureFlags.formExtraField())
    }
}

override val representationMapper: RepresentationMapper =
    RepresentationMapper.Builder()
        .register(FormModel::class.java, CustomFormRepresentation())
        .build()

Data-mapping customizations layer cleanly with view-class customizations — replace the mapping, then write a custom fragment that consumes the new fields. See representation_type.md in the Android UI extensibility docs for the upstream detail.