From 6af122f6534d18876dcf601cffebc327ad1fdaf4 Mon Sep 17 00:00:00 2001 From: Florent Morselli Date: Wed, 10 Jan 2024 17:50:14 +0100 Subject: [PATCH] Documentation updated --- README.md | 146 +++++++++++----------- src/DependencyInjection/Configuration.php | 4 - tests/config.php | 3 +- 3 files changed, 76 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index affc8b5..1e38b37 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ Progressive Web App for Symfony This bundle provides the [spomky-labs/phpwa](https://github.com/spomky-labs/phpwa) bundle for Symfony. This will help you to generate Progressive Web Apps (PWA) Manifests and assets (icons or screenshots). +Also, it will help you to generate Service Workers based on [Workbox](https://developers.google.com/web/tools/workbox). Please have a look at the [Web app manifests](https://developer.mozilla.org/en-US/docs/Web/Manifest) for more information about Progressive Web Apps. @@ -44,11 +45,11 @@ A Service Worker can be used to provide offline capabilities to the application The bundle is able to generate a manifest from a configuration file. The manifest members defined in the [Web app manifests](https://developer.mozilla.org/en-US/docs/Web/Manifest) are supported -without any change, with the exception of members `icons`, `screenshots` and `shortcuts` (see below). +without any change, with the exception of some members described in the following sections. ```yaml # config/packages/phpwa.yaml -phpwa: +pwa: name: 'My App' short_name: 'My App' description: 'My App description' @@ -76,50 +77,37 @@ When the configuration is set, you can generate the manifest with the following symfony console pwa:build ``` -The manifest will be generated in the `public` directory. -The manifest file name is `pwa.json` and the assets will leave in the `/public/pwa` folder by default. -You can change the output file name and the output folder with the following options: +By default, the manifest will be generated in the `public` directory with the name `/site.webmanifest`. +You can change the output file name and the output folder with the following configuration option: -* `--output` or `-o` to change the output file name (default: `pwa.json`) -* `--asset_folder` or `-a` to change the output folder (default: `/pwa`) -* `--public_folder` or `-p` to change the public folder (default: `%kernel.project_dir%/public`) -* `--url_prefix` or `-u` to change the URL prefix (default: ``) - -```bash -symfony console pwa:build --output=manifest.json +```yaml +# config/packages/phpwa.yaml +pwa: + manifest_filepath: '%kernel.project_dir%/public/sub-folder/pwa.json' ``` +### Using the Manifest + +The manifest can be used in your HTML pages with the following code in the `` section. +In you customized the output filename or the public folder, please replace `/site.webmanifest` with the path to your manifest file. -The URL prefix is used to generate the relative URLs in the manifest. -For instance, if your application root URL is https://example.com/foo/bar, set the URL prefix to `/foo/bar` and the manifest will be generated with relative URLs. - -```json -{ - "icons": [ - { - "src": "/foo/bar/pwa/icon-192x192.png", - "sizes": "192x192", - "type": "image/png" - }, - { - "src": "/foo/bar/pwa/icon-512x512.png", - "sizes": "512x512", - "type": "image/png" - } - ] -} +```html + ``` ### Manifest Icons The bundle is able to generate icons from a source image. +This is applicable to the application icons, shortcut icons or Windows 10 widget icons members of the manifest. The icons must be square and the source image should be at best quality as possible. To process the icons, you should set an icon processor. The bundle provides a GD processor and an Imagick processor. Depending on your system, you may have to install one extension or the other. +Please note that the icons of a size greater than 1024px may be ignored by the browser. + ```yaml # config/packages/phpwa.yaml -phpwa: +pwa: image_processor: 'pwa.image_processor.gd' # or 'pwa.image_processor.imagick' icons: - src: "%kernel.project_dir%/assets/images/logo.png" @@ -130,6 +118,23 @@ phpwa: purpose: 'maskable' - src: "%kernel.project_dir%/assets/images/logo.svg" sizes: [0] # 0 means `any` size and is suitable for vector images + shortcuts: + - name: "Shortcut 1" + short_name: "shortcut-1" + url: "/shortcut1" + description: "Shortcut 1 description" + icons: + - src: "%kernel.project_dir%/assets/images/shortcut1.png" + sizes: [48, 72, 96, 128, 144, 192, 256, 384, 512] + format: 'webp' + - name: "Shortcut 2" + short_name: "shortcut-2" + url: "/shortcut2" + description: "Shortcut 2 description" + icons: + - src: "%kernel.project_dir%/assets/images/shortcut2.png" + sizes: [48, 72, 96, 128, 144, 192, 256, 384, 512] + format: 'webp' ``` With the configuration above, the bundle will generate @@ -137,20 +142,27 @@ With the configuration above, the bundle will generate * 16 icons from the `mask.png` image. The format will be `png` and the purpose will be `maskable`. * And 1 icon from the `logo.svg` image. The format will be `svg` and the size will be `any`. +If the `format` member is present, the bundle will convert the image to the specified format. +In the example above, the `logo.png` image will be converted to `webp`, but the `mask.png` image will not be converted. + ### Manifest Screenshots The bundle is able to generate screenshots from a source image. +This is applicable to the application screenshots or Windows 10 widget screenshot members of the manifest. Similar to icons, the source image should be at best quality as possible. +You can select a folder where the source images are stored. +The bundle will automatically generate screenshots from all the images in the folder. + ```yaml # config/packages/phpwa.yaml -phpwa: +pwa: image_processor: 'pwa.image_processor.gd' # or 'pwa.image_processor.imagick' screenshots: - - src: "%kernel.project_dir%/assets/screenshots/narrow.png" - label: "View of the application home page" - - src: "%kernel.project_dir%/assets/screenshots/wide.png" - label: "View of the application home page" + - src: "%kernel.project_dir%/assets/screenshots/narrow/" + form_factor: "narrow" + - src: "%kernel.project_dir%/assets/screenshots/wide/" + form_factor: "wide" - src: "%kernel.project_dir%/assets/screenshots/android_dashboard.png" platform: 'android' format: 'webp' @@ -163,54 +175,31 @@ The `format` parameter is optional. It indicates the format of the generated ima ### Manifest Shortcuts -The `shortcuts` member may contain a list of icons. -The parameters are very similar to the `icons` member. +The `shortcuts` member may contain a list of action shortcuts that point to specific URLs in your application. +You can define URLs as relative paths or by using the route name. ```yaml # config/packages/phpwa.yaml -phpwa: - image_processor: 'pwa.image_processor.gd' # or 'pwa.image_processor.imagick' +pwa: shortcuts: - - name: "Shortcut 1" - short_name: "shortcut-1" - url: "/shortcut1" - description: "Shortcut 1 description" - icons: - - src: "%kernel.project_dir%/assets/images/shortcut1.png" - sizes: [48, 72, 96, 128, 144, 192, 256, 384, 512] - format: 'webp' - - name: "Shortcut 2" - short_name: "shortcut-2" - url: "/shortcut2" - description: "Shortcut 2 description" - icons: - - src: "%kernel.project_dir%/assets/images/shortcut2.png" - sizes: [48, 72, 96, 128, 144, 192, 256, 384, 512] - format: 'webp' -``` - -### Using the Manifest - -The manifest can be used in your HTML pages with the following code in the `` section. -In you customized the output filename or the public folder, please replace `pwa.json` with the path to your manifest file. - -```html - + - name: "Action 1" + short_name: "action-1" + url: "/action1" + description: "Action 1 description" + - name: "Action 2" + short_name: "action-2" + url: "app_action2" + description: "Use this route to generate the URL" ``` ## Service Worker -The following command will generate a Service Worker in the `public` directory. +The following command will generate a Service Worker in the `public` directory with the name `/sw.js`: ```bash symfony console pwa:sw ``` -You can change the output file name and the output folder with the following options: - -* `--output` or `-o` to change the output file name (default: `sw.js`) -* `--public_folder` or `-p` to change the public folder (default: `%kernel.project_dir%/public`) - Next, you have to register the Service Worker in your HTML pages with the following code in the `` section. It can also be done in a JavaScript file such as `app.js`. In you customized the output filename or the public folder, please replace `sw.js` with the path to your Service Worker file. @@ -225,11 +214,26 @@ In you customized the output filename or the public folder, please replace `sw.j ``` +The location of the Service Worker is important. It must be at the root of your application. +In addition, the `serviceworker.src` member of the manifest must be set to the same location. +The `serviceworker.scope` member may be set to the same location or to a sub-folder. +Do not forget to update the `scope` member in the JS configuration. + +```yaml +# config/packages/phpwa.yaml +pwa: + serviceworker: + filepath: '%kernel.project_dir%/public/sub-folder/service-worker.js' + src: '/sub-folder/service-worker.js' + scope: '/' +``` + ### Service Worker Configuration The Service Worker uses Workbox and comes with predefined configuration and recipes. You are free to change the configuration and the recipes to fit your needs. In particular, you can change the cache strategy, the cache expiration, the cache name, etc. +Please refer to the [Workbox documentation](https://developers.google.com/web/tools/workbox). # Support diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php index e4d39e4..0a4dd77 100644 --- a/src/DependencyInjection/Configuration.php +++ b/src/DependencyInjection/Configuration.php @@ -439,10 +439,6 @@ private function setupServiceWorker(ArrayNodeDefinition $node): void ->thenInvalid('The filename from the "filepath" and the "src" must be the same.') ->end() ->children() - ->booleanNode('generate') - ->defaultFalse() - ->info('Whether the service worker should be generated.') - ->end() ->scalarNode('filepath') ->defaultValue('%kernel.project_dir%/public/sw.js') ->info('The filename where the service worker will be generated.') diff --git a/tests/config.php b/tests/config.php index 349dccb..9df004e 100644 --- a/tests/config.php +++ b/tests/config.php @@ -192,8 +192,7 @@ ], 'handle_links' => 'auto', 'serviceworker' => [ - 'generate' => true, - 'src' => '/my-sw.js', + 'src' => '/sw/my-sw.js', 'filepath' => '%kernel.cache_dir%/samples/sw/my-sw.js', 'scope' => '/', 'use_cache' => true,