Basic Usage
===========
Installation
------------
Create a project folder and a :file:`venv` folder within:
.. tabs::
.. group-tab:: macOS/Linux
.. code-block:: text
$ mkdir myproject
$ cd myproject
$ python3 -m venv venv
.. group-tab:: Windows
.. code-block:: text
> mkdir myproject
> cd myproject
> py -3 -m venv venv
Activate the environment
~~~~~~~~~~~~~~~~~~~~~~~~
Before you work on your project, activate the corresponding environment:
.. tabs::
.. group-tab:: macOS/Linux
.. code-block:: text
$ . venv/bin/activate
.. group-tab:: Windows
.. code-block:: text
> venv\Scripts\activate
Your shell prompt will change to show the name of the activated
environment.
Install Flask-FomanticUI
~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash
$ pip install Flask-FomanticUI
Initialization
--------------
.. code-block:: python
from flask import Flask
from flask_fomanticui import FomanticUI
app = Flask(__name__)
fomantic = FomanticUI(app)
Resources helpers
-----------------
Flask-FomanticUI provides two helper functions to load `Fomantic UI `_
resources in the template: ``fomantic.load_css()`` and ``fomantic.load_js()``.
Call it in your base template, for example:
.. code-block:: jinja
....
{{ fomantic.load_css() }}
...
{{ fomantic.load_js() }}
You can pass ``version`` to pin the Fomantic UI 2.8.8 version you want to use.
It defaults to load files from CDN. Set ``FOMANTIC_SERVE_LOCAL`` to ``True`` to use built-in local files.
However, these methods are optional, you can also write ```` and ```` tags
to include Fomantic UI resources (from your ``static`` folder or CDN) manually by yourself.
Starter template
----------------
For reasons of flexibility, Flask-FomanticUI doesn't include built-in base templates
(this may change in the future). For now, you have to create a base template yourself.
Be sure to use an HTML5 doctype and include a viewport meta tag for proper responsive behaviors.
Here's an example base template:
.. code-block:: html
{% block head %}
{% block styles %}
{{ fomantic.load_css() }}
{% endblock %}
Your page title
{% endblock %}
{% block content %}{% endblock %}
{% block scripts %}
{{ fomantic.load_js() }}
{% endblock %}
Use this in your templates folder (suggested names are ``base.html`` or ``layout.html`` etc.),
and inherit it in child templates. See `Template Inheritance `_ for
more details on inheritance.
.. _macros_list:
Macros
------
+------------------------------+--------------------------------+--------------------------------------------------------------------+
| Macro | Templates Path | Description |
+==============================+================================+====================================================================+
| render_ui_field() | fomantic/form_ui.html | Render a WTForms form field. |
+------------------------------+--------------------------------+--------------------------------------------------------------------+
| render_ui_form() | fomantic/form_ui.html | Render a WTForms form. |
+------------------------------+--------------------------------+--------------------------------------------------------------------+
| render_ui_form_row() | fomantic/form_ui.html | Render a row of a grid form. |
+------------------------------+--------------------------------+--------------------------------------------------------------------+
| render_ui_hidden_errors() | fomantic/form_ui.html | Render error messages for hidden form field. |
+------------------------------+--------------------------------+--------------------------------------------------------------------+
| render_ui_pager() | fomantic/pagination.html | Render a basic Flask-SQLAlchemy pagniantion. |
+------------------------------+--------------------------------+--------------------------------------------------------------------+
| render_ui_pagination() | fomantic/pagination.html | Render a standard Flask-SQLAlchemy pagination. |
+------------------------------+--------------------------------+--------------------------------------------------------------------+
| render_ui_nav_item() | fomantic/nav.html | Render a navigation item. |
+------------------------------+--------------------------------+--------------------------------------------------------------------+
| render_ui_breadcrumb_item() | fomantic/nav.html | Render a breadcrumb item. |
+------------------------------+--------------------------------+--------------------------------------------------------------------+
| render_static() | fomantic/utils.html | Render a resource reference code (i.e. ````, ``