A Django app to include a manifest.json and Service Worker instance to enable progressive web app behavior
Project description
django-pwa
==========
|Build Status| |Maintainability| |codecov| |PyPI - Downloads| |PyPI -
Downloads| |PyPI - Downloads|
This Django app turns your project into a `progressive web
app <https://developers.google.com/web/progressive-web-apps/>`__.
Navigating to your site on an Android phone will prompt you to add the
app to your home screen.
.. figure:: https://github.com/silviolleite/django-pwa/raw/master/images/screenshot1.png
:alt: Prompt for install
Prompt for install
Launching the app from your home screen will display your app `without
browser
chrome <https://github.com/silviolleite/django-pwa/raw/master/images/screenshot2.png>`__.
As such, it’s critical that your application provides all navigation
within the HTML (no reliance on the browser back or forward button).
Requirements
============
Progressive Web Apps require HTTPS unless being served from localhost.
If you’re not already using HTTPS on your site, check out `Let’s
Encrypt <https://letsencrypt.org/>`__ and
`ZeroSSL <https://zerossl.com/>`__.
Installation
============
Install from PyPI:
::
pip install django-pwa
Configuration
=============
Add ``pwa`` to your list of ``INSTALLED_APPS`` in settings.py:
.. code:: python
INSTALLED_APPS = [
...
'pwa',
...
]
Configure your app name, description, icons and splash screen images in
settings.py:
.. code:: python
PWA_APP_NAME = 'My App'
PWA_APP_DESCRIPTION = "My app description"
PWA_APP_THEME_COLOR = '#0A0302'
PWA_APP_BACKGROUND_COLOR = '#ffffff'
PWA_APP_DISPLAY = 'standalone'
PWA_APP_SCOPE = '/',
PWA_APP_ORIENTATION = 'any'
PWA_APP_START_URL = '/'
PWA_APP_ICONS = [
{
'src': '/static/images/my_app_icon.png',
'sizes': '160x160'
}
]
PWA_APP_SPLASH_SCREEN = [
{
'src': '/static/images/icons/splash-640x1136.png',
'media': '(device-width: 320px) and (device-height: 568px) and (-webkit-device-pixel-ratio: 2)'
}
]
PWA_APP_DIR = 'ltr'
PWA_APP_LANG = 'en-US'
All settings are optional, and the app will work fine with its internal
defaults. Highly recommend setting at least ``PWA_APP_NAME``,
``PWA_APP_DESCRIPTION``, ``PWA_APP_ICONS`` and
``PWA_APP_SPLASH_SCREEN``.
Add the progressive web app URLs to urls.py:
.. code:: python
from django.urls import url, include
urlpatterns = [
...
url('', include('pwa.urls')), # You MUST use an empty string as the URL prefix
...
]
Inject the required meta tags in your base.html (or wherever your HTML
<head> is defined):
.. code:: html
{% load pwa %}
<head>
...
{% progressive_web_app_meta %}
...
</head>
Troubleshooting
===============
While running the Django test server:
1. Verify that ``/manifest.json`` is being served
2. Verify that ``/serviceworker.js`` is being served
3. Verify that ``/offline`` is being served
4. Use the Application tab in the Chrome Developer Tools to verify the
progressive web app is configured correctly.
5. Use the “Add to homescreen” link on the Application Tab to verify you
can add the app successfully.
The Service Worker
==================
By default, the service worker implemented by this app is:
.. code:: js
// Base Service Worker implementation. To use your own Service Worker, set the PWA_SERVICE_WORKER_PATH variable in settings.py
var staticCacheName = "django-pwa-v" + new Date().getTime();
var filesToCache = [
'/offline',
'/css/django-pwa-app.css',
'/images/icons/icon-72x72.png',
'/images/icons/icon-96x96.png',
'/images/icons/icon-128x128.png',
'/images/icons/icon-144x144.png',
'/images/icons/icon-152x152.png',
'/images/icons/icon-192x192.png',
'/images/icons/icon-384x384.png',
'/images/icons/icon-512x512.png',
'/static/images/icons/splash-640x1136.png',
'/static/images/icons/splash-750x1334.png',
'/static/images/icons/splash-1242x2208.png',
'/static/images/icons/splash-1125x2436.png',
'/static/images/icons/splash-828x1792.png',
'/static/images/icons/splash-1242x2688.png',
'/static/images/icons/splash-1536x2048.png',
'/static/images/icons/splash-1668x2224.png',
'/static/images/icons/splash-1668x2388.png',
'/static/images/icons/splash-2048x2732.png'
];
// Cache on install
self.addEventListener("install", event => {
this.skipWaiting();
event.waitUntil(
caches.open(staticCacheName)
.then(cache => {
return cache.addAll(filesToCache);
})
)
});
// Clear cache on activate
self.addEventListener('activate', event => {
event.waitUntil(
caches.keys().then(cacheNames => {
return Promise.all(
cacheNames
.filter(cacheName => (cacheName.startsWith("django-pwa-")))
.filter(cacheName => (cacheName !== staticCacheName))
.map(cacheName => caches.delete(cacheName))
);
})
);
});
// Serve from Cache
self.addEventListener("fetch", event => {
event.respondWith(
caches.match(event.request)
.then(response => {
return response || fetch(event.request);
})
.catch(() => {
return caches.match('offline');
})
)
});
Adding Your Own Service Worker
==============================
To add service worker functionality, you’ll want to create a
``serviceworker.js`` or similarly named template in a template
directory, and then point at it using the PWA_SERVICE_WORKER_PATH
variable (PWA_APP_FETCH_URL is passed through).
.. code:: python
PWA_SERVICE_WORKER_PATH = os.path.join(BASE_DIR, 'my_app', 'serviceworker.js')
The offline view
================
By default, the offline view is implemented in
``templates/offline.html`` You can overwrite it in a template directory
if you continue using the default ``serviceworker.js``.
Feedback
========
I welcome your feedback and pull requests. Enjoy!
License
=======
All files in this repository are distributed under the MIT license.
.. |Build Status| image:: https://travis-ci.org/silviolleite/django-pwa.svg
:target: https://travis-ci.org/silviolleite/django-pwa
.. |Maintainability| image:: https://api.codeclimate.com/v1/badges/246542ea921058c4f76f/maintainability
:target: https://codeclimate.com/github/silviolleite/django-pwa/maintainability
.. |codecov| image:: https://codecov.io/gh/silviolleite/django-pwa/branch/master/graph/badge.svg
:target: https://codecov.io/gh/silviolleite/django-pwa
.. |PyPI - Downloads| image:: https://img.shields.io/pypi/dm/django-pwa.svg
:target: https://pypi.org/project/django-pwa/
.. |PyPI - Downloads| image:: https://img.shields.io/pypi/v/django-pwa.svg
:target: https://pypi.org/project/django-pwa
.. |PyPI - Downloads| image:: https://img.shields.io/pypi/djversions/django-pwa.svg
:target: https://pypi.org/project/django-pwa
==========
|Build Status| |Maintainability| |codecov| |PyPI - Downloads| |PyPI -
Downloads| |PyPI - Downloads|
This Django app turns your project into a `progressive web
app <https://developers.google.com/web/progressive-web-apps/>`__.
Navigating to your site on an Android phone will prompt you to add the
app to your home screen.
.. figure:: https://github.com/silviolleite/django-pwa/raw/master/images/screenshot1.png
:alt: Prompt for install
Prompt for install
Launching the app from your home screen will display your app `without
browser
chrome <https://github.com/silviolleite/django-pwa/raw/master/images/screenshot2.png>`__.
As such, it’s critical that your application provides all navigation
within the HTML (no reliance on the browser back or forward button).
Requirements
============
Progressive Web Apps require HTTPS unless being served from localhost.
If you’re not already using HTTPS on your site, check out `Let’s
Encrypt <https://letsencrypt.org/>`__ and
`ZeroSSL <https://zerossl.com/>`__.
Installation
============
Install from PyPI:
::
pip install django-pwa
Configuration
=============
Add ``pwa`` to your list of ``INSTALLED_APPS`` in settings.py:
.. code:: python
INSTALLED_APPS = [
...
'pwa',
...
]
Configure your app name, description, icons and splash screen images in
settings.py:
.. code:: python
PWA_APP_NAME = 'My App'
PWA_APP_DESCRIPTION = "My app description"
PWA_APP_THEME_COLOR = '#0A0302'
PWA_APP_BACKGROUND_COLOR = '#ffffff'
PWA_APP_DISPLAY = 'standalone'
PWA_APP_SCOPE = '/',
PWA_APP_ORIENTATION = 'any'
PWA_APP_START_URL = '/'
PWA_APP_ICONS = [
{
'src': '/static/images/my_app_icon.png',
'sizes': '160x160'
}
]
PWA_APP_SPLASH_SCREEN = [
{
'src': '/static/images/icons/splash-640x1136.png',
'media': '(device-width: 320px) and (device-height: 568px) and (-webkit-device-pixel-ratio: 2)'
}
]
PWA_APP_DIR = 'ltr'
PWA_APP_LANG = 'en-US'
All settings are optional, and the app will work fine with its internal
defaults. Highly recommend setting at least ``PWA_APP_NAME``,
``PWA_APP_DESCRIPTION``, ``PWA_APP_ICONS`` and
``PWA_APP_SPLASH_SCREEN``.
Add the progressive web app URLs to urls.py:
.. code:: python
from django.urls import url, include
urlpatterns = [
...
url('', include('pwa.urls')), # You MUST use an empty string as the URL prefix
...
]
Inject the required meta tags in your base.html (or wherever your HTML
<head> is defined):
.. code:: html
{% load pwa %}
<head>
...
{% progressive_web_app_meta %}
...
</head>
Troubleshooting
===============
While running the Django test server:
1. Verify that ``/manifest.json`` is being served
2. Verify that ``/serviceworker.js`` is being served
3. Verify that ``/offline`` is being served
4. Use the Application tab in the Chrome Developer Tools to verify the
progressive web app is configured correctly.
5. Use the “Add to homescreen” link on the Application Tab to verify you
can add the app successfully.
The Service Worker
==================
By default, the service worker implemented by this app is:
.. code:: js
// Base Service Worker implementation. To use your own Service Worker, set the PWA_SERVICE_WORKER_PATH variable in settings.py
var staticCacheName = "django-pwa-v" + new Date().getTime();
var filesToCache = [
'/offline',
'/css/django-pwa-app.css',
'/images/icons/icon-72x72.png',
'/images/icons/icon-96x96.png',
'/images/icons/icon-128x128.png',
'/images/icons/icon-144x144.png',
'/images/icons/icon-152x152.png',
'/images/icons/icon-192x192.png',
'/images/icons/icon-384x384.png',
'/images/icons/icon-512x512.png',
'/static/images/icons/splash-640x1136.png',
'/static/images/icons/splash-750x1334.png',
'/static/images/icons/splash-1242x2208.png',
'/static/images/icons/splash-1125x2436.png',
'/static/images/icons/splash-828x1792.png',
'/static/images/icons/splash-1242x2688.png',
'/static/images/icons/splash-1536x2048.png',
'/static/images/icons/splash-1668x2224.png',
'/static/images/icons/splash-1668x2388.png',
'/static/images/icons/splash-2048x2732.png'
];
// Cache on install
self.addEventListener("install", event => {
this.skipWaiting();
event.waitUntil(
caches.open(staticCacheName)
.then(cache => {
return cache.addAll(filesToCache);
})
)
});
// Clear cache on activate
self.addEventListener('activate', event => {
event.waitUntil(
caches.keys().then(cacheNames => {
return Promise.all(
cacheNames
.filter(cacheName => (cacheName.startsWith("django-pwa-")))
.filter(cacheName => (cacheName !== staticCacheName))
.map(cacheName => caches.delete(cacheName))
);
})
);
});
// Serve from Cache
self.addEventListener("fetch", event => {
event.respondWith(
caches.match(event.request)
.then(response => {
return response || fetch(event.request);
})
.catch(() => {
return caches.match('offline');
})
)
});
Adding Your Own Service Worker
==============================
To add service worker functionality, you’ll want to create a
``serviceworker.js`` or similarly named template in a template
directory, and then point at it using the PWA_SERVICE_WORKER_PATH
variable (PWA_APP_FETCH_URL is passed through).
.. code:: python
PWA_SERVICE_WORKER_PATH = os.path.join(BASE_DIR, 'my_app', 'serviceworker.js')
The offline view
================
By default, the offline view is implemented in
``templates/offline.html`` You can overwrite it in a template directory
if you continue using the default ``serviceworker.js``.
Feedback
========
I welcome your feedback and pull requests. Enjoy!
License
=======
All files in this repository are distributed under the MIT license.
.. |Build Status| image:: https://travis-ci.org/silviolleite/django-pwa.svg
:target: https://travis-ci.org/silviolleite/django-pwa
.. |Maintainability| image:: https://api.codeclimate.com/v1/badges/246542ea921058c4f76f/maintainability
:target: https://codeclimate.com/github/silviolleite/django-pwa/maintainability
.. |codecov| image:: https://codecov.io/gh/silviolleite/django-pwa/branch/master/graph/badge.svg
:target: https://codecov.io/gh/silviolleite/django-pwa
.. |PyPI - Downloads| image:: https://img.shields.io/pypi/dm/django-pwa.svg
:target: https://pypi.org/project/django-pwa/
.. |PyPI - Downloads| image:: https://img.shields.io/pypi/v/django-pwa.svg
:target: https://pypi.org/project/django-pwa
.. |PyPI - Downloads| image:: https://img.shields.io/pypi/djversions/django-pwa.svg
:target: https://pypi.org/project/django-pwa
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
| Filename, size | File type | Python version | Upload date | Hashes |
|---|---|---|---|---|
| Filename, size django_pwa-1.0.5-py3-none-any.whl (343.4 kB) | File type Wheel | Python version py3 | Upload date | Hashes View hashes |
| Filename, size django-pwa-1.0.5.tar.gz (337.0 kB) | File type Source | Python version None | Upload date | Hashes View hashes |
Close
Hashes for django_pwa-1.0.5-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | ef093fda3028bdc99853cdd09844914fc223e64b0a98be4d4da2f44ba72b2761 |
|
| MD5 | bb5c2f9150eaef2bb66473bcab925889 |
|
| BLAKE2-256 | dbfbf07e4565429a6436da001c2c08fd7a5d3399eb639bcba69ffe8e578004db |
