XPage Android Framework

XPage is a Fragment-based page framework for Android that provides several key capabilities:

• Configuration Options: Supports static configuration via corepage.json in assets, dynamic configuration in the Application class, or automatic configuration using the @Page annotation.
• Navigation & Animation: Supports 4 default Fragment transition animations and easy navigation between Fragments and Activities.
• Data Management: Supports parameter passing between Fragments, property saving, and data interaction between Fragments, Activities, and Fragments.
• Lifecycle & UI: Supports Fragment lifecycle methods like onKeyDown and onFragmentResult. It also supports automatic Navigation Bar setup via annotations and custom TitleBar themes.
• Customization: Allows for custom Fragment page containers, custom Activity containers, and custom Fragment page information.
• Compatibility: Fully compatible with Kotlin and AndroidX.

XPage provides the following capabilities for Android developers:

• Configuration Methods:
  • Static configuration via corepage.json in the assets folder.
  • Dynamic configuration within the Application class.
  • Automatic configuration using the @Page annotation.
  • Support for custom Fragment page information.
• Navigation & UI:
  • 4 default Fragment transition animations.
  • Support for Fragment-to-Fragment and Fragment-to-Activity navigation.
  • Automatic navigation bar setup and configuration via annotations.
  • Customizable TitleBar global theme attributes.
  • Support for custom Fragment and Activity containers.
• Data & Lifecycle:
  • Parameter passing between Fragment pages.
  • Fragment attribute saving.
  • Data interaction between Fragments, Activities, and Fragments.
  • Support for onKeyDown and onFragmentResult lifecycle events.
• Compatibility:
  • Fully compatible with Kotlin and AndroidX.

XPage supports two ways to register pages:

1. Static Registration (via assets)

Create a corepage.json file in your assets folder. Define an array of page objects containing name, classPath, and optional params.

2. Dynamic Registration (via Application) [Recommended]

Automatic Registration: If you use the @Page annotation on your XPageFragment classes, XPage automatically generates a [moduleName]PageConfig class. Use its getPages() method during initialization.

Manual Registration: Implement a custom PageConfiguration and override registerPages to return a list of PageInfo objects.

// assets/corepage.json
[
  {
    "name": "Test Page 1",
    "classPath": "com.xuexiang.xpagedemo.fragment.TestFragment1",
    "params": ""
  }
]

// Automatic Registration in Application
PageConfig.getInstance()
    .setPageConfiguration(new AutoPageConfiguration())
    .debug("PageLog")
    .setContainActivityClazz(XPageActivity.class)
    .init(this);

// Manual Registration in Application
PageConfig.getInstance()
    .setPageConfiguration(new PageConfiguration() {
        @Override
        public List<PageInfo> registerPages(Context context) {
            List<PageInfo> pageInfos = new ArrayList<>();
            addPageInfoAndSubPages(pageInfos, MainFragment.class);
            pageInfos.add(PageConfig.getPageInfo(DateReceiveFragment.class));
            return pageInfos;
        }
    })
    .debug("PageLog")
    .init(this);

To use a custom layout as a container for fragments within an XPageActivity:

1. Layout Requirement: Your custom layout must contain a FrameLayout with the ID @id/fragment_container.
2. Override Root View: In your XPageActivity, override getCustomRootView() to inflate your custom layout.
3. Switch Pages: Use changePage(String pageName, Bundle params, CoreAnim anim) to switch fragments within the custom container.
4. Access Fragments: Use getPage(Class<T> clazz) to retrieve a specific fragment instance to access its data.

Note: When switching fragments via changePage, the fragments do not go through onResume and onPause. Use onHiddenChanged instead to handle visibility changes.

<!-- Custom layout must include this ID -->
<FrameLayout
    android:id="@id/fragment_container"
    android:layout_width="match_parent"
    android:layout_height="400dp">
</FrameLayout>

// In XPageActivity
@Override
protected View getCustomRootView() {
    binding = ActivityComplexBinding.inflate(getLayoutInflater());
    return binding.getRoot();
}

// Switching pages
changePage(TestFragment.PAGE_NAME, null, CoreAnim.none);

// Getting fragment instance
TabAFragment tabAFragment = getPage(TabAFragment.class);
if (tabAFragment != null) {
    String data = tabAFragment.getData();
}

To use XPage in your Android project, follow these steps:

1. Add JitPack repository to your project's root build.gradle:

2. Add dependencies to your app-level build.gradle. Choose the version compatible with your project (AndroidX or Support).

3. Register moduleName in defaultConfig to avoid the default app module name. This is required for annotation processing to work correctly across multiple modules.

Note for Kotlin users: Use kotlin-kapt plugin and kapt configuration instead of annotationProcessor.

// 1. Root build.gradle
allprojects {
     repositories {
        ...
        maven { url "https://jitpack.io" }
    }
}

// 2. App build.gradle (AndroidX version)
dependencies {
  implementation 'com.github.xuexiangjys.XPage:xpage-lib:3.4.0'
  annotationProcessor 'com.github.xuexiangjys.XPage:xpage-compiler:3.4.0'
}

// 2. App build.gradle (Kotlin version)
apply plugin: 'kotlin-kapt'

dependencies {
  implementation 'com.github.xuexiangjys.XPage:xpage-lib:3.4.0'
  kapt 'com.github.xuexiangjys.XPage:xpage-compiler:3.4.0'
}

// 3. Register moduleName
defaultConfig {
    ... 
    javaCompileOptions {
        annotationProcessorOptions {
            arguments = [ moduleName : project.getName() ]
        }
    }
}

You can customize the default TitleBar appearance using XPageTitleBarStyle in your application theme. Available customization options include background image, background color, immersion support, navigation back icon, height, and text sizes.

<!-- Base application theme -->
<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    <item name="colorPrimary">@color/xpage_default_actionbar_color</item>
    <item name="xpage_actionbar_background">@null</item>
    <item name="xpage_actionbar_color">@color/xpage_default_actionbar_color</item>
    <item name="xpage_actionbar_immersive">false</item>
    <item name="xpage_actionbar_navigation_back">@drawable/xpage_ic_navigation_back_white</item>
    <item name="xpage_actionbar_height">60dp</item>
    <item name="xpage_actionbar_title_text_size">21sp</item>
    
    <!-- Apply custom style -->
    <item name="XPageTitleBarStyle">@style/XPageTitleBar.Custom</item>
</style>

<style name="XPageTitleBar.Custom">
    <item name="tb_immersive">false</item>
    <item name="tb_centerGravity">center</item>
</style>