3 |
4 | UpUp is a tiny JavaScript library that makes sure your users can always access your site's content, even when they're on a plane, in an elevator, or 20,000 leagues under the sea.
5 |
6 | Mobile-First has become the de-facto standard for building modern sites. But in a world where everyone is mobile, an always-on connection isn't something we can rely on. It's time to start thinking **Offline First**.
7 |
8 | With UpUp you control the content your users see, even when they are offline. And you can do it with just a single JavaScript command.
9 |
10 | ### Demo & Tutorial
11 | The easiest path to understanding is to see [UpUp in action and try a quick tutorial](https://www.talater.com/upup/).
12 |
13 | ### Hello World
14 | Getting started with UpUp is as easy as adding two JavaScript files to your site, [upup.min.js](https://raw.githubusercontent.com/TalAter/UpUp/master/dist/upup.min.js) & [upup.sw.min.js](https://raw.githubusercontent.com/TalAter/UpUp/master/dist/upup.sw.min.js), and defining the content you want your users to see when they are offline.
15 |
16 | For example:
17 | ````html
18 |
19 |
25 | ````
26 | Now every time your users return to your site and their connection is down, they will see the contents of `offline.html` instead of an error.
27 |
28 | **Check out some [live demos and a full tutorial](https://www.talater.com/upup/). Once you're up and rolling, you can read the full [API Docs](https://github.com/TalAter/UpUp/blob/master/docs/README.md).**
29 |
30 | ### HTTPS Requirement
31 | UpUp requires a secure connection to your site (this is a requirement of service workers, the technology at the heart of UpUp). So make sure your users visit your site over HTTPS (an SSL certificate is free with [Let’s Encrypt](https://letsencrypt.org/) or via CloudFlare).
32 |
33 | ### Browser Support
34 | UpUp works in any browser that supports service workers. Currently this means:
35 | * Chrome 40+
36 | * Opera 27+
37 | * Firefox 41+
38 |
39 | If your users are using a different or older browser, they will simply be unaffected by UpUp. Nothing will break, and they simply won't notice anything different.
40 |
41 | ### Technical Documentation and API
42 | [Docs and full API reference](https://github.com/TalAter/UpUp/blob/master/docs/README.md)
43 |
44 | ### Author
45 | Tal Ater: [@TalAter](https://twitter.com/TalAter)
46 |
47 | ### License
48 | Licensed under [MIT](https://github.com/TalAter/annyang/blob/master/LICENSE).
49 |
--------------------------------------------------------------------------------
/bower.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "upup",
3 | "homepage": "https://www.talater.com/upup/",
4 | "authors": [
5 | "Tal Ater 
18 | Via Piacenza 9, Rome, Italy
21 |
26 | Piazza Barberini 11, Rome, Italy
29 |
34 | Via Tor de Conti 22, Rome, Italy
37 |
42 | Via delle Alpi 4, Rome, Italy
45 |Via Piacenza 9, Rome, Italy
20 |Piazza Barberini 11, Rome, Italy
27 |Via Tor de Conti 22, Rome, Italy
34 |Via delle Alpi 4, Rome, Italy
41 |
48 | Mobile First has become the de-facto standard for building modern sites. But in a world where everyone is mobile, an always-on connection isn't something we can rely on. It's time to start thinking Offline First.
54 |This tutorial will show you how to add offline functionality to your site in under 10 minutes. When you're done, your visitors will no longer be greeted with an error screen when they visit your site with no connection... Instead you'll be able to control the content and experience they get.
55 |We'll start with a simple site, and add the offline features to it:
57 |<html>
58 | <head>
59 | <meta charset="UTF-8">
60 | <title>Lonely Globe Advisor</title>
61 | </head>
62 | <body>
63 | <h1>Top Hotels in Rome</h1>
64 | <ol>
65 | <li>Villa Domus - Via Piacenza 9, Rome, Italy</li>
66 | <li>Hotel Trivelli - Piazza Barberini 11, Rome, Italy</li>
67 | </ol>
68 | </body>
69 | </html>Our sample site, Lonely Globe Advisor, offers visitors a list of the top hotels in Rome, with user ratings and an address.
71 |But what happens if our user just landed in Rome and doesn't have a local data plan?
72 |Well, he'll be out of luck.
73 |We can control the experience our users get when they are offline with 2 simple steps:
75 |<html>
80 | <head>
81 | <meta charset="UTF-8">
82 | <title>Lonely Globe Advisor</title>
83 | </head>
84 | <body>
85 | <h1>Top Hotels in Rome</h1>
86 | <ol>
87 | <li>Villa Domus - Via Piacenza 9, Rome, Italy</li>
88 | <li>Hotel Trivelli - Piazza Barberini 11, Rome, Italy</li>
89 | </ol>
90 | <script src="/upup.min.js"></script>
91 | <script>
92 | UpUp.start({
93 | 'content': '<html><body><h1>Top Hotels in Rome</h1><p>Villa Domus</p><p>Hotel Trivelli</p></body></html>'
94 | });
95 | </script>
96 | </body>
97 | </html>In the code above we simply told UpUp to display some simple HTML the next time a user can't access our site.
99 |With just this tiny bit of code, we've added an offline experience for our site, and allowed our users to see the best hotels in Rome… even when they can't access the web.
100 |UpUp uses service workers to determine when network requests fail. A service worker is a special script that runs in the browser in the background, and can see the status of network requests.
103 |When the user first visits your site, UpUp registers a service worker with your browser, and gives it a list of files to cache for later.
104 |The next time the user visits your site, the service worker listens for network errors. If a network request fails, and the service worker finds that file in the cache, it will return that file, as if it came from the network.
105 |While this is already quite impressive, it still doesn't look anything like our online version. Let's improve the offline version with more content and our design.
108 |We'll begin by moving our offline content to a separate file. This will make it much easier to update and maintain, and we'll no longer have to include the entire content of the offline site on every page.
109 |<html>
110 | <head>
111 | <meta charset="UTF-8">
112 | <title>Lonely Globe Advisor</title>
113 | </head>
114 | <body>
115 | <h1>Top Hotels in Rome</h1>
116 | <ol>
117 | <li>Villa Domus - Via Piacenza 9, Rome, Italy</li>
118 | <li>Hotel Trivelli - Piazza Barberini 11, Rome, Italy</li>
119 | </ol>
120 | <script src="/upup.min.js"></script>
121 | <script>
122 | UpUp.start({
123 | 'content-url': 'offline.html'
124 | });
125 | </script>
126 | </body>
127 | </html>Now the content our users see when they are offline, is the contents of offline.html. This is just a simple HTML file, no different than any other page on our site.
Our offline.html file contains two css files: bootstrap.min.css and offline.css. Let's make sure these are cached and available to our users when they are offline:
<html>
131 | <head>
132 | <meta charset="UTF-8">
133 | <title>Lonely Globe Advisor</title>
134 | </head>
135 | <body>
136 | <h1>Top Hotels in Rome</h1>
137 | <ol>
138 | <li>Villa Domus - Via Piacenza 9, Rome, Italy</li>
139 | <li>Hotel Trivelli - Piazza Barberini 11, Rome, Italy</li>
140 | </ol>
141 | <script src="/upup.min.js"></script>
142 | <script>
143 | UpUp.start({
144 | 'content-url': 'offline.html',
145 | 'assets': ['css/bootstrap.min.css', 'css/offline.css']
146 | });
147 | </script>
148 | </body>
149 | </html>For security reasons, the browser only lets UpUp's service worker see network requests within its scope.
154 |The scope that the service worker can affect is determined by where you placed upup.min.js and upup.sw.min.js. For example, if you place it on https://yoursite.com/js/upup.sw.min.js, UpUp will only be able to show your offline content when users try to look at the /js/ directory.
This is why it is important to place both files on the same server as your content, and not in a subdirectory. This should idealy be in the root of your site (e.g. https://yoursite.com/upup.min.js).
156 |With just one command and two settings, we can create rich offline experiences for our users. These can be as simple as the examples above, or as robust as a full single page application using frameworks like AngularJS, with content customized for each user, videos and even files the user can access while offline.
160 |<script src="/upup.min.js"></script>
161 | <script>
162 | UpUp.start({
163 | 'content-url': 'schedule.html?user=joe', // show this when the user is offline
164 | 'assets': [ // define additional assets needed while offline:
165 | 'img/logo.png', // such as images,
166 | 'css/offline.css', // custom stylesheets,
167 | 'schedule.json?user=joe', // dynamic requests with data per user,
168 | 'js/angular.min.js', // javascript libraries and frameworks,
169 | 'mov/intro.mp4', // videos,
170 | 'contacts.pdf' // and more.
171 | ]
172 | });
173 | </script>To preserve the user's security and privacy, service worker can only detect requests over a secure connection.
178 |During development you can use UpUp through localhost (e.g. http://localhost/ or http://localhost:1234/ are ok), but to deploy it to production you'll need to have HTTPS set up on your server.
This is a requirement for many new web technologies, and you can get free SSL certificates these days, so don't let that stop you… progress is coming.
180 |UpUp plays nicely with all browsers, progressively enhancing browsers that support Service Workers, while leaving users with older browsers unaffected.
185 |UpUp currently supports Chrome 40+, Opera 27+ and Firefox 41+. If your users are using a different browser, they simply won't notice anything different.
186 |
Download UpUp
195 | 
API Docs
202 | 
GitHub
209 | 
242 | 
243 |
28 | Your users are no longer sitting at their desktops, with a wire connecting them to the internet.
38 |They are visiting your site from a phone in an elevator, from their tablet on the subway, or on their laptop while they sit cramped into seat 25 E.
39 |This is why modern browsers support service workers, a new technology which lets you serve your content to your users, even when they are offline.
40 |UpUp is a free, open source project which makes using this modern magic as simple as calling one command.
41 |
42 | <script src="/upup.min.js"></script>
43 | <script>
44 | UpUp.start({
45 | 'content-url': 'offline.html' // show this page to offline users
46 | });
47 | </script>
48 | While easy to pick up, UpUp is powerful enough to support anything from showing simple messages, to making fully functional single page applications available offline, with data customized for each of your users.
51 | 52 |
Try the Tutorial
59 | API Docs
66 | GitHub
73 | UpUp is a free, open source, community effort.
80 |Please help us start the offline first revolution:
81 | 101 | 102 |
11 | 
15 | Lucky for you, UpUp is serving you content even when you are on a plane flying over the Pacific, or 20,000 leagues under the sea.
20 |To add the functionality you’re seeing now, we simply added a small piece of code to our site:
21 |
22 | <script src="upup.min.js"></script>
23 | <script>
24 | UpUp.start({
25 | 'content-url': 'offline.html', // show this page to offline users
26 | 'assets': // Save the following files to cache as well
27 | ['css/offline.css', 'css/bootstrap.min.css', 'img/mb-offline.png', 'img/logo.png', 'img/sunset.jpg']
28 | });
29 | </script>
30 |