Getting Started¶
Installation¶
Bare functionality:
pip install kegelements
Internationalization extensions:
pip install kegelements[i18n]
Templates¶
Jinja templates are made available for rendering forms. To have these included in a keg app, include the core blueprint in the app:
from keg import Keg
from keg_elements.core import keg_element_blueprint
from my_app.views import public_bp, private_bp
class MyApp(Keg):
import_name = 'my_app'
use_blueprints = [public_bp, private_bp, keg_element_blueprint]
Note, if you are using keg-auth in your app, the above is not required. That library pulls in the templates to support auth views.
For base templates that help standardize form/grid views, the template to extend is referenced from settings. The first of these defined is used:
BASE_TEMPLATE
KEG_BASE_TEMPLATE
Form selects are rendered with select2 in templates extending keg-elements/form-view.html
.
keg-elements/select2-scripts.html
and keg-elements/select2-styles.html
can be included
in templates to render select2s without extending form-view. Apps can opt out of select2
rendering with KEG_USE_SELECT2
config.
Data Model¶
KegElements provides model mixins with helpful default columns and methods:
from keg.db import db
from keg_elements.db.mixins import DefaultMixin
class Thing(DefaultMixin, db.Model):
__tablename__ = 'things'
# id, created_utc, updated_utc provided via mixin
# tests can use Thing.fake() to get an instance with random data
name = db.Column(db.Unicode(50), nullable=False)
color = db.Column(db.Unicode)
Forms¶
KegElements extends wtforms-alchemy model form generation with some custom fields, an optional meta info override, and additional validation:
from keg_elements.forms import FieldMeta, ModelForm, form_validator
from my_app.model import entities as ents
class RelatedThingForm(ModelForm):
class Meta:
model = ents.RelatedThing
include_foreign_keys = True
class FieldsMeta:
name = FieldMeta('Fancy Label')
@form_validator
def validate_name(self):
# do validation here
Internationalization¶
KegElements supports Babel-style internationalization of text strings through the morphi library. To use this feature, specify the extra requirements on install:
pip install kegelements[i18n]
Currently, English (default) and Spanish are the supported languages in the UI.
Helpful links¶
Message management¶
The setup.cfg
file is configured to handle the standard message extraction commands. For ease of development
and ensuring that all marked strings have translations, a tox environment is defined for testing i18n. This will
run commands to update and compile the catalogs, and specify any strings which need to be added.
The desired workflow here is to run tox, update strings in the PO files as necessary, run tox again (until it passes), and then commit the changes to the catalog files.
tox -e i18n
Upgrade Notes¶
While we attempt to preserve backward compatibility, some KegElements versions do introduce breaking changes. This list should provide information on needed app changes.
0.8.0
pytest
removed support for nose-style methods, so base test classes (e.g.EntityBase
) now usesetup_method
instead ofsetup
MethodsMixin’s
testing_create
renamed tofake
for brevityBootstrap 4 “horizontal” form templates had been broken and were displaying forms in the vertical style instead. This has been resolved, which means forms will change to showing with horizontal layout. If this is not desired, you will need to override the form templates/macros.
Tab index setting has been removed from the form macro templates. tabindex > 0 is not recommended for accessibility. The _field_order attribute of the form should be used to indirectly control tab order, instead of setting tabindex explicitly.
Template files now follow keg’s more recent naming scheme to use dashes instead of underscores. E.g.
keg_elements/forms/horizontal_b4.html
becamekeg-elements/forms/horizontal-b4.html
The older Bootstrap 3 macro template (
horizontal.html
) has been renamed for namespacing tohorizontal-b3.html
.keg-elements/form-view.html
andkeg-elements/grid-view.html
are now available, but need a config value (eitherBASE_TEMPLATE
orKEG_BASE_TEMPLATE
) set to represent the parent to extend.forms now have an ident field built-in to assist in identifying the form from POSTed data. If a form’s render is customized in the template layer, the ident field may be missing. A few options for moving forward:
add the field in render (identified by the result of the form’s
_form_ident_key
method)turn off ident validation by setting
_form_ident_strict
toFalse
on the form classturn off the field by setting
_form_ident_enabled
toFalse
on the form class