{
    "info": {
        "author": "Thierry Jossermoz",
        "author_email": "thierry.jossermoz@oohlalabs.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "Environment :: Web Environment",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: MIT License",
            "Operating System :: OS Independent",
            "Programming Language :: Python",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3.3",
            "Programming Language :: Python :: 3.4",
            "Topic :: Software Development :: Libraries :: Python Modules"
        ],
        "description": "=================\nDjango Silhouette\n=================\n\n.. image:: https://travis-ci.org/jthi3rry/django-silhouette.svg?branch=master\n    :target: https://travis-ci.org/jthi3rry/django-silhouette\n\n.. image:: https://coveralls.io/repos/jthi3rry/django-silhouette/badge.png?branch=master\n    :target: https://coveralls.io/r/jthi3rry/django-silhouette\n\nSilhouette is a form templating app for Django just like `Django Crispy Forms <https://github.com/maraujop/django-crispy-forms>`_\nor `Django Floppy Forms <https://github.com/gregmuellegger/django-floppyforms>`_.\nUnlike these, form templating with Silhouette is exclusively done at the template level. Your form classes don't need to change.\n\nYou no longer have to plague your forms with widgets that are only here to add some css or form helpers simulating html. Your django forms are\nused for server-side input validation, your templates are the only ones responsible for making them look awesome.\n\nIf you happen to have a team of frontend developers who don't want to dig deep into the darkness of your\npython code to change a class on one of your field's help text, they'll probably thank you.\nAnd even if you don't, you'll probably be happy to keep your form templating code where it belongs: in your templates.\n\nSilhouette also lets you create global themes and form specific themes to style everything from the form tag down to field errors and widget types.\nSince everything happens in templates, you can use template inheritance and blocks to achieve anything you like. Read on.\n\nInstallation\n============\n\n::\n\n    pip install django-silhouette\n\n\nIn your settings.py\n\n::\n\n    INSTALLED_APPS = [\n        ...\n        \"silhouette\",\n        ...\n    ]\n\n\nGetting Started\n===============\n\nInstead of explaining the internals of Silhouette head-on, let's get a feel for it by creating a form styled with Twitter's Bootstrap.\nWe'll assume that your layout already includes the bootstrap stylesheet.\n\nLet's pretend we have an imaginary form like `this one <http://getbootstrap.com/css/#forms>`_::\n\n    class BasicForm(forms.Form):\n\n        email_address = forms.EmailField()\n        password = forms.CharField(widget=forms.PasswordInput)\n        file = forms.FileField()\n        check_me_out = forms.BooleanField()\n\nWith Silhouette, you could display the form like this (in the imaginary template ``templates/app/index.html``)::\n\n    {% load silhouette_tags %}\n\n    <form>\n        {% csrf_token %}\n        <div class=\"form-group{% if form.name.errors %} has-error{% endif %}\">\n            {% field form.name widget_placeholder=\"Enter email\" widget_id=\"exampleInputEmail1\" widget_class=\"form-control\" %}\n        </div>\n        <div class=\"form-group{% if form.password.errors %} has-error{% endif %}\">\n            {% field form.password widget_placeholder=\"Password\" widget_id=\"exampleInputPassword1\" widget_class=\"form-control\" %}\n        </div>\n        <div class=\"form-group{% if form.file.errors %} has-error{% endif %}\">\n            {% field form.file help_text_contents=\"Example block-level help text here.\" help_text_class=\"help-block\" %}\n        </div>\n        <div class=\"checkbox{% if form.check_me_out.errors %} has-error{% endif %}\">\n            <label>{% form_widget form.check_me_out %} {{ form.check_me_out.label }}</label>\n        </div>\n        <button type=\"submit\" class=\"btn btn-default\">Submit</button>\n    </form>\n\nThis will give you the form as per Bootstrap's example. We didn't do anything about errors, but Silhouette will\nalso render these for free (you could add ``errors_class=\"alert alert-danger\"`` to each field to display errors using bootstrap's alerts).\n\nThis is still not ideal though. All our forms should be displayed consistently and there will be a lot of repetition if we need to do this for\nevery single form.\n\nLet's create a global theme that will handle all this for us.\n\nGlobal Themes\n=============\n\nIn your ``settings.py``, configure the silhouette theme name. By default this is::\n\n    SILHOUETTE_THEME = \"default\"\n\nLet's change the theme name to ``bootstrap``::\n\n    SILHOUETTE_THEME = \"bootstrap\"\n\nCreate a file ``templates/silhouette/bootstrap/fields/field.html``. You could create a template from scratch and render the label,\nwidget, errors and help text individually (refer to the `base field template <https://github.com/OohlaLabs/django-silhouette/blob/master/silhouette/templates/silhouette/base/fields/field.html>`_ for an example),\nbut let's see how to take advantage of Django's template inheritance and Silhouette's base theme\n\n::\n\n    {% extends \"silhouette/base/fields/field.html\" %}\n\n    {% load silhouette_tags silhouette_filters %}\n\n    {% block field %}\n        <!-- Output field wrapper based on widget type -->\n        {% if field|is_checkbox_input %}\n            <div class=\"checkbox{% if field.errors %} has-error{% endif %}\">\n                {{ block.super }}\n            </div>\n        {% else %}\n            <div class=\"form-group{% if field.errors %} has-error{% endif %}\">\n                {{ block.super }}\n            </div>\n        {% endif %}\n    {% endblock %}\n\n    {% block widget %}\n        <!-- Output field widget based on its type -->\n        {% if field|is_file_input or field|is_checkbox_input %}\n            {% field_widget field %}\n        {% else %}\n            {% field_widget field class=\"form-control\" %}\n        {% endif %}\n    {% endblock %}\n\n    {% block help_text %}\n        <!-- Output help text consistently -->\n        {% field_help_text field class=\"help-block\" %}\n    {% endblock %}\n\n    {% block errors %}\n        <!-- Output errors consistently -->\n        {% field_errors field class=\"alert alert-danger\" %}\n    {% endblock %}\n\nNotice that the template's context has a ``field`` variable that refers to the form's bound field being rendered (your default context is also available).\n\nNow we just need an extra template for checkboxes as we want to wrap the label around the field.\n\nIn ``templates/silhouette/bootstrap/fields/checkbox_input_field.html``, extend your own field template with::\n\n        {% extends \"silhouette/bootstrap/fields/field.html\" %}\n\n        {%load silhouette_tags %}\n\n        {% block label %}\n            <!-- Do not render the label here -->\n        {% endblock %}\n\n        {% block widget %}\n            <label>{% field_widget field %} {{ field.label }}</label>\n        {% endblock %}\n\nNotice that the template name for a checkbox field is the widget's class name in underscore notation ``checkbox_input`` followed by the ``_field`` suffix.\n\nYour ``templates/app/index.html`` template now can become::\n\n    {% load silhouette_tags %}\n\n    <form>\n        {% csrf_token %}\n        {% field form.name widget_placeholder=\"Enter email\" widget_id=\"exampleInputEmail1\" %}\n        {% field form.password widget_placeholder=\"Password\" widget_id=\"exampleInputPassword1\" %}\n        {% field form.file help_text_contents=\"Example block-level help text here.\" %}\n        {% field form.check_me_out %}\n        <button type=\"submit\" class=\"btn btn-default\">Submit</button>\n    </form>\n\nAnd all your future forms will use the bootstrap theme.\n\nIf you need a specific class added to any of the fields, Silhouette will merge these for you with the ones defined in a theme::\n\n    {% field form.password ... widget_class=\"extra-class\" %}\n\nWill output::\n\n    <div class=\"form-group\">\n        ...\n        <input type=\"password\" ... class=\"form-control extra-class\" />\n        ...\n    </div>\n\nNow you can extend your theme by adding new widgets like radio buttons, select boxes and so on.\n\nForm Themes\n===========\n\nField templates and global themes remove a lot of the complexity usually involved with displaying forms with Django. But Silhouette\ndoesn't stop here and also allows you to create form specific theme.\n\nFor example, let's change our ``templates/app/index.html`` template, and use the second bootstrap example using the ``form-inline`` class.\n\nWe'll also introduce the `silhouette` tag that allows you to display forms in a single line of code::\n\n    {% load silouhette_tags %}\n\n    {% silhouette form method=\"post\" action=\"/action\" class=\"form-inline\" errors_class=\"alert alert-warning\" %}\n\nThis will render::\n\n    <form enctype=\"multipart/form-data\" class=\"form-inline\" method=\"post\" action=\"/action\" >\n        <input type=\"hidden\" name=\"csrf_token\" value=\"....\" />\n\n        <!-- Errors will show up here if any -->\n        <ul class=\"alert alert-warning\">\n            <li>....</li>\n        </ul>\n\n        <!-- Fields will show up here -->\n        <div class=\"form-group\">\n            ...\n        </div>\n        ...\n\n        <!-- Controls will show up here -->\n        <button type=\"submit\">Submit</button>\n\n        <!-- Media will show up here if any -->\n        <script ...></script>\n\n    </form>\n\nHowever, by doing so, we just lost the specific attributes that were passed to each field like placehoders, ids, etc.\nas well as our styled submit button.\n\nOur fields and button are specific to our form, so let's create a \"form theme\" for these.\n\nIn ``templates/silhouette/basic_form/fields.html``::\n\n    {% extends \"silhouette/base/forms/fields.html\" %}\n\n    {% load silhouette_tags %}\n\n    {% block visible_fields %}\n        {% field form.name widget_placeholder=\"Enter email\" widget_id=\"exampleInputEmail1\" %}\n        {% field form.password widget_placeholder=\"Password\" widget_id=\"exampleInputPassword1\" %}\n        {% field form.file help_text_contents=\"Example block-level help text here.\" %}\n        {% field form.check_me_out %}\n    {% endblock %}\n\nNote that the template is not created under the ``bootstrap`` theme, but under the ``basic_form`` \"theme\". This is the form's class name ``BasicForm`` in underscore notation.\n\nNow, in ``templates/silhouette/basic_form/controls.html``::\n\n    <button type=\"submit\" class=\"btn btn-default\">Submit</button>\n\nNote that you could override this in the global theme by modifying ``templates/silhouette/bootstrap/forms/controls.html`` instead.\n\nJust like with the global theme, you can override any field, label, widget, field errors, help text in your form by\ncreating a template in ``templates/silhouette/basic_form/fields/{{overridden_part}}.html``.\n\nAnything usually possible with Django templates is possible with Silhouette.\nSilhouette provides a base theme with what we assumed could be useful and generic, but you can ignore it or replace it altogether.\n\nTemplate Loader\n===============\n\nWhen rendering a template for a field, form or formset, Silhouette tries and find the first template that exists using a list of path patterns.\n\nThe general idea is that Silhouette will look for a template from the most specific to the most generic place.\n\nFor example, when doing ``{% field form.field %}``, Silhouette will check:\n\n* if a template exists for the field in the form's theme\n* if one exists for the field's widget in the form's theme\n* if one exists for the field's widget in the global theme\n* if one exists for all fields in the form's theme\n* if one exists for all fields in the global theme\n* otherwise, it will fallback to using the base field template shipped with Silhouette\n\nThese rules are defined like this in the ``SILHOUETTE_PATTERNS`` setting:\n\n* ``{path}/{form}/fields/{field}.html``\n* ``{path}/{form}/fields/{widget}_field.html``\n* ``{path}/{theme}/fields/{widget}_field.html``\n* ``{path}/{form}/fields/field.html``\n* ``{path}/{theme}/fields/field.html``\n* ``silhouette/base/fields/field.html``\n\nWhere ``{path}`` is the value of the ``SILHOUETTE_PATH`` setting, ``{theme}`` is the value of the ``SILHOUETTE_THEME`` setting, ``{form}`` is the form class\nname in underscore notation, ``{field}`` is the field name in your form, and ``{widget}`` is the widget class name in underscore notation.\n\nEach tag has its own lookup list of patterns. See the `default settings <https://github.com/OohlaLabs/django-silhouette/blob/master/silhouette/settings.py>`_\nfor a full list. For advanced usage or if you simply don't like the convention and want to use another one, new patterns can be added or the lookup order modified by changing the ``SILHOUETTE_PATTERNS`` setting.\n\nBypassing the Template Lookup\n-----------------------------\n\nTags also accept a template argument to render a specific template. For example::\n\n    {% field form.field1 template=\"path/to/field1.html\" %}\n\nWhen using the template argument, field patterns will be ignored.\n\nOverriding Path and Theme\n-------------------------\n\nPath and theme can also be overridden for a given tag. For example::\n\n    {% field form.field1 path=\"form-themes\" theme=\"my-theme\" %}\n\nWhen using these arguments, the value of `{path}` and `{theme}` are overridden for the given tag, and all tags used within its context.\nSo in the above example, the widget, label, help_text and errors rendered by `field` would use the path `form-themes` and the theme `my-theme`.\n\nRunning Tests\n=============\n\nGet a copy of the repository::\n\n    git clone git@github.com:OohlaLabs/django-silhouette.git .\n\nInstall `tox <https://pypi.python.org/pypi/tox>`_::\n\n    pip install tox\n\nRun the tests::\n\n    tox\n\nContributions\n=============\n\nAll contributions and comments are welcome.\n\nChange Log\n==========\n\nv0.0.2\n------\n* Distribution description & homepage\n\nv0.0.1\n------\n* Initial release",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/OohlaLabs/django-silhouette",
        "keywords": "",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "django-silhouette",
        "package_url": "https://pypi.org/project/django-silhouette/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/django-silhouette/",
        "project_urls": {
            "Homepage": "https://github.com/OohlaLabs/django-silhouette"
        },
        "release_url": "https://pypi.org/project/django-silhouette/0.0.3/",
        "requires_dist": [
            "Django (>=1.6)",
            "django-pods (>=1.0.1)"
        ],
        "requires_python": "",
        "summary": "Elegant Form Templating for Django",
        "version": "0.0.3"
    },
    "last_serial": 2176629,
    "releases": {
        "0.0.1": [],
        "0.0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "155f86164cb6b389e69e8048eb291af8",
                    "sha256": "d2a8d5105b91afa0182a7c3e70679037def5483ca1c3983bad2d9212236ad34b"
                },
                "downloads": -1,
                "filename": "django_silhouette-0.0.2-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "155f86164cb6b389e69e8048eb291af8",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 20165,
                "upload_time": "2015-02-15T00:44:22",
                "url": "https://files.pythonhosted.org/packages/1a/a4/82b6972f9edc425e5f88205f861270f05bbac53167186d8f662735c4e4a4/django_silhouette-0.0.2-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "7e0e8da279457c930f7e8b90d76580f2",
                    "sha256": "f92fcde1eae13b14150f01cdd8c5d60f413fb0846f523db001f5c1aa82d183de"
                },
                "downloads": -1,
                "filename": "django-silhouette-0.0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "7e0e8da279457c930f7e8b90d76580f2",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 13168,
                "upload_time": "2015-02-15T00:44:14",
                "url": "https://files.pythonhosted.org/packages/44/18/fb75dc5fedbf4a89dc93509a94b67b7d23403da4232a6d477372c23b3707/django-silhouette-0.0.2.tar.gz"
            }
        ],
        "0.0.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8615ce017933b8e9c5659fd77a5aac69",
                    "sha256": "04f9ad1e2c45952a8e13e56752748898b8db1b18be3c2b1bfa3887b191238660"
                },
                "downloads": -1,
                "filename": "django_silhouette-0.0.3-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "8615ce017933b8e9c5659fd77a5aac69",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 26683,
                "upload_time": "2016-06-20T04:39:12",
                "url": "https://files.pythonhosted.org/packages/80/91/7b24f75a8a7a98f1bcfec7315ef8015832463dcec5ea5bccf1eaa0a3cb91/django_silhouette-0.0.3-py2.py3-none-any.whl"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "8615ce017933b8e9c5659fd77a5aac69",
                "sha256": "04f9ad1e2c45952a8e13e56752748898b8db1b18be3c2b1bfa3887b191238660"
            },
            "downloads": -1,
            "filename": "django_silhouette-0.0.3-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "8615ce017933b8e9c5659fd77a5aac69",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 26683,
            "upload_time": "2016-06-20T04:39:12",
            "url": "https://files.pythonhosted.org/packages/80/91/7b24f75a8a7a98f1bcfec7315ef8015832463dcec5ea5bccf1eaa0a3cb91/django_silhouette-0.0.3-py2.py3-none-any.whl"
        }
    ]
}