search

DMCApps / NavigationFragment

The purpose of this manager is to work with the ViewPager, Tabs and Navigation drawer to handle a single stack flow of fragments on the screen. It makes use of a main Fragment as a container and presents and hides fragments within it as children.
MIT License
28 stars 8 forks source link

readme

Navigation Manager Fragment

Slack

Author

Daniel Carmo, dcarmo@alumni.uoguelph.ca

Adding the library to your android studio project

In your app build.gradle file add the following to your dependencies. Project only available on jCenter repository.

compile 'com.github.dmcapps:navigation-fragment:2.0.2-alpha'

Current Version

2.0.2-alpha

This version is an alpha. Please send any feedback on the Issue Tracker

Migration

From 1.0.0 to 2.0.0

MAJOR CHANGE:

The package has been changed from

com.dmcapps.navigationfragment

to

com.github.dmcapps.navigationfragment

I appologize for the inconvenience but it was necessary to get this into maven and out to more possible users.

In order to ease future development. The update to version 2.0.0 has been a major refactor to remove code duplication between the support and non-support version. This will make future implementations and maintanence much easier.

All the present and dismiss methods work as is. In order to perform more advanced functionality (e.g. overriding animations) you will need to call beginPresentation() first and string together the builder patter items to perform the required tasks.

Presenting a fragment

// Basic Presenting has not changed. Just call:
presentFragment(Fragment);
// as well as 
presentFramgent(Fragment, Bundle);

// The biggest change is adding additional options to your presentation. In order to present with a bundle or override animations you would do that as follows:
// 1.0.0 
overrideNextAnimation(int, int);
presentFragment(Fragment, Bundle);

// 2.0.0
// Animations must now be set before presentation. They cannot be overriden at dismiss time.
// Presenting a fragment now has additional options and is done through a builder style.
beginPresentation().setCustomAnimations(int, int, int, int)
    .setNavBundle(Bundle)
    .presentFragment(Fragment);

Dismissing a Fragment

// This have not changed. Just call:
dismissFragment();
// OR
dismissFragment(Bundle);
// From within your fragment

// NOTE: animations must all be set at presentation time now and cannot be overridden before a dismiss.

Trasitions

This implementation of the NavigationManager include support for transitions (API 21 and above). See the Transtions example in the v17 project. At this point I have only added the shared element portion as that is all that is required in the transaction. The rest can be set up in the fragments themselves. (FUTURE implementation will do this all in the transaction once set up as well as allow for default implementations much like the )

NavigationFragment fragment = LargeImageFragment.newInstance();
PresentationTransaction transaction = beginPresentation();

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
    setExitTransition(new Slide(Gravity.START));
    setEnterTransition(new Slide(Gravity.START));

    fragment.setSharedElementEnterTransition(new DetailTransition());
    fragment.setSharedElementReturnTransition(new DetailTransition());

    fragment.setEnterTransition(new Slide(Gravity.END));

    transaction.addSharedElement(smallImageView, "trans_largeImageView");
}
transaction.presentFragment(fragment);

Items Removed:

MasterDetail implementation (this was created as something that I needed for a project. I've removed it so remove excess coding when adding to the interface declaration) ListFragment implementation (this is not needed with the recycler view being widely accepted and used and it's been around so long)

Introduction

The purpose of this manager is to handle a single stack flow of fragments on the screen so that the developer can easily create flows without having to worry about using the FragmentManager and ChildFragmentManager. The single instance of the NavigationManagerFragment will easily handle the presenting and dismissing of Fragments as they are created and added or removed from the stack.

Every Fragment in the Navigation Stack must extend NavigationFragment in order to properly be displayed and navigated. Every NavigationFragment will have access to the NavigationManagerFragment in order to push and pop Fragments from the stack. Further details below will explain how to use the functionality provided by this Manager.

Implementation

The Stack Fragment Manager

Use the Stack Fragment Manager just like a normal fragment. In your activity, add it to the manager with an initial fragment and you are ready to use the Navigation Manager.

public class SingleStackNavigationExampleActivity extends AppCompatActivity {

    private static final String STATE_NAV_TAG = "NAV_TAG";

    private String mStackNavigationManagerFragmentTag;

    // ... 

    // In the activity, create the stack manager fragment and add it to the screen with the initial fragment.
    StackNavigationManagerFragment navManager = StackNavigationManagerFragment.newInstance(SampleFragment.newInstance("Root Fragment in the Stack", 0));

    mStackNavigationManagerFragmentTag = UUID.randomUUID().toString();

    FragmentManager fm = getFragmentManager();
    FragmentTransaction ft = fm.beginTransaction();
    ft.add(android.R.id.content, navManager, mStackNavigationManagerFragmentTag);
    ft.commit();

    // Rest of your code.

Now from within your Fragments you can easily present and dismiss fragments using. All fragments that you would like to manager using the NavigationManager must extend NavigationFragment.

Navigation fragmentToPresent = SampleFragment.newInstance("Fragment added to Stack.", (mFragCount + 1));
presentFragment(fragmentToPresent);

Here is an example of the SampleFragment

// You Fragments must extend from NavigationFragment to have access to the helpers and Navigation Manager.
public class SampleFragment extends NavigationFragment {

    // ...
    // To perform basic presentations:
    Navigation fragmentToPresent = SampleFragment.newInstance("Fragment added to Stack.", (mFragCount + 1));
    presentFragment(fragmentToPresent);

    // For more advanced presentations use:
    beginPresentation()
        .setCustomAnimations(R.anim.slide_in_from_bottom, R.anim.slide_out_to_top, R.anim.slide_out_to_bottom, R.anim.slide_in_from_top)
        .presentFragment(fragmentToPresent);

    // To dismiss the current fragment call
    dismissFragment();

    // ... Rest of class
}

Upcoming Plans

See TODO

Change Log

2.0.2

2.0.1

2.0.0

1.0.0

0.3.1

0.3.0

NOTE: The present and dismiss share the same bundle and hence setting a bundle on present/dismiss will override the current nav bundle for the specific fragment that is presented or the fragment that is returned to on dismiss.

See CHANGELOG for past implementation notes and current in progress items.

In Android Studio Terminal use:

./gradlew install

./gradlew bintrayUpload

License

Copyright (c) 2016 DMCApps MIT License