Aloha

Aloha is a library for adding a simple welcome activity to your Android application. Customization is simple. You specify resource identifiers for each page and write a minimal amount of code.

Sample application

Use the link above to install the demo from the Play Store. The sample application source is also available on GitHub.

Usage

1. The Aloha library is available on JCenter. Add the dependency to your build.gradle file:

   dependencies {
       compile 'honuapps:aloha:0.9.0'
   }
   

2. Prepare your resources for each welcome page: image, header, content, and background color.
3. Create a WelcomeActivity that extends BaseWelcomeActivity.

4. Implement createPages() in WelcomeActivity. Create a PageDesriptor for each page:

   @Override
   public void createPages() {
      addPage(new PageDescriptor(R.string.welcome_header_0, R.string.welcome_content_0, R.drawable.welcome_image_0, R.color.welcome_color_0));
      addPage(new PageDescriptor(R.string.welcome_header_1, R.string.welcome_content_1, R.drawable.welcome_image_1, R.color.welcome_color_1));
      addPage(new PageDescriptor(R.string.welcome_header_2, R.string.welcome_content_2, R.drawable.welcome_image_2, R.color.welcome_color_2));
   }
   

5. Declare your WelcomeActivity in AndroidManifest.xml:

   <activity android:name=".WelcomeActivity" />
   

6. Modify your MainActivity to start the WelcomeActivity:

   if (WelcomeHelper.isWelcomeRequired(this)) {
       startActivity(new Intent(MainActivity.this, WelcomeActivity.class));
       overridePendingTransition(android.R.anim.fade_in, android.R.anim.fade_out);
   }
   

Resource Identifiers

Specify resource identifiers to customize each welcome page:

WelcomeActivity

The versionCode of the client app can be used to show the welcome activity on app install or upgrade. Use this helper method to compare versions and update a SharedPreference when 'true'.

WelcomeHelper.isWelcomeRequired(this)

PageTransformer

The PageTansformer provides a cross-fading transition between page slides of the view pager. The text slides with the page and gradually fades out. The image and background color also fade out as the new page increases in opacity. When you scroll off the last welcome page, the main activity is revealed.

Testing

During development you may find it helpful to clear the SharedPreference to force the WelcomeActivity to show each time you run your app.

WelcomeHelper.clearLastRunVersionCode(this)

Recommendations

Follow these suggestions for the best results:

• Use reasonably sized image resources. The layouts use centerInside for the ImageView scale type. This means your image will scale down only if necessary and never be scaled up. A 400x400 image works well with most devices.
• When selecting background colors keep in mind that the default theme is light on dark.

• Use Toolbar in your MainActivity layout and disable the window title in the style:

  <style name="AppTheme.Base" parent="Theme.AppCompat.Light.NoActionBar">
      <item name="android:windowNoTitle">true</item>
  </style>
  

Report Issues

Please use GitHub to report issues and request enhancements.

• Aloha library: report issue
• Aloha demo: report issue

Acknowledgments

The sample application uses images under CC0 license.

License

License information LICENSE