Package: django-templateselector
Author:Keryn KnightVersion:0.2.5ReleaseStatusstable (0.2.5)masterSectionsWhat it doesExampleUse caseAvailable functionalityTemplateFieldTemplateChoiceFieldnice_display_nameSupported Django versionsInstallation and usageInstallationConfigurationUsageAltering the widget choice sizeRunning the testsRunning the demoThe licenseChange history for django-templateselector0.2.50.2.40.2.30.2.20.2.10.2.00.1.10.1.0What it doesProvides a new model field,fields.TemplateFieldwhich allows for selection
of a specificDjangotemplate using a nice form field (fields.TemplateChoiceField)
and a nicer widget (widgets.TemplateSelector) than the standard<select>dropdown.ExampleBelow is a screenshot of the admin widget, without any thumbnails set up for
each template, because I’m too lazy for that.Use caseImagine you have aPagemodel, and you want to allow admins or page authors
to choose from a range of templates for the page to use, you could do this:from django.db import models
from templateselector.fields import TemplateField

class MyPage(models.Model):
  title = models.CharField(max_length=100)
  # ...
  template = TemplateField(match='^myapp/mypage/layouts/.+\.html$')which would allow them to select any HTML file Django could find in the
appropriate directory.Available functionalityThese fields are really the only public API. There’s obviously other stuff, if you
care to rummage around.TemplateFieldExtends CharField, and requires amatchargument which ought to be a
string version of a regular expression. Thematchwill be used to filter
the possible choices. Optionally also takes adisplay_nameargument, which
is a callable (ordotted.string.path.to.one) that takes a given
string (the selected template path) and returns a nice name for it. The
nice name is available asget_<fieldname>_display,for consistency with DjangoThe default form field forTemplateFieldis …TemplateChoiceFieldHas the same arguments asTemplateField, and can be used independently
in all forms if you want to not use the model field.
The form field, when rendered with theTemplateSelectorwidget, will try
and show a preview image for each template, by attempting to load a100W x 120Himage from your staticfiles.
Given a template name ofpath/to/template.htmit will try and loadpath/to/template.htm.pngprefixed
by whatever yourSTATIC_URLis. If no file exists, a placeholder image is
shown as a fallback.Both this and theTemplateFieldmake use of…nice_display_nameThis function is the default callable for thedisplay_namearguments on
theTemplateFieldandTemplateChoiceField, it tries to provide some
flexibility and sensisble defaults; specifically:If your project defines aTEMPLATESELECTOR_DISPLAY_NAMESsetting which
is a dictionary like{'path/to/template.html': "my awesome template"}then
the name"my awesome template"will be shown by preference.If not set, or no key match is found, the function will take thefile name(not the path!) withoutany extensionand will attempt to make a pretty, readable
name of it by replacing most non-alphabet characters with spaces, so
the templatetest/app/hello_world.htmlwould becomeHello worldSupported Django versionsThe tests are run against Django 1.11 on Python 2.7, and 3.5.
The widget uses the Django 1.11 template-based-rendering, so won’t work on
previous versions. Possibly it’ll just default back to a normal radiobox? I dunno.Installation and usageInstallationYou can usepipto install the0.2.5version fromPyPI:pip install django-templateselector==0.2.5Or you can grab it fromGitHublike this:pip install -e git+https://github.com/kezabelle/django-template-selector.git#egg=django-template-selectorConfigurationTo get theTemplateSelectorwidget to display correctly, youwillneed to
addtemplateselectorto your project’sINSTALLED_APPS.You may also wish to configureTEMPLATESELECTOR_DISPLAY_NAMES = {}to provide
nice names (seenice_display_name)UsageFor using theTemplateField, try something like this:from django.db.models import Model
from templateselector.fields import TemplateField

class MyPage(models.Model):
  template = TemplateField(match='^myapp/mypage/layouts/.+\.html$')For using theTemplateChoiceFieldwithout using the Model field, you’d
do something like:from django.forms import Form
from templateselector.fields import TemplateChoiceField

class MyForm(Form):
    field = TemplateChoiceField(match="^myapp/[0-9]+.html$")To get the widget’s CSS, don’t forget to use{{ form.media }}in your template!Altering the widget choice sizeIf you’d like to modify the dimensions used for each option in the widget (eg:
you have landscape template thumbnails instead of portrait) you’ll need to
override the following CSS classes:.templateselector-list-item {
    width: ???;
}
.templateselector-label input {
    top: ???;
}
.templateselector-thumb {
    width: ???;
    height: ???;
}You can probably use the#id_FIELDNAMEfor a given field to provide the
necessary specificity.You may need to provide a wrapper element if you re-use the same model/form
attribute name (eg:{{ myform.selected_file }}) for multiple things with
different dimensions:<!-- target with
.myform-wrapper #id_selected_file .templateselector-list-item
etc -->
<div class="myform-wrapper">{{ myform.selected_file }}</div>

<!-- target with
.myapp-wrapper #id_selected_file .templateselector-thumb
 etc -->
<div class="myapp-wrapper">{{ mymodelform.selected_file }}</div>Running the testsIf you have a cloned copy, you can do:python setup.py testIf you have tox, you can just do:toxRunning the demoA barebones demo is provided. It assumes you’re using something likevirtualenvandvirtualenvwrapperbut you can probably figure it out otherwise:mktmpenv --python=`which python3`
pip install -e git+https://github.com/kezabelle/django-template-selector.git#egg=django-templateselectorThen probably:cd src/django-templateselector
python demo_project.py runserverThe index page/will show you a normal version of the selection widget,
while/admin/tests/mymodel/add/will show the slightly customised version
for the standardDjangoadmin.The licenseIt’s theFreeBSD. There’s should be aLICENSEfile in the root of the repository, and in any archives.Copyright (c) 2017, Keryn Knight
All rights reserved.Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.Change history for django-templateselector0.2.5BUGFIX:Added:focusvisual styles so that keyboard navigation through a form
including the widget may now indicate when selecting items.0.2.4FEATURE:Added asystem checkto ensure that the templates and styles are
able to be loaded.0.2.3BUGFIX:Change the model level field validation (TemplateField(match=...)to
forcibly check the given value matches the regex, in addition to checking
whether the given value exists in one of the template loaders.MISC:Still trying to master automatic deployment from Travis. One day I’ll
get sdist working again!0.2.2MISC:Still trying to master automatic deployment from Travis. No
functionality change since0.2.00.2.1MISC:Automatic deployment of new releases from Travis mostly worked, but thesdistis in poor shape (see commit44ad2a1542f2f61a73de84e0f7213bccfdb6f265)
so I’ve disabled that for now. Wheels are better anyway, right? No
functionality change since0.2.00.2.0BUGFIX:prevent the “same” template showing up more than once in the
widget, which wouldn’t be possible when usingget_template(#1)FEATURE:If the form field (TemplateChoiceField) has onlyonevalid template
option, and the form is unbound (ie: its anaddform or whatever) then
pre-select the valid choice. Only happens if the field hasrequired=TrueFEATURE:using theget_<fieldname>_displayas a value in a`ModelAdmin.list_displaywill now allow for sorting by the underlying value in the database. (#2)FEATURE:if the<fieldname>is used as part of aModelAdmin.list_filterit will
show the nice display names of any used templates, rather than their internal
path representation. (#3)0.1.1MISC:First release on PyPI.0.1.0MISC:Initial development.