Need help with scoop?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

lyft
1.1K Stars 87 Forks Apache License 2.0 153 Commits 14 Opened issues

Description

:icecream: micro framework for building view based modular Android applications.

Services available

!
?

Need anything else?

Contributors list

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 Build Status

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. ```java

@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
    Screen
    s, and navigate to the last
    Screen
    in the list.
  4. resetTo
    - Go to specified
    Screen
    and remove all
    Screen
    s 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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.