Meteor Community Logo

Meteor Community

Packosphere

undefined's Avatar

matheus90:mobi-router

v0.6.62•Published 10 years ago

This package has not had recent updates. Please investigate it's current state before committing to using it in your project.

Mobi-Router

Simple router made for meteor apps designed specifically for mobile devices.

It uses the concept of keeping a stack of "slides" (alias for pages in web apps) which can be used to create sequences like sign up, etc. E.g for applications which need to go deeper and deeper into a page (like School > Class > Student > Student Profile), it makes creating such sequences with "Back" and "Next" buttons very easy.

You can checkout the demo site here: http://mobi-router.meteor.com/

Installation

The latest package is always on Atmosphere. To install latest package:

$ mrt add mobi-router

After it's installed, place the base template (the root of Mobi-Router) somewhere like this:

1<body>
2
3    ...
4    
5    <div id="page">
6        {{> mobi_router}}
7    </div>
8    
9    ...
10    
11</body>

Set the desktopWidth and desktopHeight in the .configure(settings) to fit in place like on the demo site does. (On demo site it's displayed as it would be the screen of the iPad graphics.)

API

Basic Navigation

.go(routeName, params, pushToStack);

Most common way to navigate to the routeName . It's possible to use different ways:

Start new route stack: MobiRouter.go('home', {first: 'blabla', second: '123'});

  • routeName: Name of the route
  • params: Parameters to be passed to the given route
  • pushToStack: Whether to create a new stack or push to the present stack.

When pushToStack is true, back button is automatically enabled. Text to show in Back button can be customized in settings.

Note: pushToStack will append the path of routeName to url already present in browser window

Consider keeping pushToStack true for the special usecase of creating flow sequences when you need user to go back to previous slide with a 'Back' button.

Append page to stack can be shorten, because this:

1MobiRouter.go('greeting', {}, true)

is the same as:

1MobiRouter.go('greeting', true)

.back(posToMove, keepFollowings);

Animates the content to move back to left. It navigates to the previous slide in sequence if there is one.

  • posToMove (int): (def.: 1) number of pages to move
  • keepFollowings (bool): (def.: false) if set true, the stack remains the same, but paging animation fires
  • return: no return

.next(posToMove);

Animates the content to move back to left. Navigates to next slide in the stack if there is one.

  • posToMove (int): (def.: 1) number of pages to move
  • return: no return

.setParams(params, route);

If you do not want to go to another page but change parameters of the current or any requested page, you can use this function.

  • params (object): the parameteres you want to update
  • route (MobiRoute): (deg.: current) the route which you want to update it's parameters
  • return: the refreshed route used by the function

.showSidebar();

With this you can show the sidebar (i.e. move the main window to the right)

  • return: (bool)true

.hideSidebar();

With this you can hide the sidebar (i.e. move the main window to the left)

  • return: (bool)true

Configuration

.map(map);

Adding routes to MobiRouter. The data attribute if object will be passed to the template, if function it will be calculated first and the result is passed to the template.

1MobiRouter.map({
2    'home': {
3        path: '/',
4        defaultTitle: 'Home',
5        template: 'home',
6        routeType: 'SimplePage',
7        data: function(){ return {first: this.params.first, fffsss: this.params.second}; },
8        classExtensions: {
9            page: 'lightsteelblue-bg',
10            header: 'orange-bg',
11        },
12    },
13    'greeting': {
14        path: '/greeting/:first/:last',
15        defaultTitle: 'Wellcome, <i> {:firstName} {:lastName} </i>!',
16        template: 'hello',
17        data: function(){ return {firstName: this.params.first, lastName: this.params.last}; },
18    },
19    'animals': {
20        path: 'animals',
21        defaultTitle: 'Animals',
22        routeType: 'TableView',
23        rows: [
24            {
25                id: 'mammals-link',
26                classExtension: 'custom-link',
27                title: 'Mammals',
28                type: 'link',
29                subTitle: function() { return 'Count: <b>'+(_.keys(Animals.mammals).length)+'</b>'; },
30                action: function(){ MobiRouter.go('mammals', true); },
31            },
32            
33            ...
34            
35        ],
36    },
37    
38    ...
39    
40});

.configure(settings);

For setting up defaults for MobiRouter, you specify the settings like this:

1MobiRouter.configure({
2    canISpeak: true,            // create logs in the console
3    desktopWidth: 800,
4    desktopHeight: 600,
5    headerHeight: 45,    
6    sidebarMoveTime: 300,
7    sidebarMoveEasing: 'easeOutExpo',
8    sidebarToggleBtn: 45,
9    sidebarDefaultWidth: 300,
10    sidebarTemplate: 'sidebar',
11    notFoundTemplate: 'not_found',
12    notFoundTitle: '404, Page not found',
13    defaultBackBtnText: 'Back',
14    defaultBackBtnAction: function(){ MobiRouter.back(); },
15    defaultNextBtnText: 'Next',
16    defaultNextBtnAction: function(){ MobiRouter.next(); },
17    loadingTemplate: true, // { false || true || 'loading' },
18    minLoadingTemplateTime: 3000, 
19    pageMoveTime: 600,
20    pageMoveEasing: 'easeInOutBack',
21});

.setViewTypes(types);

The is an opportunity to create custom templates to fit the routes into. You can set the routeType of the route e.g. TableView and it will create a page like this. If you leave out the routeType attribute it will defaults to SimplePage that means the route will be rendered with it's own template.

To create new view types you need to add them this way:

1MobiRouter.setViewTypes({
2    TableView: 'mobi_tableview',
3    . . .
4});

Custom views

You can easily add custom views with .addViewTypes. Custom views are basically simple templates which are rendered with all the other data provided when defining a route in MobiRouter.map(). They provide infinite re-usability.

For now, mobi-router provide following custom views baked in:

TableView

It renders a list of rows on the screen like the most common interface of most mobile apps. There are various customization options to render the rows differently.

A route can be converted to render a TableView by specifying routeType: "TableView". A TableView require rows property of the route which represents the rows to render. See below

  • rows It has to be an array of objects. Each object in the array represents a single row. Each row can have various customization options.

    • type A row can be of basically two types: link and button which are further customizable.
      • link A link is a simple link row which performs some action (provided by action property of the row) when user click/touch it. action is usually used for navigation
        Link can have an option linkBtn property. If set to true, a button appears on the right end of row with linkBtnText as its text and linkBtnClass as its class, which performs action provided by linkBtnAction.
      • button Simple row with a button at the right end. In this case row itself doesn't do any action, action is performed by the button only. [TODO: More docs]
    • linkBtn: Boolean Decide if a button will be shown in right end of row. Works only with link type row
    • linkBtnText: String Text to be shown in the button. It can also be html code. Works only with link type row
    • linkBtnClass: String Class of the button. Useful if you want button to have bootstrap/foundation classes. Works only with link type row
    • linkBtnAction: Function Function to be executed when button on link row is clicked

!-----------------------------------! !-- TODO: More Documentation --! !-----------------------------------!

.animateScroller(pos, time);

Animates the content to move to the requested/current position. (paging animation)

  • pos (int): (def.: currentPosition()) requested position, starts with 0
  • time (int): (def.: 750) animation duration in milliseconds
  • return: no return

.backBtnAction();

Action that will be fired when pressing the current back button in the header. Default: MobiRouter.back();

.backBtnText();

The text of the current back button in the header.

.calculateSizes();

Refreshes the stored data of Mobi-Router part sizes

.content(route);

The template of the specified/current route.

  • route(MobiRoute): (def.: .currentRoute()) the route what you need the title for
  • return: (Template)

.currentPosition();

Provide current route's position in the stack

  • return: (int)

.currentRoute();

Returns the current route object (MobiRoute object)

  • return: (MobiRoute)

.currentRouteName();

The id/name of the current route.

  • return: (string)

.currentTemplate();

The name of template assigned to the current route.

  • return: (string)

.dep (Dependecy)

Reactivity trigger used by Mobi-Router.

.getData();

Returns the data of route passed into the current template.

  • return: (object)

.getMap();

Provides the whole routemap saved from calling .map() function.

  • return: (object)

.getPageTitle(route);

The title of specified/current route, calculated by the .getData() returned values.

  • route (MobiRoute): (def.: .currentRoute()) the route which you need the title for
  • return: (html)

.getSlideStack();

The stack/array of currently queued routes.

  • return: (array)

.getSlideStackSize();

Size of routes stack.

  • return: (int)

.getUrl();

Generates pathname for url from the actual stack and route parameters.

  • return: (string)

.hasBackBtn();

Wether the header has back button or not.

  • return: (bool)

.hasNextBtn();

Wether the header has next button or not.

  • return: (bool)

.initScrolls();

Initialize/refresh sidebar scroller and page scrollers.

.jumpToPosition(pos);

Jumps to the requested|current route without animation.

  • pos (int): (def.: currentPosition()) requested position, starts with 0

.loading();

It's true while the loading template is on the screen.

  • return: (bool)

.loadingTemplate();

The template used as load screen on site opening.

  • return: (Template)

.nextBtnAction();

The function called when .next() is triggered.

  • return: (function)

.nextBtnText();

Text shown on the actual next button in the header

  • return: (string)

.notFoundTemplate();

The template which is used when Mobi-Router can not find the requested page.

  • return: (Template)

.notFoundTitle();

The title shown when the requested page has not found.

  • return: (string)

`.readUrl(url);

Read out a sequence from the requested|current url.

  • url (string): (def.: actual url) the url you want to get the sequence out
  • return: (array)

.refreshSidebarScroll();

Manual trigger to refresh the sidebar's scroller.

.sidebar();

The sidebar template set by the configurator of site.

  • return: (Template)

.speak(message);

Centralized function to display logs of Mobi-Router.

  • message (string): the message you want to display in console

.storedRoutes();

Array of stored routes set with .map() function.

  • return: (array)

README.md style changes and technical updates are possible in future