scrollytell 1.0.4

  • Readme
  • Changelog
  • Example
  • Installing
  • 75

✨ Scrollytell Flutter #

platform License: MIT By-MDG

A flutter package to implement ScrollyTelling in your flutter app. Using ScrollyTell you can have the background changing dynamically as you scroll. ScrollyTell provides a mechanism to fully control this behaviour. Visit our medium blog.

🎖 Installing #

dependencies:
  scrollytell: ^1.0.4

⚡️ Import #

import 'package:scrollytell/scrollytell.dart';

Props #

propstypedefault valueDescription
panels (required)List WidgetA list of panel widgets
panelStartCallbackFunction(num, Function)Called on start of new panel
panelEndCallbackFunction(num, Function)Called on end of existing panel
panelProgressCallbackFunction(num, double, Function)Called every frame
opacitydouble1Set opacity of the panels
lastPanelForceCompleteboolfalseSet true if the last panel hits bottom of the screen and can't be scrolled through
initialOverlayWidgetWidgetnoneOverlay widget before start of scrolling
guidelinePositionGuidelinePositionGuidelinePosition.topSet position of guideline
stickyChartIndexintnullThe panel of corresponding index will dock at center when scrolled past the center
showDebugConsoleboolfalseshow debug console (activePanelIndex, progress) and debug line (guideline)

At least one of the panelStartCallback, panelProgressCallback, panelEndCallback must be non-null.

Terminology and Explanation #

Panel #

Panel is a widget. The list of panels form a scrolling sequence. In simple words, each panel is widget that remains in foreground while scrolling.

OverlayWidget #

The overlay widget is what you want to be dynamically changed as you scroll. For example: In a simple story telling app, the panel will consist of a text portion of the story, while the OverlayWidget shows a corresponding graphic.

guideline #

Guideline is an imaginary reference line. When the panel's top coincide with the guideline we say panel has been 'started' or the panel is 'active' and panelStartCallback is called. Similarily when panel's bottom touch guideline we say panel is ended andpanelEndCallback is called. You can choose the guidelinePosition to be either at ScrollyWidget's top, center, bottom.

activePanelIndex #

An integer value corresponding to the panel that is "active"(coincides with the guideline).

progress (0,1) #

A double value that depicts how much the panel has been scrolled past the guideline. For example: When the center of panel reaches guideline progress is half.

🎮 How To Use #

Declare a List of Widgets #

List<Widget> panelList = [Text('Hello Scrollytell'), Text('Hello Flutter')];

Declare an Overlay Widget #

Widget overlayWidget;

Declare a ScrollyWidget #

Widget _scrollyWidget = ScrollyWidget(
		   showDebugConsole: true,
  	           guidelinePosition: GuidelinePosition.center,
                   panels: panelList,
                   panelStartCallback: (activePanelNumber, func){},
                   panelEndCallback: (endingPanelNumber, func){},
                   panelProgressCallback: (activePanelNumber, progress, func){
    
                // set properties of overlay widget using activePanelNumber and progress
        
                       double rad = (progress <= 0.5) ? progress * 200 : 200 - progress * 200;
                       overlayWidget = Center(
                           child: Container(
                               width: 200,
                               height: 200,
                               decoration: BoxDecoration(
                                   borderRadius: BorderRadius.all(
                                       Radius.circular(rad),
                                   ),
                               color: Colors.red,
                               ),
                           ),
                       );
        
                // then pass it into the function
        
                       func(overlayWidget)
                   },
               )

Now Wrap it in either Expanded, Flexible or Container #

Option 1 : Wrap in Expanded for covering the remaining screen.

Expanded(child: _scrollyWidget)

Option 2 : Wrap in Flexible

Flexible(child: _scrollyWidget)

Option 3 : Wrap in container to give it desired size.

Container(height: 500, width: 300, child: _scrollyWidget)

OR Use it directly as body of Scaffold. #

Scaffold(body: _scrollyWidget)

For more info, refer to the basic_usage app in the example.

Some usage tips for beginners #

Setting the overlay widget. #

  • The overlayWidget will continue to be the one which was last set in the callback(s) unless you explicitly change it.
  • When you do not want to display anything at overlayWidget set it to be Container()

adding a "fake panel" #

  • Sometimes you may want to include want to include containers at start (maybe a heading) and want it to scroll with your actual panels. The best option is to add it as a panel in the panelList and not manipulate the overlayWidget when activePanelIndex is 1.
  • A similar approach can be applied when you want include containers (like large empty spaces) in between you actual panels (like, text portions of story). Just include the container at the appropriate position in the panelList and not manipulate the overlayWidget when activePanelIndex is corresponding index.

🚀 Showcase #


🐛 Bugs/Requests #

If you encounter any problems feel free to open an issue. If you feel the library is missing a feature, please raise a issue(label:enhancement) on Github and we will look into it. Pull requests are most welcome.

🤝 Guidelines for Contributors #

If you want to contribute to improve this library, please read our guidelines. Feel free to open an issue.

⭐️ License #

MIT License view license

This project draws inspiration from @google's Scrollytell.

[1.0.4] - Dec 9,2019

  • Resolved bug for [initalOverlayWidget == null]
  • One of the three callbacks and list of panels is compulsory
  • added documentation

[1.0.3] - Dec 8,2019

  • Updated description

[1.0.2] - Dec 8,2019

  • Added terminology and usage tips in readme

[1.0.1] - Dec 7,2019

  • Minor changes in description and readme.

[1.0.0] - Dec 7,2019

  • A flutter package for ScrollyTelling.

example/README.md

These examples explain how to use the library.

DescriptionCode
Show basic usage of ScrollyWidgetcode
Fancy Panel used in Animal Farmcode
Story Telling appcode

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  scrollytell: ^1.0.4

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:scrollytell/scrollytell.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
49
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
75
Learn more about scoring.

We analyzed this package on Jan 19, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.0
  • pana: 0.13.4
  • Flutter: 1.12.13+hotfix.5

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.0 <3.0.0
flutter 0.0.0
Transitive dependencies
collection 1.14.11 1.14.12
meta 1.1.8
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test