Use Material Design

Configure the project

About this task

Directly importing AppCompat libraries into a project causes "resource not found" errors at compile-time because of the structure of the mPaaS framework. To solve this, mPaaS provides a custom AppCompat library. To use this library, you must first configure your Portal and Bundle projects.

The mPaaS AppCompat library is based on the native Android 23 version and includes the following components:

• appcompat

• animated-vector-drawable

• cardview

• design

• recyclerview

• support-vector-drawable

This custom library is based on the native Android 23 version. It is identical to the native library but resolves the compilation issues that occur when you import the native library.

Resource usage scenarios include using resources from another Bundle, providing resources to other components, and using custom resources in AndroidManifest. Because of the structure of the mPaaS framework, you must be aware of the considerations for each scenario. For more information, see Use resources.

Procedure

1. Configure the Portal project.

   Before you call the mPaaS AppCompat library, configure the Portal project as follows:

   1. Update the Alipay Plugin for Gradle to the following version:

      classpath 'com.alipay.android:android-gradle-plugin: 3.0.0.9.13'

   2. Remove the original AppCompat library dependency from the Gradle script.

   3. Add the following AppCompat dependencies to the Gradle script:

      bundle 'com.mpaas.android.res.base:mpaas-baseresjar:1.0.0.180626203034@jar'
      manifest 'com.mpaas.android.res.base:mpaas-baseresjar:1.0.0.180626203034:AndroidManifest@xml'

   4. After completing the configuration, configure the Bundle project to call the AppCompat component and sync the Portal project.

2. Configure the Bundle project.

   1. In the Bundle project where you want to use AppCompat components, change the Alipay Plugin for Gradle to the following version:

      classpath 'com.alipay.android:android-gradle-plugin: 3.0.0.9.13'

   2. Add dependencies for the sub-components you require. The following example shows how to add the recyclerview component:

      provided 'com.mpaas.android.res.base:mpaas-baseresjar:1.0.0.180626203034:recyclerview@jar'

Use resources

Common Material Design resources include strings, colors, and styles. Resource usage includes the following scenarios:

• Check for duplicate Package IDs

• Use resources from another Bundle

• Provide resources to other components

• Use custom resources in AndroidManifest

Check for duplicate Package IDs

If you encounter a "resource not found" error when using resources as described in this topic, check for duplicate Package IDs. The Package ID is defined in build.gradle. Its value affects the generated resource ID. Duplicate Package IDs cause "resource not found" errors.

You can check for duplicate Package IDs in one of two ways:

Option 1: Automatic detection with a Gradle task

Prerequisites

The version of android-gradle-plugin must be 3.0.0.9.13 or later.

classpath 'com.alipay.android:android-gradle-plugin: 3.0.0.9.13'

Steps

1. In the root directory of the Portal project, run the appropriate command:

   • On Windows: Run gradlew.bat checkBundleIds.

   • On other operating systems: Run gradlew checkBundleIds.

2. Check the output:

   • If the output contains No duplicate bundle ids found, there are no duplicate Package IDs.

   • If the output contains There are duplicate bundle ids, duplicate Package IDs exist. Use the output to identify the duplicates.

Option 2: Manual detection

Manual detection works in all cases. Follow these steps:

1. In the Portal project, open the bundles.csv text file.

   

2. Sort the PackageId column and check for duplicates. After you ensure that no duplicate Package IDs exist, recompile the project.

Use resources from another Bundle

Example scenario

Using resources from mpaas-baseresjar is an example of this scenario. When you use resources from another Bundle, you must add the resource's namespace. The namespace is the applicationID of the Bundle that contains the resource. When you build a release package, an error such as the one shown in the following image may occur:

Solution

Configure lintOptions in build.gradle as shown in the following image.

You must add the namespace as a prefix whenever you reference a resource from that Bundle. This includes references in layouts and custom styles. Otherwise, a "resource not found" compilation error occurs.

Code example: Reference in a layout

The following code shows an example of how to reference a resource from another Bundle in a layout:

<?xml version="1.0" encoding="utf-8"?>
<android.support.design.widget.CoordinatorLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res/com.mpaas.android.res.base"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:fitsSystemWindows="true">

    <android.support.design.widget.AppBarLayout
        android:id="@+id/app_bar_scrolling"
        android:layout_width="match_parent"
        android:layout_height="@dimen/app_bar_height_image_view"
        android:fitsSystemWindows="true"
        android:theme="@style/AppTheme.AppBarOverlay"
        android:background="@color/blue">

        <android.support.design.widget.CollapsingToolbarLayout
            android:id="@+id/collapsing_toolbar_layout"
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            android:fitsSystemWindows="true"
            app:contentScrim="?com.mpaas.android.res.base:attr/colorPrimary"
            app:layout_scrollFlags="scroll|exitUntilCollapsed">

            <ImageView
                android:id="@+id/image_scrolling_top"
                android:layout_width="match_parent"
                android:layout_height="match_parent"
                android:fitsSystemWindows="true"
                android:scaleType="fitXY"
                android:src="@drawable/material_design_3"
                app:layout_collapseMode="parallax" />

            <android.support.v7.widget.Toolbar
                android:id="@+id/toolbar"
                android:layout_width="match_parent"
                android:layout_height="?com.mpaas.android.res.base:attr/actionBarSize"
                app:layout_collapseMode="pin"
                app:popupTheme="@style/AppTheme.PopupOverlay" />

        </android.support.design.widget.CollapsingToolbarLayout>
    </android.support.design.widget.AppBarLayout>

    <android.support.design.widget.FloatingActionButton
        android:id="@+id/fab_scrolling"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_margin="@dimen/big_activity_fab_margin"
        android:src="@drawable/ic_share_white_24dp"
        app:layout_anchor="@id/app_bar_scrolling"
        app:layout_anchorGravity="bottom|end" />

    <include layout="@layout/content_scrolling" />

</android.support.design.widget.CoordinatorLayout>

Code example: Reference in a custom style

The following code shows an example of how to use a resource from another Bundle in a custom style:

    <style name="AppTheme" parent="@com.mpaas.android.res.base:style/Theme.AppCompat.NoActionBar">
        <!-- Customize your theme here. -->
        <item name="com.mpaas.android.res.base:colorPrimary">@color/colorPrimary</item>
        <item name="com.mpaas.android.res.base:colorPrimaryDark">@color/colorPrimaryDark</item>
        <item name="com.mpaas.android.res.base:colorAccent">@color/colorAccent</item>
    </style>

Provide resources to other components

1. Configure the Portal project. In the Portal project, import the resource Bundle information:

   // Import the bundle that provides resources
   bundle "com.mpaas.demo.materialdesign:materialdesign-build:1.0-SNAPSHOT:raw@jar"
   manifest "com.mpaas.demo.materialdesign:materialdesign-build:1.0-SNAPSHOT:AndroidManifest@xml"
   // To find the resources at compile-time, you must also provide the JAR package of the bundle
   provided 'com.mpaas.demo.materialdesign:materialdesign-build:1.0-SNAPSHOT:raw@jar'

2. Define resources. Follow these steps to define resources so they can be referenced by other Bundles or the Portal project:

   1. Define the IDs of the resources that you want to provide in public.xml. This makes the resource IDs static, which is a standard Android feature. You can copy the resource ID values from R.java. The following is an example:

      <?xml version="1.0" encoding="utf-8"?>
      <resources>
       <public name="AppTheme" id="0x1f030000" type="style" />
       <public name="AppTheme.AppBarOverlay" id="0x1f030001" type="style" />
       <public name="AppTheme.NoActionBar" id="0x1f030002" type="style" />
       <public name="AppTheme.NoActionBar.StatusBar" id="0x1f030003" type="style" />
       <public name="AppTheme.PopupOverlay" id="0x1f030004" type="style" />
       <public name="DialogFullscreen" id="0x1f030005" type="style" />
       <public name="DialogFullscreenWithTitle" id="0x1f030006" type="style" />
      
       <public name="title_activity_login" id="0x1f0c0081" type="string"/>
       <public name="title_activity_recycler_view" id="0x1f0c0082" type="string"/>
       <public name="title_activity_share_view" id="0x1f0c0085" type="string"/>
       <public name="title_activity_scrolling" id="0x1f0c0083" type="string"/>
       <public name="title_activity_settings" id="0x1f0c0084" type="string"/>
       <public name="title_activity_about" id="0x1f0c007f" type="string"/>
       <public name="activity_donate" id="0x1f0c000e" type="string" />
       <public name="activity_my_apps" id="0x1f0c000f" type="string"/>
      
      </resources>

   2. When another component uses the resource, add the package name as a prefix. For more information, see Use resources from another Bundle.

Use custom resources in AndroidManifest

If you define a theme in the AndroidManifest file of the Bundle project, as shown in the following code:

<activity
            android:name=".activity.MainActivity"
            android:launchMode="singleTop"
            android:theme="@com.mpaas.demo.materialdesign:style/AppTheme.NoActionBar"
            android:windowSoftInputMode="stateHidden|stateUnchanged">
</activity>

You must:

• In the main project path of the Portal project, create a res_slinks file. Add the Bundle name to the res_slinks file, with each name on a new line.

• Also, remove the manifest dependency for that Bundle in build.gradle, as shown in the following code:

  manifest 'com.mpaas.demo.materialdesign:materialdesign-build:1.0.0:AndroidManifest@xml'