django-simple-pwa

این اپ یک راهکار سریع برای ایجاد و کنترل اپ PWA برای وب سایت شماست.

لطفا ما را برای ترجمه‌ی مستندات به زبان محلی خود یاری کنید.

فهرست محتوا

شروع سریع

نصب

ابتدا DSP (django-simple-pwa) را با دستور زیر نصب کنید

1pip install django-simple-pwa

حال DSP را به اپ‌های نصب شده اضافه کنید.

1#<my_project/settings.py>
2
3INSTALLED_APPS = [
4        #...
5        'pwa',
6        #...
7]

تنظیمات

حال urlهای DSP را به urls.py که در کنار setting.py واقع است به شکل زیر اضافه کنید.

1#<my_project/urls.py>
2
3from django.urls import path, include
4urlpatterns = [
5        #...
6        path('', include('pwa.urls')),
7        #...
8]

مهم است که محل فایل‌های استاتیک را در تنظمیات خود معرفی کنید.

1#<my_project/settings.py>
2
3from os.path import join
4
5STATIC_URL = '/static/'
6STATIC_ROOT = str(join(BASE_DIR, 'static'))
7STATICFILES_DIRS = ( str(join(BASE_DIR, 'static_files')), )

همچنین فرمان ./manage.py collectstatic را اجرا کنید.

اجرا در لوکال هاست

در صورتی که پروژه‌ را در لوکال هاست خود اجرا می‌کنید، مطمئن شوید که فایل‌های استاتیک به درستی لود شده‌اند.

1#<my_project/urls.py>
2from django.conf.urls.static import static
3from django.conf import settings
4
5urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

لود کردن فایل‌های ضروری

حال در فایل html اصلی خود که عموما به نام index.html شناخته می‌شود، متا دیتا‌های اپ را لود کنید.

1{% load pwa %}
2<head>
3        {% pwa_meta_data %}
4</head>
5<body>
6
7        {% pwa_meta_script %}
8</body>

توجه

همچین می‌توانید این تنظیمات را در تمام صفحات اعمال کنید تا از طریق همه آن‌ها pwa در دسترس باشد.

اگر همه مراحل را به درستی انجام داده باشید میتوانید اکنون سایت خود را بر روی دستگاه خود به صورت pwa نصب کنید.

شخصی سازی

ساختار پیش فرض

DSP از یک ساختار پیشفرض برای تولید manifest.json استفاده می‌کند.

 1#<pwa/defaults.py>
 2
 3DEFAULT_CONFIG = {
 4        "name": "Progressive Web Application",
 5        "short_name": "PWA",
 6        "theme_color": "#7820f5",
 7        "background_color": "#7820f5",
 8        "display": "standalone",
 9        "orientation": "portrait",
10        "scope": "/",
11        "start_url": "/",
12        "icons": [
13                {
14                        "src": "/static/pwa/icons/72x72.png",
15                        "type": "image/png",
16                        "sizes": "72x72"
17                },
18                {
19                        "src": "/static/pwa/icons/96x96.png",
20                        "type": "image/png",
21                        "sizes": "96x96"
22                },
23                {
24                        "src": "/static/pwa/icons/128x128.png",
25                        "type": "image/png",
26                        "sizes": "128x128"
27                },
28                {
29                        "src": "/static/pwa/icons/144x144.png",
30                        "type": "image/png",
31                        "sizes": "144x144"
32                },
33                {
34                        "src": "/static/pwa/icons/152x152.png",
35                        "type": "image/png",
36                        "sizes": "152x152"
37                },
38                {
39                        "src": "/static/pwa/icons/192x192.png",
40                        "type": "image/png",
41                        "sizes": "192x192"
42                },
43                {
44                        "src": "/static/pwa/icons/384x384.png",
45                        "type": "image/png",
46                        "sizes": "384x384"
47                },
48                {
49                        "src": "/static/pwa/icons/512x512.png",
50                        "type": "image/png",
51                        "sizes": "512x512"
52                }
53                ],
54        "lang": "en",
55        "dir": "ltr",
56        "description": "Progressive Web app powerd by Django",
57        "version": "1.",
58        "manifest_version": "1.0",
59        "permissions": [
60                "notifications",
61                "webRequest"
62        ],
63        "author": "PWA-django"
64}

تغییر پیش فرض

برای شخصی‌سازی فایل manifest.json app.js sw.js کافیست متغیر PWA_CONFIG PWA_SW PWA_APP را در فایل settings.py تعریف کنید.

1#<my_project/settings.py>
2
3PWA_CONFIG = {
4# ...
5"name": "Progressive Web Application"
6# ...
7}
8PWA_APP = """// js code here"""
9PWA_SW = """// js code here"""

هشدار

توجه داشته باشید که هیچ یک از دو آیکون شما دارای سایز برابر نباشند.

برای مثال ساختار زیر باعث ایجاد خطا در برنامه میشود.

 1{
 2        "src": "/static/pwa/icons/144x144.png",
 3        "type": "image/png",
 4        "sizes": "144x144"
 5},
 6{
 7        "src": "/static/pwa/icons/144x144.ico",
 8        "type": "image/x-icon",
 9        "sizes": "144x144"
10},

توجه

این بدین معنی است که لزوما تغییر فرمت موجب جلوگیری از خطا نمی‌شود.

توجه

همچنین ما توصیه نمی‌کنیم که PWA_APP و PWA_SW را دوباره تعریف کنید مگر آنکه بدانید واقعا چه می‌کنید.

شما میتوانید آیکون‌های خود را در سایزهای مختلف با فرمت‌های دلخواه خود به صورت فوق تعریف کنید اما ما توصیه میکنیم از فرمت .ico استفاده کنید.

تغییر manifest.json

برای این کار PWA_CONFIG را به settings.py اضافه کنید.

 1#<my_project/settings.py>
 2
 3PWA_CONFIG = {
 4        "name": "My Costum Name",
 5        "short_name": "MCN",
 6        "theme_color": "#fff",
 7        "background_color": "#f0f0f0",
 8        "display": "standalone",
 9        "orientation": "portrait",
10        "scope": "/",
11        "start_url": "/",
12        "icons": [
13                {
14                        "src": "/static/pwa/icons/72x72.png",
15                        "type": "image/png",
16                        "sizes": "72x72"
17                },
18                {
19                        "src": "/static/pwa/icons/96x96.png",
20                        "type": "image/png",
21                        "sizes": "96x96"
22                },
23                {
24                        "src": "/static/pwa/icons/128x128.png",
25                        "type": "image/png",
26                        "sizes": "128x128"
27                },
28                {
29                        "src": "/static/pwa/icons/144x144.png",
30                        "type": "image/png",
31                        "sizes": "144x144"
32                },
33                {
34                        "src": "/static/pwa/icons/152x152.png",
35                        "type": "image/png",
36                        "sizes": "152x152"
37                },
38                {
39                        "src": "/static/pwa/icons/192x192.png",
40                        "type": "image/png",
41                        "sizes": "192x192"
42                },
43                {
44                        "src": "/static/pwa/icons/384x384.png",
45                        "type": "image/png",
46                        "sizes": "384x384"
47                },
48                {
49                        "src": "/static/pwa/icons/512x512.png",
50                        "type": "image/png",
51                        "sizes": "512x512"
52                }
53                ],
54        "lang": "en",
55        "dir": "ltr",
56        "description": "Progressive Web app powerd by Django",
57        "version": "1.",
58        "manifest_version": "1.0",
59        "permissions": [
60                "notifications",
61                "webRequest"
62        ],
63        "author": "PWA-django"
64}
مقادیر قابل قبول manifest.json

ما در اینجا برخی از مواردی که یک PWA میتواند در فایل manifest.json خود داشته باشد را به صورت پیشفرض برای اپ خود تعریف کرده‌ایم و در ادامه به تعریف مقادیری که میتوانید برای آن‌ها لحاظ کنید می‌پردازیم.

 1{
 2"name": 'The name of application',
 3"short_name": "Short name; Can be same with name",
 4"theme_color": "The hex color for app theme",
 5"background_color": "The hex color for app background color",
 6"display": "fullscreen [OR] standalone [OR] minimal-ui [OR] browser",
 7"orientation": "any [OR] natural [OR] landscape [OR] landscape-primary [OR] landscape-secondary [OR] portrait [OR] portrait-primary [OR] portrait-secondary",
 8"scope": "/app/ [OR] https://example.com/ [OR] https://example.com/subdirectory/",
 9"start_url": "/ [OR] https://example.com [OR] ../startpoint.html",
10"icons": "the list of dictionery that contains **src** and **sizes** and **type**"
11"lang": "langueage code like fa [OR] en [OR] tu [OR] fn [OR] ge [OR] ...",
12"dir": "rtl [OR] ltr [OR] auto",
13"description": "Description pf your app",
14"version": "app version",
15"manifest_version": "manifest.json file vertion if change on updating app",
16"permissions": `list here <https://developer.chrome.com/docs/extensions/mv2/declare_permissions/>`_
17"author": "author name or title of app"
18
19}

توجه

برای اطلاعات بیشتر می‌توانید به برخی مستندات آن که در لیست زیر فراهم کردیم بپردازید:

تغییر ServiceWorker.js

برای این کار PWA_SW را در settings.py به یکی از دو روش زیر تعریف کنید.

1PWA_SW = """// js code here """

1SW = open('/path/to/ServiceWorker.js', "r")
2PWA_SW = SW.read()
3SW.close()

توجه

برای اطلاعات بیشتر نسبت به نحوه‌ی کارکرد ServiceWorker.js می‌توانید از منابع زیر استفاده کنید.

تغییر app.js

برای این کار کافیست متغییر PWA_APP را در فایل settings.py تعریف کنید.

1PWA_SW = """// js code here """

1APP = open('/path/to/app.js', "r")
2PWA_SW = APP.read()
3APP.close()

توجه

همچنان توصیه نمی‌کنیم که PWA_APP و PWA_SW را دوباره تعریف کنید مگر آن که بدانید واقعا چه می‌کنید.

تغییر محتوای صفحه‌ی آفلاین

ما از ساختاری مشابه ساختار جنگو برای تغییر صفحه‌ی آفلاین استفاده می‌کنیم. به طوری که برای تغییر آن می‌بایست ابتدا در مسیر <templates-dir>/pwa/ یک فایل با نام offline.html ایجاد کنید و سپس آن را در مسیر pwa/pwa_offline.html اکستند کنید.

1<!-- <templates-dir/pwa/offline.html> -->
2
3{% extend 'pwa/pwa_offline.html' %}
4
5{% block title %} title {% endblock title %}
6{% block main %} something {% endblock main %}

توجه

ما به طور پیش‌فرض از بوت‌استرپ در قسمت آفلاین سایت استفاده می‌کنیم با این حال میتوانید به صورت زیر فایل‌های css و js خود را در آن بارگذاری کنید.

1{% block extrastyles %} <!-- your css here --> {% endblock extrastyles %}
2
3{% block extrascripts %} <!-- your js here --> {% endblock extrascripts %}

هشدار

توجه داشته باشید با اعمال قطعه کد بالا دیگر بوت استرپ در صفحه اعمال نخواهد شد.

درضمن هرگونه تغییر در فایل آفلاین باید با تغییر کش در ServiceWorker.js همراه باشد. بنابراین در صورتی که فایل آفلاین را تغییر دادید نیاز است که PWA_SW را نیز تعریف کنید هرچند ممکن است بدون این کار هم برنامه کار بکند ولی بهتر است که ServiceWorker.js باز نویسی شود.

خطا و ارورها

در صورتی که با خطای زیر مواجه شدید آیکون‌های خود را به صورت صحیح آدرس دهی کنید. همچنین مطمئن شوید هیچ یک از دو آیکون شما دارای سایز برابر نمی‌باشند حتی اگر فرمت متفاوتی دارند.

error.png

عدم نمایش دکمه نصب

در صورتی که دکمه نصب نمایش داده نشد، مطمئن شوید که سرور بر روی لوکال هاست و یا HTTPS اجرا میشود. اجرای سرور بر روی شبکه NAT نیازمند دارا بودن گواهی SSL معتبر است. این موضوع به django-simple-pwa مربوط نیست و به ساختار PWA مربوط می‌شود.