.. django-xicon .. README.rst

A django-xicon documentation

|GitHub| |Coveralls| |pypi-license| |pypi-version| |pypi-python-version| |pypi-django-version| |pypi-format| |pypi-wheel| |pypi-status|_

*django-xicon is a Django reusable application to handle a modern bunch of site icons*

.. contents::

Nowadays <link rel="shortcut icon" href="https://github.com/vint21h/django-xicon/blob/master/favicon.ico" type="image/x-icon" sizes="16x16"/> is not enough for good site or web application. Apple <https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html>, Microsoft <https://technet.microsoft.com/en-us/windows/dn320426(v=vs.60)#MainContent> and Google <https://developers.google.com/web/fundamentals/web-app-manifest/>_ creates their own standards. django-xicon solve the boring problem of reading and implementing of these standards requirements through fast and simple Django project configuration. These standards requirements are not fully implemented, but enough to pass most of the checks.

Installation

Obtain your copy of source code from the git repository: $ git clone https://github.com/vint21h/django-xicon.git. Or download the latest release from https://github.com/vint21h/django-xicon/tags/.
Run $ python ./setup.py install from the repository source tree or unpacked archive. Or use pip: $ pip install django-xicon.

Configuration

Add "xicon" to settings.INSTALLED_APPS:

.. code-block:: python

# settings.py

INSTALLED_APPS += [
    "xicon",
]

Add "xicon" to your URLs definitions if you want to serve manifest.json or browserconfig.xml:

.. code-block:: python

# urls.py

from django.urls import include, re_path

urlpatterns += [
    re_path(r"^xicon/", include("xicon.urls")),
]

Settings

XICON_FAVICONS Contains list of favicons. Defaults to []. Each element must be according to the next structure:

.. code-block:: python

{
    "src": "favicon.ico",
    "type": "image/x-icon",
    "size": "16x16",
}  # type: Dict[str, Optional[str]]

Where src key is a path to the favicon file in Django static directory, type is favicon file mime-type and size key contains icon's width and height and can be omitted.

XICON_APPLE_TOUCH_ICONS Contains list of apple touch icons. Defaults to []. Each element must be according to the next structure:

.. code-block:: python

{
    "src": "apple-touch-icon-144x144.png",
    "size": "144x144",
}  # type: Dict[str, Optional[str]]

Where src key is a path to the icon file in Django static directory and size contains icon's width and height and can be omitted.

XICON_APPLE_TOUCH_ICON_MASK_ICON_SRC Contains path to Safari pinned tabs icon. Defaults to "".

XICON_APPLE_TOUCH_ICON_MASK_ICON_COLOR Contains path to Safari pinned tab icon hover color. Defaults to "", must start with #.

XICON_APPLE_MOBILE_WEB_APP_STATUS_BAR_STYLE_COLOR Contains iOS web application status bar color. Defaults to "".

XICON_APPLE_MOBILE_WEB_APP_TITLE Contains iOS web application launch icon title. Defaults to "".

XICON_ANDROID_CHROME_THEME_COLOR Contains android chrome web application toolbar color also used in manifest.json. Defaults to "", must start with #.

XICON_ANDROID_CHROME_ICONS Contains a list of icons for manifest.json. Defaults to []. Each element must be according to the next structure:

.. code-block:: python

{
    "src": "android-chrome-64x64.png",
    "type": "image/png",
    "sizes": "64x64",
}  # type: Dict[str, str]

Where src key is a path to the icon file in Django static directory, type is favicon file mime-type and size key contains icon's width and height.

XICON_ANDROID_CHROME_NAME Contains android chrome web application name for manifest.json. Defaults to "".

XICON_ANDROID_CHROME_SHORT_NAME Contains android chrome web application short name for manifest.json. Defaults to "".

XICON_ANDROID_CHROME_BACKGROUND_COLOR Contains android chrome web application background color for manifest.json. Defaults to "", must start with #.

XICON_ANDROID_CHROME_DISPLAY Contains android chrome web application browser UI mode for manifest.json. Defaults to "".

XICON_ANDROID_CHROME_ORIENTATION Contains android chrome web application screen orientation for manifest.json. Defaults to "".

XICON_MSAPPLICATION_NAME Contains microsoft application name. Defaults to "".

XICON_MSAPPLICATION_TILE_COLOR Contains Microsoft application tile color also used in browserconfig.xml. Defaults to "", must start with #.

XICON_MSAPPLICATION_TILES Contains list of icons for Microsoft application meta tags and also used in browserconfig.xml. Defaults to []. Each element must be according to the next structure:

.. code-block:: python

{
    "src": "mstile-70x70.png",
    "name": "square70x70logo",
}  # type: Dict[str, str]

Where src key is a path to the icon file in Django static directory and name contains tile name (type).

Usage

If you want to use all power of django-xicon, just set up all settings and include "xicon/includes/xicon.html" to your base template <head> HTML tag:

.. code-block:: django

{# base.html #}

<head>
    {% include "xicon/includes/xicon.html" %}
</head>

Or just for favicons, setup XICON_FAVICONS setting, load "xicon_tags" to your base template and place "xicon_favicons" in <head> HTML tag:

.. code-block:: django

{# base.html #}

{% load xicon_tags %}

<head>
    {% xicon_favicons %}
</head>

If you want to setup web application for apple devices <https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html>_, setup all settings prefixed with XICON_APPLE_ and include "xicon/includes/apple.html" to your base template <head> HTML tag:

.. code-block:: django

{# base.html #}

<head>
    {% include "xicon/includes/apple.html" %}
</head>

Or just for apple touch icons, setup APPLE_TOUCH_ICONS setting, load "xicon_tags" to your base template and place "xicon_apple_touch_icons" in <head> HTML tag:

.. code-block:: django

{# base.html #}

{% load xicon_tags %}

<head>
    {% xicon_apple_touch_icons %}
</head>

To use Safari pinned tabs mask icon setup XICON_APPLE_TOUCH_ICON_MASK_ICON_SRC and XICON_APPLE_TOUCH_ICON_MASK_ICON_COLOR settings, load "xicon_tags" to your base template and place "xicon_apple_touch_icon_mask_icon" in <head> HTML tag:

.. code-block:: django

{# base.html #}

{% load xicon_tags %}

<head>
    {% xicon_apple_touch_icon_mask_icon %}
</head>

To configure iOS web application bar style color setup XICON_APPLE_MOBILE_WEB_APP_STATUS_BAR_STYLE_COLOR setting, load "xicon_tags" to your base template and place "xicon_apple_mobile_web_app_status_bar_style" in <head> HTML tag:

.. code-block:: django

{# base.html #}

{% load xicon_tags %}

<head>
    {% xicon_apple_mobile_web_app_status_bar_style %}
</head>

To configure iOS web application launch icon title setup XICON_APPLE_MOBILE_WEB_APP_TITLE setting, load "xicon_tags" to your base template and place "xicon_apple_mobile_web_app_title" in <head> HTML tag:

.. code-block:: django

{# base.html #}

{% load xicon_tags %}

<head>
    {% xicon_apple_mobile_web_app_title %}
</head>

If you want to use android chrome <https://developers.google.com/web/fundamentals/web-app-manifest/>_ related things, just setup all settings prefixed with XICON_ANDROID_CHROME_ and include "xicon/includes/android-chrome.html" to your base template <head> HTML tag:

.. code-block:: django

{# base.html #}

<head>
    {% include "xicon/includes/android-chrome.html" %}
</head>

Or if you need only configure android chrome web application toolbar color, setup XICON_ANDROID_CHROME_THEME_COLOR, load "xicon_tags" to your base template and place "xicon_android_chrome_theme_color" in <head> HTML tag:

.. code-block:: django

{# base.html #}

{% load xicon_tags %}

<head>
    {% xicon_android_chrome_theme_color %}
</head>

If you need generate and serve manifest.json, add "xicon" to your URLs definitions, setup next settings: XICON_ANDROID_CHROME_THEME_COLOR, XICON_ANDROID_CHROME_ICONS, XICON_ANDROID_CHROME_NAME, XICON_ANDROID_CHROME_SHORT_NAME, XICON_ANDROID_CHROME_BACKGROUND_COLOR, XICON_ANDROID_CHROME_DISPLAY and `XICON_ANDROID_CHROME_ORIENTATION, and then include"xicon/includes/android-chrome-manifest-meta.html"to your base template`` HTML tag:

.. code-block:: python

# urls.py

from django.urls import include, re_path

urlpatterns += [
    re_path(r"^xicon/", include("xicon.urls")),
]

.. code-block:: django

{# base.html #}

<head>
    {% include "xicon/includes/android-chrome-manifest-meta.html" %}
</head>

If you want to setup microsoft application <https://technet.microsoft.com/en-us/windows/dn320426(v=vs.60)#MainContent>_ configure all settings prefixed with XICON_MSAPPLICATION_ and include "xicon/includes/msapplication.html" to your base template <head> HTML tag:

.. code-block:: django

{# base.html #}

<head>
    {% include "xicon/includes/msapplication.html" %}
</head>

Or if you need only configure microsoft application name, setup XICON_MSAPPLICATION_NAME, load "xicon_tags" to your base template and place "xicon_msapplication_name" in <head> HTML tag of your base template:

.. code-block:: django

{# base.html #}

{% load xicon_tags %}

<head>
    {% xicon_msapplication_name %}
</head>

If you need configure microsoft application tile color, setup XICON_MSAPPLICATION_TILE_COLOR, load "xicon_tags" to your base template and place "xicon_msapplication_tile_color" in <head> HTML tag of your base template:

.. code-block:: django

{# base.html #}

{% load xicon_tags %}

<head>
    {% xicon_msapplication_tile_color %}
</head>

If you need generate and serve browserconfig.xml, add "xicon" to your URLs definitions, setup next settings: XICON_MSAPPLICATION_TILE_COLOR and XICON_MSAPPLICATION_TILES, and then include "xicon/includes/msapplication-browserconfig-meta.html" to your base template <head> HTML tag:

.. code-block:: python

# urls.py

from django.urls import include, re_path

urlpatterns += [
    re_path(r"^xicon/", include("xicon.urls")),
]

.. code-block:: django

{# base.html #}

<head>
    {% include "xicon/includes/msapplication-browserconfig-meta.html" %}
</head>

Or just for microsoft application tiles, setup MSAPPLICATION_TILES setting, load "xicon_tags" to your base template and place "xicon_mstiles" in <head> HTML tag:

.. code-block:: django

{# base.html #}

{% load xicon_tags %}

<head>
    {% xicon_mstiles %}
</head>

Contributing

Fork it <https://github.com/vint21h/django-xicon/>_
Install GNU Make <https://www.gnu.org/software/make/>_
Install and configure pyenv <https://github.com/pyenv/pyenv/> and pyenv-virtualenv plugin <https://github.com/pyenv/pyenv-virtualenv/>
Install and configure direnv <https://github.com/direnv/direnv/>_
Create environment config from example

.. code-block:: bash

cp .env.example .env

Install development dependencies:

.. code-block:: bash

make install

Create your fix/feature branch:

.. code-block:: bash

git checkout -b my-new-fix-or-feature

Check code style and moreover:

.. code-block:: bash

make check

Run tests:

.. code-block:: bash

make test

Push to the branch:

.. code-block:: bash

git push origin my-new-fix-or-feature

Create a new Pull Request <https://github.com/vint21h/django-xicon/compare/>_

Licensing

django-xicon is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. For complete license text see COPYING file.

Contacts

Project Website: https://github.com/vint21h/django-xicon/

Author: Alexei Andrushievich vint21h@vint21h.pp.ua

For complete authors list see AUTHORS file.

.. |GitHub| image:: https://github.com/vint21h/django-xicon/workflows/build/badge.svg :alt: GitHub .. |Coveralls| image:: https://coveralls.io/repos/github/vint21h/django-xicon/badge.svg?branch=master :alt: Coveralls .. |pypi-license| image:: https://img.shields.io/pypi/l/django-xicon :alt: License .. |pypi-version| image:: https://img.shields.io/pypi/v/django-xicon :alt: Version .. |pypi-django-version| image:: https://img.shields.io/pypi/djversions/django-xicon :alt: Supported Django version .. |pypi-python-version| image:: https://img.shields.io/pypi/pyversions/django-xicon :alt: Supported Python version .. |pypi-format| image:: https://img.shields.io/pypi/format/django-xicon :alt: Package format .. |pypi-wheel| image:: https://img.shields.io/pypi/wheel/django-xicon :alt: Python wheel support .. |pypi-status| image:: https://img.shields.io/pypi/status/django-xicon :alt: Package status .. _GitHub: https://github.com/vint21h/django-xicon/actions/ .. _Coveralls: https://coveralls.io/github/vint21h/django-xicon?branch=master .. _pypi-license: https://pypi.org/project/django-xicon/ .. _pypi-version: https://pypi.org/project/django-xicon/ .. _pypi-django-version: https://pypi.org/project/django-xicon/ .. _pypi-python-version: https://pypi.org/project/django-xicon/ .. _pypi-format: https://pypi.org/project/django-xicon/ .. _pypi-wheel: https://pypi.org/project/django-xicon/ .. _pypi-status: https://pypi.org/project/django-xicon/

vint21h / django-xicon

readme

A django-xicon documentation

Installation

Configuration

Settings

Usage

Contributing

Licensing

Contacts