##SlidingTutorial

Cleveroad introduces Sliding Tutorial Library for Android

Hey guys, hope you haven’t started developing a tutorial for your Android app yet, as we have already completed a part of your job. Don’t worry, we act from good motives only. Our aim is to help you create a sliding tutorial in a fast and simple manner. So we’ve done some work and voila!. A simple Android Sliding Tutorial library is at your service.

Also you can watch the animation of the Sliding Tutorial for Android on YouTube in HD quality.

The invention is going to ease the problem of structural design but not to limit a stretch of your imagination at the same time. We took care of the suitability aspect. So, your app is not going to look alien among other Android elements.

Read our Case Study: Sliding tutorial for Android by Cleveroad to make sure that you don’t miss a detail:

Applied parallax effects will make your product presentation look like Google apps tutorial.

All you need to do is:
1. Create background designs for each screen of your tutorial (assistance with mobile design)
2. Create icons for each screen of your tutorial
3. Follow the instructions below

Using

First, add gradle dependency into your build.gradle:

dependencies {
    compile 'com.cleveroad:slidingtutorial:1.0.0'
}

There are two common variants of using library: via TutorialPageProvider and via TutorialPageOptionsProvider.

Via TutorialPageProvider

You have to create page fragments where each fragment must extend from PageFragment, override PageFragment#getLayoutResId() and PageFragment#getTransformItems(). Also you have to create your layout xml file with images.

public class FirstCustomPageFragment extends PageFragment {

    @Override
    protected int getLayoutResId() {
        return R.layout.fragment_page_first;
    }

    @Override
    protected TransformItem[] provideTransformItems() {
        return new TransformItem[] {
                // TransformItem.create(view for transform, moving direction, shift coefficient)
                TransformItem.create(R.id.ivFirstImage, Direction.LEFT_TO_RIGHT, 0.2f),
                TransformItem.create(R.id.ivSecondImage, Direction.RIGHT_TO_LEFT, 0.06f),
                TransformItem.create(R.id.ivThirdImage, Direction.LEFT_TO_RIGHT, 0.08f),
                TransformItem.create(R.id.ivFourthImage, Direction.RIGHT_TO_LEFT, 0.1f),
                TransformItem.create(R.id.ivFifthImage, Direction.RIGHT_TO_LEFT, 0.03f),
                TransformItem.create(R.id.ivSixthImage, Direction.RIGHT_TO_LEFT, 0.09f),
                TransformItem.create(R.id.ivSeventhImage, Direction.RIGHT_TO_LEFT, 0.14f),
                TransformItem.create(R.id.ivEighthImage, Direction.RIGHT_TO_LEFT, 0.07f)
        };
    }
}

Set up TutorialPageProvider instance to TutorialOptions.Builder#setTutorialPageProvider(TutorialPageProvider).

public class CustomTutorialFragment extends TutorialFragment {

    private static final int TOTAL_PAGES = 3;

    private final TutorialPageProvider mTutorialPageProvider = new TutorialPageProvider() {
        @NonNull
        @Override
        public PageFragment providePage(int position) {
            switch (position) {
                case 0:
                    return new FirstCustomPageFragment();
                case 1:
                    return new SecondCustomPageFragment();
                case 2:
                    return new ThirdCustomPageFragment();
                default:
                    throw new IllegalArgumentException("Unknown position: " + position);
            }
        }
    };

    private int[] pagesColors = new int[] { Color.RED, Color.DKGRAY, Color.BLUE };

    @Override
    protected TutorialOptions provideTutorialOptions() {
        return TutorialOptions.newBuilder(getContext())
                .setPagesColors(pagesColors)
                .setPagesCount(TOTAL_PAGES)
                .setTutorialPageProvider(mTutorialPageProvider)
                .build();
    }
}

Via TutorialPageProvider

Or you can create TutorialPageOptionsProvider and set it up to TutorialOptions.Builder#setTutorialPageProvider(TutorialPageOptionsProvider). It will automatically provide PageFragment instance with specified PageOptions configuration.

public class CustomTutorialFragment extends TutorialFragment {

    private static final int TOTAL_PAGES = 3;

    private final TutorialPageOptionsProvider mTutorialPageOptionsProvider = new TutorialPageOptionsProvider() {
        @NonNull
        @Override
        public PageOptions provide(int position) {
            @LayoutRes int pageLayoutResId;
            TransformItem[] tutorialItems;
            switch (position) {
                case 0: {
                    pageLayoutResId = R.layout.fragment_page_first;
                    tutorialItems = new TransformItem[]{
                            TransformItem.create(R.id.ivFirstImage, Direction.LEFT_TO_RIGHT, 0.2f),
                            TransformItem.create(R.id.ivSecondImage, Direction.RIGHT_TO_LEFT, 0.06f),
                            TransformItem.create(R.id.ivThirdImage, Direction.LEFT_TO_RIGHT, 0.08f),
                            TransformItem.create(R.id.ivFourthImage, Direction.RIGHT_TO_LEFT, 0.1f),
                            TransformItem.create(R.id.ivFifthImage, Direction.RIGHT_TO_LEFT, 0.03f),
                            TransformItem.create(R.id.ivSixthImage, Direction.RIGHT_TO_LEFT, 0.09f),
                            TransformItem.create(R.id.ivSeventhImage, Direction.RIGHT_TO_LEFT, 0.14f),
                            TransformItem.create(R.id.ivEighthImage, Direction.RIGHT_TO_LEFT, 0.07f)
                    };
                    break;
                }
                case 1: {
                    pageLayoutResId = R.layout.fragment_page_second;
                    tutorialItems = new TransformItem[]{
                            TransformItem.create(R.id.ivFirstImage, Direction.RIGHT_TO_LEFT, 0.2f),
                            TransformItem.create(R.id.ivSecondImage, Direction.LEFT_TO_RIGHT, 0.06f),
                            TransformItem.create(R.id.ivThirdImage, Direction.RIGHT_TO_LEFT, 0.08f),
                            TransformItem.create(R.id.ivFourthImage, Direction.LEFT_TO_RIGHT, 0.1f),
                            TransformItem.create(R.id.ivFifthImage, Direction.LEFT_TO_RIGHT, 0.03f),
                            TransformItem.create(R.id.ivSixthImage, Direction.LEFT_TO_RIGHT, 0.09f),
                            TransformItem.create(R.id.ivSeventhImage, Direction.LEFT_TO_RIGHT, 0.14f),
                            TransformItem.create(R.id.ivEighthImage, Direction.LEFT_TO_RIGHT, 0.07f)
                    };
                    break;
                }
                case 2: {
                    pageLayoutResId = R.layout.fragment_page_third;
                    tutorialItems = new TransformItem[]{
                            TransformItem.create(R.id.ivFirstImage, Direction.RIGHT_TO_LEFT, 0.2f),
                            TransformItem.create(R.id.ivSecondImage, Direction.LEFT_TO_RIGHT, 0.06f),
                            TransformItem.create(R.id.ivThirdImage, Direction.RIGHT_TO_LEFT, 0.08f),
                            TransformItem.create(R.id.ivFourthImage, Direction.LEFT_TO_RIGHT, 0.1f),
                            TransformItem.create(R.id.ivFifthImage, Direction.LEFT_TO_RIGHT, 0.03f),
                            TransformItem.create(R.id.ivSixthImage, Direction.LEFT_TO_RIGHT, 0.09f),
                            TransformItem.create(R.id.ivSeventhImage, Direction.LEFT_TO_RIGHT, 0.14f)
                    };
                    break;
                }
                default: {
                    throw new IllegalStateException("Invalid position");
                }
            }

            return PageOptions.create(pageLayoutResId, position, tutorialItems);
        }
    };

    @Override
    protected TutorialOptions provideTutorialOptions() {
        return TutorialOptions.newBuilder(getContext())
                .setPagesCount(TOTAL_PAGES)
                .setTutorialPageProvider(mTutorialPageOptionsProvider)
                .build();
    }
}

Customization

Set up skip button click listener

You have to implement OnClickListener interface and provide it to TutorialOptions.Builder#setOnSkipClickListener(OnClickListener). Example:

public class CustomTutorialFragment extends TutorialFragment {
    @Override
    protected TutorialOptions provideTutorialOptions() {
        return TutorialOptions.newBuilder(getContext())
                .setOnSkipClickListener(new View.OnClickListener() {
                    @Override
                    public void onClick(View v) {
                        Toast.makeText(getContext(), "Skip button clicked", Toast.LENGTH_SHORT).show();
                    }
                })
                // set up other configuration ...
                .build();
    }
}

Set up pages colors

Just provide array of color values to TutorialOptions.Builder#setPagesColors(int array). Array with colors must have length equal to pages size.

public class CustomTutorialFragment extends TutorialFragment {

    private static final int TOTAL_PAGES = 3;

    private int[] pagesColors = new int[] { Color.RED, Color.BLUE, Color.DKGRAY };

    @Override
    protected TutorialOptions provideTutorialOptions() {
        return TutorialOptions.newBuilder(getContext())
                .setPagesCount(TOTAL_PAGES)
                .setPagesColors(pagesColors)
                // set up other configuration ...
                .build();
    }
}

Infinite scroll

To loop tutorial pages you have set TutorialOptions.Builder#setUseAutoRemoveTutorialFragment(boolean) to Boolean#TRUE.

Auto remove TutorialFragment - scroll from last tutorial page to your content

If you want to provide smooth transition from last tutorial page to content - just set up TutorialOptions.Builder#setUseAutoRemoveTutorialFragment(boolean) to Boolean#TRUE.

Indicator view customization

There is IndicatorOptions class for configuration indicator view. Here's example:

public class CustomTutorialFragment extends TutorialFragment {
    @Override
    protected TutorialOptions provideTutorialOptions() {
        return TutorialOptions.newBuilder(getContext())
                .setIndicatorOptions(IndicatorOptions.newBuilder(getContext())
                        .setElementSizeRes(R.dimen.indicator_size)
                        .setElementSpacingRes(R.dimen.indicator_spacing)
                        .setElementColorRes(android.R.color.darker_gray)
                        .setSelectedElementColor(android.R.color.white)
                        .setRenderer(BitmapRenderer.create(getContext()))
                        .build())
                .build();
    }
}

As you can see, you can specify element size, element spacing (aka padding), element color, selected element color, and implementation of Renderer interface. There are 2 default implementation inside Renderer.Factory:

• Renderer.Factory#newCircleRenderer()
• Renderer.Factory#newSquareRenderer()

Also in sample module there are two implementaions:

• DrawableRenderer
• RhombusRenderer

Add OnTutorialPageChangeListener

You can listen change page listener - just implement TutorialFragment.OnTutorialPageChangeListener and add listener via TutorialFragment#addOnTutorialPageChangeListener(OnTutorialPageChangeListener). To remove listener use TutorialFragment#removeOnTutorialPageChangeListener(OnTutorialPageChangeListener).

public class CustomTutorialFragment extends TutorialFragment
        implements TutorialFragment.OnTutorialPageChangeListener {

    private static final String TAG = "CustomTutorialFragment";

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        addOnTutorialPageChangeListener(this);
    }

    @Override
    public void onPageChanged(int position) {
        Log.i(TAG, "onPageChanged: position = " + position);
        if (position == TutorialFragment.EMPTY_FRAGMENT_POSITION) {
            Log.i(TAG, "onPageChanged: Empty fragment is visible");
        }
    }

}

Changelog

Version	Changes
v.1.0.0	Library fully refactored. See full 1.0.0 Changelog
v.0.9.5	Added getters for views. Possible fix for manifest merging issues
v.0.9.4	Renamed all attributes; all resources marked as private
v.0.9.3	Fixed issue with wrong page showed at startup if pages count not equals 3
v.0.9.2	Added onSkipButtonClicked method and SimplePagerFragment
v.0.9.1	Added infinite scroll behavior
v.0.9	First public release

1.0.0 Changelog

• Renamed PresentationPagerFragment to TutorialFragment.
• Made PageFragment not abstract with default implementaion for PageFragment#getLayoutResId() and PageFragment#getTransformItems().
• Removed capability to create new instance of TransformItem via new. Added fabric static method TransformItem#create(int,Direction,float).
• Created [OnTutorialPageChangeListener] to listen change page events.
• Use [TutorialFragment#addOnTutorialPageChangeListener()] and [TutorialFragment#removeOnTutorialPageChangeListener()] to add/remove listener.
• Created TutorialOptions to configure TutorialFragment.
• Created TutorialPageOptionsProvider and PageOptions to provide and configure PageFragment instances.
• Created TutorialPageProvider to provide PageFragment instances.
• Removed CirclePageIndicator.
• Created TutorialPageIndicator view.
• Created IndicatorOptions to configure TutorialPageIndicator view.
• Created Renderer interface that responds for drawing single indicator item. There are 2 default implementaion: Renderer.Factory#newCircleRenderer() and Renderer.Factory#newSquareRenderer().

Migrations from v.0.9.5 to v.1.0.0

1. You must change creation TransformItem from new TransformItem(R.id.ivFirstImage, true, 20) to TransformItem.create(R.id.ivFirstImage, Direction.LEFT_TO_RIGHT, 0.2f), where 2-nd parameter now is Direction of view translation and 3-rd parameter is shiftCoefficient.
2. Your fragment with tutorial must extend TutorialFragment instead of PresentationPagerFragment.
3. In your TutorialFragment successor fragment must implement #provideTutorialOptions() method that returns TutorialOptions instance.
4. In TutorialOptions.Builder#setTutorialPageProvider(TutorialPageProvider)* you must specify TutorialPageProvider instance. For example:

private final TutorialPageProvider mTutorialPageProvider = new TutorialPageProvider() {
        @NonNull
        @Override
        public PageFragment providePage(int position) {
            position %= ACTUAL_PAGES_COUNT;
            switch (position) {
                case 0:
                    return new FirstCustomPageFragment();
                case 1:
                    return new SecondCustomPageFragment();
                case 2:
                    return new ThirdCustomPageFragment();
                default:
                    throw new IllegalArgumentException("Unknown position: " + position);
            }
        }
    };

Migrations from v.0.9.3 to v.0.9.4

• All resources marked as private. Make sure you're not using any resource (strings, dimens, etc) from this library.
• All attributes were renamed, prefix st_ added. Add this prefix to any custom XML attribute you used. Example:

    <com.cleveroad.slidingtutorial.CirclePageIndicator
        android:id="@+id/indicator"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_gravity="center"
        app:st_fillColor="@android:color/white"
        app:st_pageColor="@android:color/secondary_text_light_nodisable"
        app:st_radius="4dp"
        app:st_strokeColor="#00000000"
        app:st_strokeWidth="0dp"/>

Migrations from v.0.9 to v.0.9.1

####CirclePageIndicator This class is final now. Make sure you're not extending from it.

####LayersHolder This class is package-local now. Make sure you're not using it.

####PageFragment getRootResId() and getBackgroundColorResId() methods are deprecated. You can remove them now. To specify page's color use PresentationPagerFragment.getPageColor(int) method.

####PresentationPagerFragment getPageFragments() method is deprecated. You can remove it now. Use getPagesCount() and getPage(int) methods instead.

Added isInfinityScrollEnabled() method. Override it and return true to enable this feature.

NOTE: make sure you're returning new fragment instance when displaying tutorial with infinite scroll enabled.

Support

If you have any questions regarding the use of this tutorial, please contact us for support at info@cleveroad.com (email subject: «Sliding android app tutorial. Support request.»)
or
Use our contacts:
Cleveroad.com
Facebook account
Twitter account
Google+ account

License

    The MIT License (MIT)

    Copyright (c) 2015-2016 Cleveroad

    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.