Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat(docs) add all the icon information #4100

Merged
merged 2 commits into from May 13, 2019
Merged

feat(docs) add all the icon information #4100

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b1e061b
feat(docs) Add information about all the icons.
nothingismagick May 12, 2019
aa9b9d3
Merge branch 'dev' into feat/docs/icons
nothingismagick May 12, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
28 changes: 28 additions & 0 deletions docs/src/assets/menu.js
View file
Open in desktop
Expand Up @@ -49,6 +49,10 @@ const options = [
name: 'Vue Prototype Injections',
path: 'vue-prototype-injections'
},
{
name: 'App Icons',
path: 'app-icons'
},
{
name: 'Quasar Language Packs',
path: 'quasar-language-packs'
Expand Down Expand Up @@ -115,6 +119,10 @@ const cli = [
name: 'quasar.conf.js',
path: 'quasar-conf-js'
},
{
name: 'App Icons',
path: 'app-icon-details'
},
{
name: 'Testing & Auditing',
path: 'testing-and-auditing'
Expand Down Expand Up @@ -190,6 +198,10 @@ const cli = [
name: 'Introduction',
path: 'introduction'
},
{
name: 'App Icons for SPA',
path: 'app-icons-spa'
},
{
name: 'Build Commands',
path: 'build-commands'
Expand All @@ -216,6 +228,10 @@ const cli = [
name: 'Configuring SSR',
path: 'configuring-ssr'
},
{
name: 'App Icons for SSR',
path: 'app-icons-ssr'
},
{
name: 'Client Side Hydration',
path: 'client-side-hydration'
Expand Down Expand Up @@ -254,6 +270,10 @@ const cli = [
name: 'Configuring PWA',
path: 'configuring-pwa'
},
{
name: 'App Icons for PWA',
path: 'app-icons-pwa'
},
{
name: 'Handling Service Worker',
path: 'handling-service-worker'
Expand All @@ -280,6 +300,10 @@ const cli = [
name: 'Configuring Cordova',
path: 'configuring-cordova'
},
{
name: 'App Icons for Cordova',
path: 'app-icons-cordova'
},
{
name: 'Cordova Plugins',
path: 'cordova-plugins'
Expand Down Expand Up @@ -318,6 +342,10 @@ const cli = [
name: 'Configuring Electron',
path: 'configuring-electron'
},
{
name: 'App Icons for Electron',
path: 'app-icons-electron'
},
{
name: 'Electron Packages',
path: 'electron-packages'
Expand Down
32 changes: 32 additions & 0 deletions docs/src/pages/options/app-icons.md
View file
Open in desktop
@@ -0,0 +1,32 @@
---
title: App Icons
---

You love the Quasar logo probably as much as the team does, but you just spent what feels like a lifetime making your own pixel-perfect representation of the soul of your application.

There are many different situations where your icon might be seen: In the browser tab, on the desktop and even in an App Store.

And so now you need your logo in about 80 different sizes with representative names, arcane formats, placed in the right folders and probably some proper `<xml>` declarations for Cordova too. Even if you know exactly what you are doing, this is tedious and error prone. However, if you are using the Quasar CLI, your life is easy and care-free - because Quasar and the **Icon Factory** app-extension make it dead simple.

We have collected the all the important information here: [Quasar CLI > App icons](/quasar-cli/app-icon-details) - but if you just want to "set it and forget it", here's what you need to know:

## Icon Factory

Check out the [Icon Factory repository](https://github.com/quasarframework/app-extension-icon-factory/blob/dev/README.md) for explicit details about how it works, or just dive in and install it into your project like [any app extension](/app-extensions/introduction):
```bash
$ quasar ext add @quasar/icon-factory
```

It will ask you to tell it where it can find the source image (1240x1240) and which minification strategy you want to use. Then when you run `$ quasar dev` - it will produce the right icons and put them in all the right places for you, no matter what `--mode` you are using; if you are just serving an HMR locally or producing final assets with `build`.

## Not using Quasar CLI yet?

You'll have to convert, resize, name and place your files wherever they are, and depending on how you build your application that could be anywhere.

For devs in this situation, we provide the option for you to install the Icon Factory globally as an npm module and use it to just produce the icons you need:
```bash
$ npm install --global @quasar/app-extension-icon-factory
$ iconfactory -p=kitchensink -s=icon-1280x1280.png -t=./outputFolder -m=pngquant
```

Full details about this type of usage can be found at the app-extension repository.
203 changes: 203 additions & 0 deletions docs/src/pages/quasar-cli/app-icon-details.md
View file
Open in desktop
@@ -0,0 +1,203 @@
---
title: App Icon Details
---

If you were to target all platforms that Quasar currently supports, you will need to make around 80 different files of 4 different media types (png, ico, icns and svg). If you just use a tool like Gimp, Photoshop or Affinity Designer, you will find that these files are rather large and the process of making them and naming them is prone to operator error. You will probably want to compress the PNG files at least, and also remove unnecessary app-metadata from the SVG.

This page documents all of the icons you will need for each of the build targets.


<img src="https://cdn.quasar-framework.org/img/iconfactory.png" style="float:right;max-width:15%;min-width:240px;padding-top:40px" />

## The Icon Factory

::: tip
We highly recommend using the Icon Factory app extension, because it consumes a source icon and automatically clones, scales, minifies and places the icons in the appropriate directories for you. When you change this source file (or some of the extension's settings) the icons will be automatically rebuilt on the next dev or build command.
:::


You will have to place the source image as a png with transparancy (1240x1240) in the source folder and choose which minification strategy you want to use. Then when you run `$ quasar dev` - it will produce the right icons and put them in all the right places for you, no matter what `--mode` you are using; if you are just serving an HMR locally or producing final assets with `build`.

Check out the [Icon Factory repository](https://github.com/quasarframework/app-extension-icon-factory/blob/dev/README.md) for explicit details about how it works, or just dive in and install it into your project like [any app extension](/app-extensions/introduction) (and follow the instructions):

```bash
$ quasar ext add @quasar/icon-factory
```

## Build Targets

::: warning
All of these filenames are important and non-negotiable (because of either the build target or Quasar's mapping to the respective dist targets, so don't think its okay to change any of them to something else.
:::

### SPA, PWA & SSR
These build targets are classical websites, and include a variety of special icons for individual browsers and operating systems. You need all of them - and if you discover one that is new or missing, please open an issue.

```text
src/
statics/
app-logo-128x128.png
icons/
apple-icon-120x120.png
apple-icon-152x152.png
apple-icon-167x167.png
apple-icon-180x180.png
favicon-16x16.png
favicon-32x32.png
favicon-96x96.png
favicon.ico
icon-128x128.png
icon-192x192.png
icon-256x256.png
icon-384x384.png
icon-512x512.png
ms-icon-144x144.png
safari-pinned-tab.svg
```


### Cordova

Cordova is the most complicated of the build targets, because not only do you need to place the icons in specific folders, you also need to register them in the `src-cordova/config.xml` file. Further, if you are using splashscreens (which you should), you will also need to install `cordova-plugin-splashscreen` and register it in your config.xml - unless of course you are using the Icon Factory, in which case that is all taken care of for you.

```shell
$ cd src-cordova
$ cordova plugin add cordova-plugin-splashscreen
$ cordova plugin save
$ cd ..
```

```text
src-cordova/
config.xml
res/
android/
icon-36-ldpi.png
icon-48-mdpi.png
icon-72-hdpi.png
icon-96-xhdpi.png
icon-144-xxhdpi.png
icon-192-xxxhdpi.png
ios/
icon.png
icon-2x.png
icon-40.png
icon-40-2x.png
icon-50.png
icon-50-2x.png
icon-60.png
icon-60-2x.png
icon-60-3x.png
icon-72.png
icon-72-2x.png
icon-83.5-2x.png
icon-167.png
icon-1024.png
screen/
android/
screen-hdpi-landscape.png
screen-ldpi-portrait.png
screen-mdpi-landscape.png
screen-mdpi-portrait.png
screen-hdpi-landscape.png
screen-hdpi-portrait.png
screen-xhdpi-landscape.png
screen-xhdpi-portrait.png
screen-xxhdpi-landscape.png
screen-xxhdpi-portrait.png
screen-xxxhdpi-landscape.png
screen-xxxhdpi-portrait.png
ios/
screen-ipad-landscape.png
screen-ipad-landscape-2x.png
screen-ipad-portrait.png
screen-ipad-portrait-2x.png
screen-iphone-portrait.png
screen-iphone-portrait-2x.png
screen-iphone-landscape.png
screen-iphone-landscape-2x.png
screen-iphone-portrait-568h_2x.png
Default@2x~universal~anyany.png
```

And here is what your config.xml should look like:

```xml
<platform name="android">
<icon density="ldpi" src="res/android/icon-36-ldpi.png" />
<icon density="mdpi" src="res/android/icon-48-mdpi.png" />
<icon density="hppi" src="res/android/icon-72-hdpi.png" />
<icon density="xhdpi" src="res/android/icon-96-xhdpi.png" />
<icon density="xxhdpi" src="res/android/icon-144-xxhdpi.png" />
<icon density="xxxhdpi" src="res/android/icon-192-xxxhdpi.png" />
<splash density="land-ldpi" src="res/screen/android/screen-ldpi-landscape.png" />
<splash density="port-ldpi" src="res/screen/android/screen-ldpi-portrait.png" />
<splash density="land-mdpi" src="res/screen/android/screen-mdpi-landscape.png" />
<splash density="port-mdpi" src="res/screen/android/screen-mdpi-portrait.png" />
<splash density="land-hdpi" src="res/screen/android/screen-hdpi-landscape.png" />
<splash density="port-hdpi" src="res/screen/android/screen-hdpi-portrait.png" />
<splash density="land-xhdpi" src="res/screen/android/screen-xhdpi-landscape.png" />
<splash density="port-xhdpi" src="res/screen/android/screen-xhdpi-portrait.png" />
<splash density="land-xxhdpi" src="res/screen/android/screen-xxhdpi-landscape.png" />
<splash density="port-xxhdpi" src="res/screen/android/screen-xxhdpi-portrait.png" />
<splash density="land-xxxhdpi" src="res/screen/android/screen-xxxhdpi-landscape.png" />
<splash density="port-xxxhdpi" src="res/screen/android/screen-xxxhdpi-portrait.png" />
</platform>
<platform name="ios">
<icon height="57" src="res/ios/icon.png" width="57" />
<icon height="114" src="res/ios/icon-2x.png" width="114" />
<icon height="40" src="res/ios/icon-40.png" width="40" />
<icon height="80" src="res/ios/icon-40-2x.png" width="80" />
<icon height="50" src="res/ios/icon-50.png" width="50" />
<icon height="100" src="res/ios/icon-50-2x.png" width="100" />
<icon height="60" src="res/ios/icon-60.png" width="60" />
<icon height="120" src="res/ios/icon-60-2x.png" width="120" />
<icon height="180" src="res/ios/icon-60-3x.png" width="180" />
<icon height="72" src="res/ios/icon-72.png" width="72" />
<icon height="144" src="res/ios/icon-72-2x.png" width="144" />
<icon height="167" src="res/ios/icon-83.5-2x.png" width="167" />
<icon height="167" src="res/ios/icon-167.png" width="167" />
<icon height="1024" src="res/ios/icon-1024.png" width="1024" />
<splash height="768" src="res/screen/ios/screen-ipad-landscape.png" width="1024" />
<splash height="1536" src="res/screen/ios/screen-ipad-landscape-2x.png" width="2048" />
<splash height="1024" src="res/screen/ios/screen-ipad-portrait.png" width="768" />
<splash height="2048" src="res/screen/ios/screen-ipad-portrait-2x.png" width="1536" />
<splash height="320" src="res/screen/ios/screen-iphone-landscape.png" width="480" />
<splash height="640" src="res/screen/ios/screen-iphone-landscape-2x.png" width="960" />
<splash height="480" src="res/screen/ios/screen-iphone-portrait.png" width="320" />
<splash height="960" src="res/screen/ios/screen-iphone-portrait-2x.png" width="640" />
<splash height="1136" src="res/screen/ios/screen-iphone-portrait-568h_2x.png" width="640" />
<splash height="2732" src="res/screen/ios/Default@2x~universal~anyany.png" width="2732" />
</platform>
<plugin name="cordova-plugin-splashscreen" spec="^5.0.2" />
```


### Electron
These images are used to display the icon of the application in the desktop operating system in the tray, on the desktop, in the file-browser and in relevant stores. The `icon.ico` file is for Windows and `icon.icns` is for MacOS. If you discover any that are missing, please file an issue.

```text
src-electron/
icons/
icon.ico
icon.icns
icon.png
linux-16x16.png
linux-24x24.png
linux-32x32.png
linux-48x48.png
linux-64x64.png
linux-96x96.png
linux-128x128.png
linux-512x512.png
Square30x30Logo.png
Square44x44Logo.png
Square71x71Logo.png
Square89x89Logo.png
Square107x107Logo.png
Square142x142Logo.png
Square150x150Logo.png
Square284x284Logo.png
Square310x310Logo.png
StoreLogo.png
```
32 changes: 32 additions & 0 deletions docs/src/pages/quasar-cli/developing-electron-apps/app-icons-electron.md
View file
Open in desktop
@@ -0,0 +1,32 @@
---
title: App Icons for Electron
---

### Electron
These images are used to display the icon of the application in the desktop operating system in the tray, on the desktop, in the file-browser and in relevant stores. The `icon.ico` file is for Windows and `icon.icns` is for MacOS. If you discover any that are missing, please file an issue.

```text
src-electron/
icons/
icon.ico
icon.icns
icon.png
linux-16x16.png
linux-24x24.png
linux-32x32.png
linux-48x48.png
linux-64x64.png
linux-96x96.png
linux-128x128.png
linux-512x512.png
Square30x30Logo.png
Square44x44Logo.png
Square71x71Logo.png
Square89x89Logo.png
Square107x107Logo.png
Square142x142Logo.png
Square150x150Logo.png
Square284x284Logo.png
Square310x310Logo.png
StoreLogo.png
```