README.md

# hshassets [![python version](https://img.shields.io/badge/python-3.x-blue.svg)]() [![django version](https://img.shields.io/badge/Django-2.x-brightgreen.svg)]()

This django-app provides everything you ever wanted! (probably not, but i hope you feel happy anyways). It brings fonts,
styles, javascript and layouts as templates.

Please read the [wiki](https://lab.it.hs-hannover.de/django/hshassets/wikis/templates) for further information about the
available templates.

## Packed with awesome stuff

The current version of this package ships the following own stuff and awesome third-party libraries

### Own stuff

- CD Content like Images under `static/hshassets/img/hsh_brand`
- Form renderer (like CrispyForms)

### Third party libraries

#### CSS

- [animate.css](https://github.com/daneden/animate.css) (3.5.2) - cross-browser library of CSS animations
- [bulma](https://github.com/jgthms/bulma) (0.6.2) - modern CSS framework based on Flexbox
- [font-awesome](https://github.com/FortAwesome/Font-Awesome) (4.7.0) - iconic font and CSS toolkit

#### JavaScript

- [jquery](https://github.com/jquery/jquery) (3.2.1) - New Wave JavaScript


## Installation

Simply put this app into your projects `requirements.txt` file and run `pip install -r requirements.txt`. Once you
installed it, you should put the name `hshcdn` into your projects `INSTALLED_APPS` setting. Tadaa!

Also if you want to use breadcrubs (you likely do), you need to add the settings context processor to your `TEMPLATES` setting:

```python
TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        # [...]
        'OPTIONS': {
            'context_processors': [
                # [...]
                'hshassets.context_processors.settings'  # <-- add this line
            ],
        },
    },
]
```

**More information about using breadcrumbs [can be found in the WIKI](https://lab.it.hs-hannover.de/django/hshassets/wikis/breadcrumbs)**

## Usage

Simply create an `assets` folder in your app(s) directory. It can contain the folders `fonts` for custom fonts, `img`
for own images, `js` for custom javascript and `sass` for custom (s)css.

- *Everything* that exists in the folders `appname/assets/fonts` and `img` will be *copied* to
`appname/static/appname/<folder_name>`.
- Files that exist at `appname/assets/js` and ends with `.js` will be merged and minified to
`appname/static/appname/script(.min).css`
- For (s)css, hshassets will search for the file `appname/assets/sass/_init.scss` and tries to compile it. So you have
to import additional (s)css files there. The compiled and minified result will be copied to
`appname/static/appname/styles(.min).css`

This example structure ...

```
[project name]
│
├── [app name]
│   │                             ┐
│   ├── assets                    │
│   │   ├── fonts                 ├─ This is new
│   │   │   └── funny_font.woff   │
│   │   ├── img                   │
│   │   │   ├── dog.png           │
│   │   │   ├── cat.png           │
│   │   │   └── mouse.png         │
│   │   ├── js                    │
│   │   │   ├── foo.js            │
│   │   │   └── bar.js            │
│   │   └── sass                  │
│   │       ├── _init.scss        │
│   │       └── stuff.scss        │
│   │                             ┘
│   ├── urls.py
│   ├── wsgi.py
│   └── ...
│
├── manage.py
├── README.md
└── ...
```

... will produce the following result tree:

```
[project name]
│
├── [app name]
│   │
│   ├── assets                      - this will still exist
│   │   └── ...
│   │                                ┐                  
│   ├── static                       │
│   │   └── [appname]                ├─ The produced result
│   │       ├── fonts                │
│   │       │   └── funny_font.woff  │  But be careful, never edit files here directly!
│   │       │                        |  `hshassets` manages this directory entirely. This
│   │       ├── img                  │  means that everything here will be overwritten or
│   │       │   ├── dog.png          │  deleted if it shouldn't be here. Use the `assets`
│   │       │   ├── cat.png          │  folder for your custom stuff.
│   │       │   └── mouse.png        │
│   │       │                        │
│   │       ├── js                   ├─ Javascript won't be concatinated but minified
│   │       │   ├── foo.js           │
│   │       │   └── bar.js           |
│   │       │                        |
│   │       ├── styles.css           ├─ Sass / Scss files will be compiled, concatinated
│   │       └── styles.min.css       │  and minified.
│   │                                ┘
│   ├── urls.py
│   ├── wsgi.py
│   └── ...
│
├── manage.py
├── README.md
└── ...
```

To help you with the development, there are two command available:

- `python manage.py buildassets`  
  Will gather, copy, compile and minify everything **once**. After it finished, you can execute other commands.

- `python manage.py watchassets`  
  does the exact same as the command before, but doesn't stop at the end. It will continuously watch for changes on
  `*.js`, `*.sass`, `*.scss`, `*.css` files and everything at `img/` and `fonts/` to re-compile -minify and -copy
  the changed files

## Forms
Example:
```python
class UnlockForm(forms.Form):
    username = forms.CharField(
        max_length=400,
        widget=forms.TextInput(attrs={"placeholder": _("username"), "icon": "fa-user"}),
        label="",  # empty, not None
    )
```
```jinja2
{% load bulma %}
{% trans "Send" as submit_text %}
{% bulma_form form submit_text=submit_text %}
```
To change styles and icons of the submit button: `bulma_form` with something like
```jinja2
{% bulma_form form submit_icon="fa-hand-spock-o" submit_class="button is-danger" %}
```
Or you can use these template tags for a DIY form:
```jinja2
{% load bulma %}
{% bulma_form_errors form %}
{% bulma_form_fields form %}
{% bulma_submit_button %}
```