Deprecation Note

The open-source version of Scoop is no longer actively maintained and does not represent the version of Scoop currently being used internally at Lyft.

Scoop

Scoop is a micro framework for building view based modular Android applications.

What do I get?

1. Router. Object that allows you to navigate between screens and maintain backstack.
2. View controllers. A new building block that you will use instead of Activity and Fragments.
3. Layouts. A new building block that you will use instead of Activity and Fragments.
4. Scoops ("Scopes"). Hierarchical scopes that allows you organize your application dependencies and their lifespan.
5. Transitions. Animations played between moving from one view to another. We provide a set of basic transitions such as sliding right, left, etc. Additionally, you are able to create your own custom transitions.

Navigation

Our navigation is based on lightweight objects called Screen.

Screen is a meta data object that specifies which view controller or layout you want to show and optional data you want to pass to your view controller or layout. You can think of them as Android Intents with a much simpler API.

Screen screen = new MyScreen(new MyData("foo"));

router.goTo(screen);

The Screen class is extendable, and will provide you with the foundation for your navigation.

@ViewController(MyController.class)
public class MyScreen extends Screen {
}

We provide 5 primary navigation methods:

1. goTo - Go to specified Screen and add it to the backstack.
2. replaceWith - Go to specified Screen and replace the top of the backstack with it.
3. replaceAllWith - Replace the backstack with a List of specified Screens, and navigate to the last Screen in the list.
4. resetTo - Go to specified Screen and remove all Screens after it from the backstack. If the specified screen is not in the backstack, remove all and make this Screen the top of the backstack.
5. goBack - Navigate to previous Screen.

Router does not render views. Router just emits an event that you can listen to in order to render the specified Screen. Within Scoop we provide the extensible view UIContainer that you can use to render view controllers and transitions.

ViewController

This class manages a portion of the user interface as well as the interactions between that interface and the underlying data. Similar to an activity or a fragment, ViewController requires you to specify the layout id and has lifecycle methods. However, a ViewController lifecycle only has two states: "attached" and "detached".

You can also use view binders like Butterknife. So you don't need to explicitly call ButterKnife.bind/unbind.

@ViewController(MyController.class)
public class MyScreen extends Screen {
}

public class MyController extends ViewController {

    @Override
    protected int layoutId() {
        return R.layout.my;
    }

    @Override
    public void onAttach() {
        super.onAttach();
    }

    @Override
    public void onDetach() {
        super.onDetach();

    }

    @OnClick(R.id.do_smth)
    public void doSomething() {

    }
}

The big difference from Android fragments and activities is that in Scoop we don't keep the ViewController in memory after it was detached. Whenever you move to a new Screen the ViewController detaches and is disposed together with the view.

Layout

A Layout annotation can be used similarly to ViewController annotation, and can accomplish the same goals. However, there is a higher degree of coupling between the controller and the view in this approach, so this implementation is generally not recommended.

@Layout(R.layout.my)
public class MyScreen extends Screen {
}

public class MyView extends FrameLayout {

    public LayoutView(Context context, AttributeSet attrs) {
      super(context, attrs);
    }

    @Override
    protected void onAttachedToWindow() {
      super.onAttachedToWindow();

      if (isInEditMode()) {
        return;
      }
    }

    @OnClick(R.id.do_smth)
    public void doSomething() {

    }
}

Scoops

Scoop's namesake is the word "scope". You can think of app scopes as ice cream scoops: going deeper in the navigation stack is an extra scoop on the top with another flavor.

Primary purpose of scoops is providing access to named services. When you create a scoop you have to specify its parent (except root) and services.

Scoop rootScoop = new Scoop.Builder("root")
        .service(MyService.SERVICE_NAME, myService)
        .build();

Scoop childScoop = new Scoop.Builder("child", rootScoop)
        .service(MyService.SERVICE_NAME, myService2)
        .service(OtherService.SERVICE_NAME, otherService)
        .build();

Internally, when trying to find a service within scoop, scoop will first try to find the service within itself. If the service is not within itself, scoop will iteratively go up in its scoop heirarchy to try to find the service.

MyService service = childScoop.findService(MyService.SERVICE_NAME);

When a scoop is no longer needed you can destroy it, which will remove references to all its services and invoke destroy for all children.

childScoop.destroy();

You are only required to create the root scoop manually. All child scoops will be created by Router whenever you advance in navigation. Created child scoops will be destroyed whenever you navigate to a previous item in the backstack.

To control child scoop creation you should extend ScreenScooper class. By default ScreenScooper only adds Screen to each child scoop.

Instead of adding individual services to your scoops, we recommend implementing dagger integration. In this case the only added service will be the dagger injector.

public class DaggerScreenScooper extends ScreenScooper {

    @Override
    protected Scoop addServices(Scoop.Builder scoopBuilder, Screen screen, Scoop parentScoop) {
        DaggerInjector parentDagger = DaggerInjector.fromScoop(parentScoop);

        DaggerModule daggerModule = screen.getClass().getAnnotation(DaggerModule.class);

        if(daggerModule == null) {
            return scoopBuilder.service(DaggerInjector.SERVICE_NAME, parentDagger).build();
        }

        DaggerInjector screenInjector;

        try {
            Object module = daggerModule.value().newInstance();
            screenInjector = parentDagger.extend(module);
        } catch (Throwable e) {
            throw new RuntimeException("Failed to instantiate module for screen: " + screen.getClass().getSimpleName(), e);
        }

        return scoopBuilder
                .service(DaggerInjector.SERVICE_NAME, screenInjector).build();
    }
}

Transitions

Transitions are animations played between moving from one ViewController to another. Within Scoop we provide the following built in transitions:

1. Backward slide
2. Forward slide
3. Downward slide
4. Upward slide
5. Fade

To apply a transition you have to specify it for your ViewController by overriding enterTransition()/exitTransition() methods.

public class MyController extends ViewController {

    @Override
    protected ScreenTransition enterTransition() {
        return new ForwardSlideTransition();
    }

    @Override
    protected ScreenTransition exitTransition() {
        return new BackwardSlideTransition();
    }

    ...
}

If a transition is not specified, views will be swapped instantly.

You can also implement custom transitions by implementing the ScreenTransition interface.

public class AutoTransition implements ScreenTransition {

    @TargetApi(Build.VERSION_CODES.LOLLIPOP)
    @Override
    public void translate(final ViewGroup root, final View from, final View to, final TransitionListener transitionListener) {

        Scene toScene = new Scene(root, to);

        android.transition.AutoTransition transition = new android.transition.AutoTransition();

        transition.addListener(new Transition.TransitionListener() {
            @Override
            public void onTransitionEnd(Transition transition) {
                transitionListener.onTransitionCompleted();
            }

            @Override
            public void onTransitionCancel(Transition transition) {
                transitionListener.onTransitionCompleted();
            }
            ...
        });

        TransitionManager.go(toScene, transition);
    }
}

Samples

• Basics - App that showcases the basics of Scoop (navigation, parameter passing, dependency injection)
• Micro Lyft - advanced sample based on Lyft's public api to showcase real world usage [COMING SOON].

Questions

For questions please use GitHub issues. Mark the issue with the "question" label.

Download

compile 'com.lyft:scoop:0.4.2'

Snapshots of development version are available in Sonatype's snapshots repository.

License

Copyright (C) 2015 Lyft, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Special Thanks

• Logan Johnson
• Ray Ryan
• Pierre-Yves Ricau
• Jake Wharton