From 74bcb0654fe5563344906625ee15aaeb4b16153e Mon Sep 17 00:00:00 2001 From: Engincan VESKE Date: Mon, 6 Jun 2022 12:12:16 +0300 Subject: [PATCH 1/4] Add initial `Pwa Configuration` docs for Blazor --- docs/en/UI/Blazor/Pwa-Configuration.md | 130 +++++++++++++++++++++++++ docs/en/docs-nav.json | 4 + 2 files changed, 134 insertions(+) create mode 100644 docs/en/UI/Blazor/Pwa-Configuration.md diff --git a/docs/en/UI/Blazor/Pwa-Configuration.md b/docs/en/UI/Blazor/Pwa-Configuration.md new file mode 100644 index 0000000000..5a26f746fa --- /dev/null +++ b/docs/en/UI/Blazor/Pwa-Configuration.md @@ -0,0 +1,130 @@ +# PWA Configuration + +[PWAs (Progressive Web Apps)](https://web.dev/progressive-web-apps/) are developed using specific technologies to allow applications to take advantage of both web and native app features. + +Here the list of some features that PWA provides: + +- **Installable**: Web application can be installed and used like a native/desktop application. +- **Network Independent**: PWAs support offline scenerios. It can work offline or with a poor network connection. +- **Responsive**: It's usable on any devices such as mobile phones, tables, laptops, etc. +- and more... + +## Creating a Project with PWA Support + +You can create a new web application with PWA support for **Blazor WebAssembly** by using the `--pwa` option like below: + +```bash +abp new Acme.BookStore -t blazor --pwa +``` + +After this command, your application will be created and some additional PWA related files (such as **manifest**, **icons**, **service workers**, etc.) will be added. Then, you can get full advantages of web and native app features. + +## Adding PWA Support to an Existing Project + +If you started your application without PWA support, it's possible to change your mind and get benefit of PWA later. You only need to make some configurations as listed below: + +### 1-) Add `manifest.json` File + +> Web Application Manifest provides information about a web application in a JSON text file and it's required for the web application to be downloaded and be presented to the user similarly to a native application. + +First, you need to create a JSON file named **manifest.json** under the **wwwroot** folder and define some informations about your application. You can see an example **manifest.json** file content as below: + +```json +{ + "name": "MyProjectName", + "short_name": "MyCompanyName.MyProjectName", + "start_url": "./", + "display": "standalone", + "background_color": "#ffffff", + "theme_color": "#03173d", + "prefer_related_applications": false, + "icons": [ + { + "src": "icon-512.png", + "type": "image/png", + "sizes": "512x512" + }, + { + "src": "icon-192.png", + "type": "image/png", + "sizes": "192x192" + } + ] +} +``` + +- Some application specific informations should be defined in this file. +- For example, you can configure which icon need to be seen in which screen size, background color, etc. + +### 2-) Icons for Specific Screen Sizes (Optional) + +You can add some icons for your application to be seen in specific screen sizes and define in which screen sizes icons should be displayed in the **manifest.json** file. You can see the **icons** section in the **manifest.json** file to an example. + +> You can use, our default icons from [here](https://github.com/abpframework/abp/tree/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Blazor/wwwroot). + +### 3-) Configure Service Workers + +> Service workers are one of the fundamental part of PWAs. They enable fast loading (regardless of the network), offline access, push notifications, and other web/native app capabilities. They run in the background and doesn't block the main thread so they don't slow your application. + +You need to create `service-worker.js` and `service-worker.published.js` files under the **wwwroot** folder of your project. These files will be used by your project to determine which PWA features that you want to use. + +You can copy-paste the simple configurations for [service-worker.js](https://github.com/abpframework/abp/blob/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Blazor/wwwroot/service-worker.js) and [service-worker.published.js](https://github.com/abpframework/abp/blob/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Blazor/wwwroot/service-worker.published.js) files from our [template](https://github.com/abpframework/abp/tree/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Blazor/wwwroot). + +After the related service worker files added, then we need to define them in our `.csproj` file to notify our application. So open your `*.csproj` file and add the following content: + +```xml + + net6.0 + true + + + service-worker-assets.js + + + + + + +``` + +* With the `ServiceWorkerAssetsManifest` MSBuild property, your Blazor application generates a service worker assets manifest with the specified name. This file will be generated in the path of `/bin/Debug/{TARGET FRAMEWORK}/wwwroot/service-worker-assets.js` on runtime. This manifest can list, all resources such as images, stylesheets, JS files etc. by examining the `service-worker.published.js` file (regarding to your configurations in this file). +* `ServiceWorker` property is used to define which files need to be accounted as **Service Worker** files. These files are used to determine which PWA features should be used. + + +### 4-) Define Web Application Manifest and Register Service Workers + +Finally, now you can define `manifest.json` file and **icons** in the **index.html** file and register the **service workers** for your application. + +Let's start with adding `` elements (between `` tags) for the manifest and app icon in the **index.html** file (under the **wwwroot** folder): + +```html + + + + + + +``` + +Then, add the following ` + +``` + +You've added the related files and making the related configurations with this final touch to add PWA support to your existing application. Now, you can take advantage of PWA. + +## Differences Between the Debug and Release Service Workers + +## Customizations + +### Customize Web Application Manifest + +### Customize Service Workers \ No newline at end of file diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 070d390ff5..c366dc8a7b 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -923,6 +923,10 @@ { "text": "Routing", "path": "UI/Blazor/Routing.md" + }, + { + "text": "PWA Configuration", + "path": "UI/Blazor/Pwa-Configuration.md" } ] }, From 034c370b181450129a31dcd62a8812ee46dce893 Mon Sep 17 00:00:00 2001 From: Engincan VESKE Date: Mon, 6 Jun 2022 15:00:56 +0300 Subject: [PATCH 2/4] Complete PWA documentation for Blazor --- docs/en/UI/Blazor/Pwa-Configuration.md | 161 +++++++++++++++++++++---- 1 file changed, 138 insertions(+), 23 deletions(-) diff --git a/docs/en/UI/Blazor/Pwa-Configuration.md b/docs/en/UI/Blazor/Pwa-Configuration.md index 5a26f746fa..d941a8e594 100644 --- a/docs/en/UI/Blazor/Pwa-Configuration.md +++ b/docs/en/UI/Blazor/Pwa-Configuration.md @@ -2,12 +2,11 @@ [PWAs (Progressive Web Apps)](https://web.dev/progressive-web-apps/) are developed using specific technologies to allow applications to take advantage of both web and native app features. -Here the list of some features that PWA provides: +Here is the list of some features that PWA provides: -- **Installable**: Web application can be installed and used like a native/desktop application. -- **Network Independent**: PWAs support offline scenerios. It can work offline or with a poor network connection. -- **Responsive**: It's usable on any devices such as mobile phones, tables, laptops, etc. -- and more... +- **Installable**: A web application can be installed and used like a native/desktop application. +- **Network Independent**: PWAs support offline scenarios. It can work offline or with a poor network connection. +- **Responsive**: It's usable on any devices such as mobile phones, tablets, laptops, etc. ## Creating a Project with PWA Support @@ -21,13 +20,13 @@ After this command, your application will be created and some additional PWA rel ## Adding PWA Support to an Existing Project -If you started your application without PWA support, it's possible to change your mind and get benefit of PWA later. You only need to make some configurations as listed below: +If you started your application without PWA support, it's possible to change your mind and get the benefit of PWA later. You only need to make some configurations as listed below: ### 1-) Add `manifest.json` File > Web Application Manifest provides information about a web application in a JSON text file and it's required for the web application to be downloaded and be presented to the user similarly to a native application. -First, you need to create a JSON file named **manifest.json** under the **wwwroot** folder and define some informations about your application. You can see an example **manifest.json** file content as below: +First, you need to create a JSON file named **manifest.json** under the **wwwroot** folder and define some pieces of information about your application. You can see an example **manifest.json** file content below: ```json { @@ -53,24 +52,24 @@ First, you need to create a JSON file named **manifest.json** under the **wwwroo } ``` -- Some application specific informations should be defined in this file. -- For example, you can configure which icon need to be seen in which screen size, background color, etc. +- Some application specific information should be defined in this file. +- For example, you can configure which icon needs to be seen in which screen size, background color, description, etc. -### 2-) Icons for Specific Screen Sizes (Optional) +### 2-) Add Icons for Specific Screen Sizes (Optional) -You can add some icons for your application to be seen in specific screen sizes and define in which screen sizes icons should be displayed in the **manifest.json** file. You can see the **icons** section in the **manifest.json** file to an example. +You can add some icons for your application to be seen in specific screen sizes and define in which screen sizes icons should be displayed in the **manifest.json** file. You can see the **icons** section in the **manifest.json** file as an example above. -> You can use, our default icons from [here](https://github.com/abpframework/abp/tree/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Blazor/wwwroot). +> You can use, default icons from our [template](https://github.com/abpframework/abp/tree/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Blazor/wwwroot). ### 3-) Configure Service Workers -> Service workers are one of the fundamental part of PWAs. They enable fast loading (regardless of the network), offline access, push notifications, and other web/native app capabilities. They run in the background and doesn't block the main thread so they don't slow your application. +> Service workers are one of the fundamental parts of PWAs. They enable fast loading (regardless of the network), offline access, push notifications, and other web/native app capabilities. They run in the background and don't block the main thread so they don't slow your application. -You need to create `service-worker.js` and `service-worker.published.js` files under the **wwwroot** folder of your project. These files will be used by your project to determine which PWA features that you want to use. +You need to create `service-worker.js` and `service-worker.published.js` files under the **wwwroot** folder of your project. These files will be used by your project to determine which PWA features you want to use. -You can copy-paste the simple configurations for [service-worker.js](https://github.com/abpframework/abp/blob/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Blazor/wwwroot/service-worker.js) and [service-worker.published.js](https://github.com/abpframework/abp/blob/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Blazor/wwwroot/service-worker.published.js) files from our [template](https://github.com/abpframework/abp/tree/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Blazor/wwwroot). +You can get the simple configurations for [service-worker.js](https://github.com/abpframework/abp/blob/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Blazor/wwwroot/service-worker.js) and [service-worker.published.js](https://github.com/abpframework/abp/blob/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Blazor/wwwroot/service-worker.published.js) files from our [template](https://github.com/abpframework/abp/tree/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Blazor/wwwroot). -After the related service worker files added, then we need to define them in our `.csproj` file to notify our application. So open your `*.csproj` file and add the following content: +After the related service worker files are added, then we need to define them in our `.csproj` file to notify our application. So open your `*.csproj` file and add the following content: ```xml @@ -88,12 +87,12 @@ After the related service worker files added, then we need to define them in our ``` * With the `ServiceWorkerAssetsManifest` MSBuild property, your Blazor application generates a service worker assets manifest with the specified name. This file will be generated in the path of `/bin/Debug/{TARGET FRAMEWORK}/wwwroot/service-worker-assets.js` on runtime. This manifest can list, all resources such as images, stylesheets, JS files etc. by examining the `service-worker.published.js` file (regarding to your configurations in this file). -* `ServiceWorker` property is used to define which files need to be accounted as **Service Worker** files. These files are used to determine which PWA features should be used. +* `ServiceWorker` property is used to define which files need to be accounted as **Service Worker** files and service workers are used to determine which PWA features should be used. ### 4-) Define Web Application Manifest and Register Service Workers -Finally, now you can define `manifest.json` file and **icons** in the **index.html** file and register the **service workers** for your application. +Finally, now you can define the `manifest.json` file and **icons** in the **index.html** file and register the **service workers** for your application. Let's start with adding `` elements (between `` tags) for the manifest and app icon in the **index.html** file (under the **wwwroot** folder): @@ -119,12 +118,128 @@ Then, add the following `