Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

brim

View (minimal-ui) manager for iOS 8.

Subscribe to updates I use brim


Statistics on brim

Number of watchers on Github 358
Number of open issues 11
Average time to close an issue 28 days
Main language JavaScript
Average time to merge a PR about 13 hours
Open pull requests 1+
Closed pull requests 1+
Last commit about 2 years ago
Repo Created about 5 years ago
Repo Last Updated over 1 year ago
Size 1.84 MB
Homepage http://gajus.com/...
Organization / Authorgajus
Contributors2
Page Updated
Do you use brim? Leave a review!
View open issues (11)
View brim activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating brim for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Brim

NPM version Bower version

View (minimal-ui) manager for iOS 8.

Try it and tweet it if you like it.

Using Brim with iOS simulator.

Contents

minimal-ui

In iOS 7.1, a property, minimal-ui, has been added for the viewport meta tag key that allows minimizing the top and bottom bars in Safari as the page loads. While on a page using minimal-ui, tapping the top bar brings the bars back. Tapping back in the content dismisses them again.

The minimal-ui viewport property is no longer supported in iOS 8. However, the minimal-ui itself is not gone. User can enter the minimal-ui with a touch-drag down gesture.

There are several pre-conditions and obstacles to manage the view state, e.g. for minimal-ui to work, there has to be enough content to enable user to scroll; for minimal-ui to persist, window scroll must be offset on page load and after orientation change. However, there is no way of calculating the dimensions of the minimal-ui using the screen variable, and thus no way of telling when user is in the minimal-ui in advance.

Features

Brim solves all of the issues associated with determining the state of the UI and controlling the persistence. Specifically:

  • Determines when user is in the minimal-ui.
  • Determines when the view changes.
  • Provides a UI to instruct user to enter the minimal-ui.
  • Locks user in the minimal-ui (following the spec defined in the iOS 7.1).
  • Makes the view persist when page is reloaded or device orientation changes.

Setup

You need to create two elements: mask and main. Mask is displayed to the user when page is in the full view. The role of the element is to instruct user to enter the minimal-ui. Main element is shown when mask is hidden.

  • These elements must be direct and sole descendants of <body>.
  • The IDs must be brim-mask and brim-main.
  • Do not apply styling that would affect the position or the dimensions of these elements.

The Underlying Implementation

When page is loaded, Brim will create a treadmill element. Treadmill element is used to give user space to scroll. Presence of the treadmill element ensures that user can enter the minimal-ui view and that it continues to persist if user reloads the page or changes device orientation. It is invisible to the user the entire time. This element has ID brim-treadmill.

Upon loading the page or after changing the orientation, Brim is using Scream to detect if page is in the minimal-ui view (page that has been previously in minimal-ui and has been reloaded will remain in the minimal-ui if content height is greater than the viewport height).

When page is in the minimal-ui, Brim will disable scrolling of the document (it does this in a safe way that does not affect the contents of the main element). Disabling document scrolling prevents accidentally leaving the minimal-ui when scrolling upwards. As per the original iOS 7.1 spec, tapping the top bar brings back the rest of the chrome.

When page is in the full view, Brim will show the mask element.

Quick Start

<!DOCTYPE html>
<html>
<head>
    <script src="./bower_components/scream/dist/scream.js"></script>
    <script src="./bower_components/brim/dist/brim.js"></script>
    <script>
    window.addEventListener('DOMContentLoaded', function () {
        var scream,
            brim;

        scream = gajus.Scream({
            width: {
                portrait: 320,
                landscape: 640
            }
        });

        brim = gajus.Brim({
            viewport: scream
        });
    });
    </script>
</head>
<body>
    <div id="brim-mask">
        <!-- Content displayed to the user when in full view. -->
    </div>
    <div id="brim-main">
        <!-- Content displayed to the user when in minimal view.  -->
    </div>
</body>
</html>

Styling

If mask element does not have active content, it is advisable to disable pointer events:

#brim-mask {
    pointer-events: none;
}

Do not set style that would change position or dimensions of the mask or the main element.

Do not style the treadmill.

Events

viewchange

Invoked on page load and when view changes.

brim.on('viewchange', function (e) {
    // Invoked when view changes.

    // @var {String} 'full', 'minimal'
    e.viewName;
});

Detecting iOS 8

Brim does not have a use case outside of iOS 8, though it does not restrict itself. I recommend using platform.js to target the platform:

if (platform.os.family == 'iOS' && parseInt(platform.os.version, 10) >= 8) {
    // Use Scream & Brim.
}

Download

Using Bower:

bower install brim

Using NPM:

npm install brim
brim open issues Ask a question     (View All Issues)
  • about 3 years Blank screen when switching modes
  • over 3 years scream.js throws error --- "exports is not defined"
  • over 3 years Google Maps Tips
  • over 3 years iPad Pro not recognised
  • about 4 years Using brim in landscape mode only
  • over 4 years Questions about using brim
  • over 4 years Problem overflow-y scroll and brim
  • almost 5 years Clicking on bottom of page disables minimal-ui
brim open pull requests (View All Pulls)
  • Better scroll prevention
brim list of languages used
Other projects in JavaScript