{ "info": { "author": "D.A.Dokter", "author_email": "dokter@w20e.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Framework :: Plone", "Framework :: Pylons", "Intended Audience :: Developers", "License :: OSI Approved :: GNU General Public License (GPL)", "Operating System :: OS Independent", "Programming Language :: Python" ], "description": ".. contents:: Table of Contents\n\nThe w20e.forms package provides a powerful API for creating and\nhandling electronic forms. The package is loosely based on XForms\nconcepts (and Socrates QE, a Java implementation). The package intends\nto provide a drop-in alternative for standard plone, pyramid and\ndjango solutions, but is useable in any framework (or without a\nframework...).\n\n\nCore concepts\n=============\n\nThe core concepts are as follows (so you can quickly decide whether\nyou like this approach or not):\n\nA form is a container for/composition of four things:\n\n1. data\n2. model\n3. view\n4. submission\n\nThis clearly separates the data, the data's properties (datatype,\nwhether something is required or not, etc.) and the renderable part of\nthe form. This is also the main difference between this API and other\nsolutions (afaik...). Where the usual approach is to define a form\nbased on a *Schema* or other data-centered notion, like so::\n\n foo = String(\"id\", \"label\", validator=somefunction)\n\nthe approach of w20e.forms is to define::\n\n foo = Field(\"fid\")\n props = FieldProperties(\"pid\", [\"fid\"], required=True, datatype=int)\n ctrl = Input(\"cid\", \"label\", bind=\"fid\")\n\nwhere the properties and control are *bound* to the variable. This\nenables controls in your form that are not bound to any data you wish\nto collect, sharing of properties, etc.\n\nAnother important difference is that the API provides a structured way\nof defining properties for data, instead of having to define your own\nvalidation. See section 1.2 for details.\n\n\nData\n----\n\nThe data holds the variables you wish to collect with this form. A\nvariable simply has an id, and if you like a default value.\n\n\nModel\n-----\n\nThe model holds all properties for a given form, like readonly-ness,\nrequiredness, datatyping for variables, relevance, etc. All these\nproperties are calculated from expressions, in this case Python\nexpressions, so requiredness is not just true or false, it can be\ncalculated based on an expression that can include other variables in\nyour data. All variables from the form data are available in\nexpressions via the 'data' dict, so if variable 'foo' would be\nrequired if variable 'bar' was set to 666, this can be expressed like\nso in the properties bound to foo:\n\n ... required=\"data['bar'] == 666\" ...\n\nIn general, all expressions are eval-ed to something true or\nfalse. The model offers the following properties:\n\n* required: is a variable required or not?\n* relevant: is the variable relevant? Like maiden name would be irrelevant\n when gender is male. In general, the related control/widget for irrelevant \n variables would not be shown.\n* readonly: can a person change the value of a variable?\n* calculate: in stead of letting a person set the value of a variable, the\n variable is calculated.\n* constraint: check whether the expression evaluates to True.\n* datatype: datatype for the variable, like int, string, or more complex\n variables.\n\nProperties are bound to variables by a bind attribute. A set of\nproperties can be bound to a series of variables.\n\n\nView\n----\n\nThe view (or FormView) is the actual visible part (or audible for that\nmatter) of the form. The view can be rendered and holds a collection\nof widgets or controls, that are bound to variables. More than one\ncontrol can bind to the same variable. Controls can be grouped in\ngroups for layout purposes, like flow layout or card layout (tabs).\n\nIn label and hint texts of controls you can use lexical values of\nvariables by using the expression ${}. This way you can refer to\nvalues given in other variables from your labels and hints.\n\n\nBasic use\n=========\n\nOk, enough theory, let's do something for real.\n\nA form is produced by hand, or by using a factory: this should take\ncare of producing a form holding the necessary stuff.\n\nLet's get the imports over with...\n\n >>> import sys\n >>> from interfaces import *\n >>> from zope.interface import implements\n >>> from formdata import FormData\n >>> from formview import FormView\n >>> from formmodel import FormModel\n >>> from data.field import Field\n >>> from model.fieldproperties import FieldProperties\n >>> from rendering.control import Input, Select, Option\n >>> from rendering.group import FlowGroup\n >>> from form import Form, FormValidationError\n >>> from rendering.html.renderer import HTMLRenderer\n >>> from submission.attrstorage import AttrStorage\n\nCreating a form\n---------------\n\nNow let us create a factory class\n\n >>> class FormFactory():\n ... implements(IFormFactory)\n ... def createForm(self):\n ... data = FormData()\n ... data.addField(Field(\"field0\"))\n ... data.addField(Field(\"field1\", \"foo\"))\n ... data.addField(Field(\"field2\", \"bar\"))\n ... data.addField(Field(\"field3\"))\n ... view = FormView()\n ... grp = FlowGroup(\"grp0\", label=\"Group 0\")\n ... grp.addRenderable(Input(\"input2\", \"Input 2\", bind=\"field0\"))\n ... view.addRenderable(Input(\"input0\", \"First name\", bind=\"field0\"))\n ... view.addRenderable(Input(\"input1\", \"Last name\", bind=\"field1\"))\n ... view.addRenderable(Select(\"select0\", \"Select me!\", options=[], bind=\"field2\", with_empty=True))\n ... view.addRenderable(grp)\n ... model = FormModel()\n ... model.addFieldProperties(FieldProperties(\"prop0\", [\"field0\"], required=\"True\"))\n ... model.addFieldProperties(FieldProperties(\"prop1\", [\"field1\", \"field2\"], relevant=\"data['field0']\"))\n ... submission = AttrStorage(attr_name=\"_data\")\n ... return Form(\"test\", data, model, view, submission)\n\n >>> ff = FormFactory()\n >>> form = ff.createForm()\n\nBy now, we should have a form where field0 is required, and field1 and\nfield2 are only relevant if field0 is filled in.\n\n >>> print len(form.data.getFields())\n 4\n\n >>> props = form.model.getFieldProperties(\"field0\")\n >>> props[0].id\n 'prop0'\n\n >>> len(props)\n 1\n\n >>> field0 = form.data.getField(\"field0\")\n >>> field0.id\n 'field0'\n\n >>> field0.value\n\nIn the meanwhile, field1 and field2 should be irrelevant, given that field0\nhas no value\n\n >>> form.model.isRelevant(\"field1\", form.data)\n False\n >>> form.model.isRelevant(\"field2\", form.data)\n False\n\nValidation should fail, given that field0 is required.\n\n >>> try:\n ... form.validate()\n ... except FormValidationError:\n ... print sys.exc_info()[1].errors['field0']\n ['required']\n\n >>> form.data.getField(\"field0\").value = \"pipo\"\n >>> form.validate()\n True\n\n >>> field0.value\n 'pipo'\n\nBy now, field1 and field2 should also be relevant\n\n >>> form.model.isRelevant(\"field1\", form.data)\n True\n >>> form.model.isRelevant(\"field2\", form.data)\n True\n\nDisplay\n-------\n\nThe following section will assume rendering to HTML. This will most\nlikely cover nigh 100% of the use cases...\nNow for some display parts. An irrelevant control should\nnot have a class 'relevant', otherwise it should have it... This\nenables specific styling, like 'display: none'.\n\n >>> form.data.getField('field0').value = None\n >>> field = form.view.getRenderable('input1')\n >>> renderer = HTMLRenderer()\n >>> renderer.render(form, field, sys.stdout)\n
\n \n
\n
\n \n
\n\n >>> form.data.getField('field0').value = 'pipo'\n >>> field = form.view.getRenderable('input1')\n >>> renderer = HTMLRenderer()\n >>> renderer.render(form, field, sys.stdout)\n
\n \n
\n
\n \n
\n\n >>> field = form.view.getRenderable('input0')\n >>> renderer.render(form, field, sys.stdout)\n
\n \n
\n
\n \n
\n \nHow 'bout those extra classes...\n\n >>> renderer.render(form, field, sys.stdout, extra_classes=\"card\")\n
\n \n
\n
\n \n
\n\n >>> select = form.view.getRenderable('select0')\n >>> renderer.render(form, select, sys.stdout)\n
\n \n
\n
\n \n
\n\nDo we actually get grouped controls?\n\n >>> nested_input = form.view.getRenderable('input2')\n >>> nested_input.id\n 'input2'\n\nSubmission\n----------\n\nFinally when the form is rendered, filled in by someone, and\nvalidated, the data should normally go somewhere. This is by way of\nsubmission. We defined submission to be AttrStorage, something that\nstores the data in an attribute on some context. This is a case that\ncould be used in many frameworks, at least plone and pyramid.\n\nLet's see what it does:\n\n >>> class Context:\n ... \"\"\" some context \"\"\"\n >>> ctx = Context()\n >>> form.submission.submit(form, ctx)\n\nThe context now should hold the data in an attribute. We specified the\nname of the attribute to be '_data', so let's check:\n\n >>> ctx._data.getField('field0').value\n 'pipo'\n\n\nBeyond the basics\n=================\n\nWell, this is all very simple, and it is quite likely that you would\nwish for something a bit more usefull. All parts of the form are there\nto be extended. Take for instance the FormView. A developer (or end\nuser) should be able to:\n\n * create a full HTML form;\n * use a generated HTML form (this is wat the base implementation does);\n * create a PDF form.\n\nThe factory is also an important part of the form process. A factory\ncan be imagined to be one of the following:\n\n * produced from a Schema (content type);\n * produced from an XML definition, for example an XForms instance from\n OpenOffice.\n\nForms in general should be:\n\n * submitable to a range of handlers, like email, database storage,\n content type storage;\n * easy to validate 'live;\n * enable multi-page.\n\nMore detailed tests:\n\nWe'd like to check whether lookup of a control by bind works, so as to\nbe able to process values into lexical values. This is especially\ninteresting when using selects: we'd expect to see the label not the\nvalue in lexical space.\n\n >>> data = FormData()\n >>> data.addField(Field(\"f0\", \"opt0\"))\n >>> view = FormView()\n >>> opts = [Option(\"opt0\", \"Option 0\"), Option(\"opt1\", \"Option 1\")]\n >>> view.addRenderable(Select(\"sel0\", \"Select 0\", bind=\"f0\", options=opts))\n >>> ctl = view.getRenderableByBind(\"f0\")\n >>> ctl.lexVal(\"opt0\")\n 'Option 0'\n\n\nCan we use variable substitution in labels and hints? Yes, we can!\n\n >>> data = FormData()\n >>> data.addField(Field(\"f0\", \"Pipo\"))\n >>> data.addField(Field(\"f1\"))\n >>> view = FormView()\n >>> view.addRenderable(Input(\"in0\", \"First name\", bind=\"f0\"))\n >>> view.addRenderable(Input(\"in1\", \"Last name for ${f0}\", bind=\"f1\"))\n >>> model = FormModel()\n >>> form = Form(\"test\", data, model, view, None)\n >>> renderer = HTMLRenderer()\n >>> field = form.view.getRenderable('in1')\n >>> renderer.render(form, field, sys.stdout)\n
\n \n
\n
\n \n
\n\nLet's delve into input processing a bit...\nA simple input should just return it's own value\n\n >>> data = {'pipo': 'lala'}\n >>> ctl = Input(\"pipo\", \"f0\", \"Some input\")\n >>> ctl.processInput(data)\n 'lala'\n\n\nRegistering your own stuff\n==========================\n\nw20e.forms is not a complete library for forms, and it will never be\nthis, since most people have very specific needs, like a specific\nwidget, a custom version of an input field, etc. The API facilitates\nin this by using a global registry to register extensions.\n\nThe global registry is available like so:\n\n >>> from w20e.forms.registry import Registry\n\nand offers a number of class methods to register stuff. \n\nLet's for exampe register a new renderer for an input:\n\n\nVocabularies\n------------\n\nw20e.forms enables use of vocabularies to limit possible answers to a\ngiven list. This is a feature that is generally used with select\nwidgets. A vocabulary is a 'named' factory that creates a list of\noptions. \n\nRegister like so:\n\n>>> def make_vocab():\n... return [Option('0', 'Opt 0'), Option('1', 'Opt 1')]\n... Registry.register_vocab('foovocab', make_vocab)\n... sel = Select(\"select0\", \"Select me!\", vocab=make_vocab,\n... bind=\"field2\", with_empty=True))\n\n\nRequired, Relevant, Readonly\n----------------------------\n\nIn a form you'll usually want to say things like: this control need\nonly be shown whan the answer to that question is 'x', or that\nquestion is required whenever the answer to somethind else is 'y'.\n\nw20e.forms enables this using expressions. The epxressions are set as\nproperties in variables, by their 'bind' attribute. So in the form\nmodel you may have a property set named 'req', that makes\nvariable 'foo' required like so:\n\n model.addFieldProperties(FieldProperties(\"req\", [\"foo\"], required=\"True\"))\n\nObviously in general you want something a bit more flexible than that,\nlike checking for other data that has been entered. All form data is\nmade available to the expression within the 'data' variable, that is a\ndict. So checking upon some other variable, goes like this:\n\n model.addFieldProperties(FieldProperties(\"req\", [\"foo\"],\n required=\"data['bar'] == 42\"))\n\nSo only if the answer to 'bar' is 42, 'foo' is required. Relevance,\nrequiredness and readonly-ness all work like this.\n\nYou may even add your own expression context to the engine, to call\nmethods on objects, etc.\n\nGo like this, assuming your object is obj:\n\n>>> registry.register_expr_context('mycontext', obj)\n... model.addFieldProperties(FieldProperties(\"req\", [\"foo\"],\n... relevant=\"mycontext.some_method())\n\n\nXML\n===\n\nThe xml namespace of the w20e.forms package provides an XML based\nimplementation of the w20e.forms API. This enables definition from\nand serialization to XML files. Provided is the DTD used for defining\nthe w20e.forms as XML. This is quite similar to xForms.\n\nUsing XML as definition of forms provides a more declarative way of\ncreating forms, not unlike the way you create a form in HTML. Also, XML is a format that is easily stored and transported.\n\n\nStart using the XML factory\n\n >>> from factory import XMLFormFactory\n\nNow let us create a factory class\n\n >>> xml = \"\"\"\n ...
\n ...\n ... \n ... \n ... \n ... \n ... \n ...\n ... \n ... \n ... foo\n ...\tbar\n ...\tTrue\n ... \n ... \n ... bar\n ...\tint\n ... \n ... \n ...\n ... \n ... \n ... \n ... Well, foo or no?\n ... \n ... \n ... \n ... \n ... \n ... \n ... Moi\n ... \n ... \n ...\n ... \n ... @@save\n ... \n ...\n ...
\"\"\"\n\n We are using a vocab in the xml, so register it...\n >>> from w20e.forms.registry import Registry\n ... def some_vocab():\n ... return [Option(0, 0), Option(1, 1)]\n ... Registry.register_vocab('some_vocab', some_vocab)\n\n >>> xmlff = XMLFormFactory(xml)\n >>> form = xmlff.create_form()\n >>> print len(form.data.getFields())\n 2\n\n >>> print form.data.getField(\"foo\").id\n foo\n\n >>> print form.data.getField(\"bar\").value\n 666\n\n Set the value \n\n >>> form.data.getField(\"bar\").value = 777\n >>> print form.data.getField(\"bar\").value\n 777\n\n Okido, so far so good. Now let's see what properties we have.\n \n >>> props = form.model.getFieldProperties(\"bar\")\n >>> len(props)\n 2\n\n >>> intprop = [prop for prop in props if prop.id == \"int\"][0]\n >>> reqprop = [prop for prop in props if prop.id == \"required\"][0]\n >>> reqprop.getRequired()\n 'True'\n \n >>> intprop.getDatatype()\n 'int'\n\n Finally, check the viewable part, or the controls\n >>> ctrl = form.view.getRenderable(\"fooctl\")\n >>> ctrl.label\n 'Foo?'\n\n >>> ctrl.__class__.__name__\n 'Input'\n\n >>> ctrl.hint\n 'Well, foo or no?'\n\n >>> ctrl.id\n 'fooctl'\n\n >>> ctrl.bind\n 'foo'\n\n >>> ctrl = form.view.getRenderable(\"barctl\")\n >>> ctrl.multiple\n 'False'\n\n >>> len(ctrl.options)\n 2\n\nDo we get the nested stuff?\n >>> ctrl = form.view.getRenderable(\"txt\")\n >>> ctrl.id\n 'txt'\n\n\nSerialization\n-------------\n\nYou can easily serilialize the form back into XML. Let's try...\n\n >>> from serializer import XMLSerializer\n >>> serializer = XMLSerializer()\n >>> print serializer.serialize(form)\n
\n \n \n \n \n \n \n bar\n \t int\n \n \n foo\n \t bar\n \t True\n \n \n\t\n \t \n \n Well, foo or no?\n \n \n \n \n \n \n \n \n \n\t @@save\n\t\n
\n \n\nNote that variable foo now holds the value 777. Sadly, it is hard to\nguarantee that all XML will be exactely the same as the input XML.\n\n\nPyramid\n=======\n\nThe pyramid package provides a simple means of using w20e.forms for pyramid\napps. The package provides a specific 'file' field for pyramid, to enable\nextracting filename and contents from a file in a POST/GET request, and a base\nview.\n\nWould you wish to use w20e.forms, then:\n\n * add w20e.forms to the eggs dependencies of your app (duh...)\n\n * for the view that you wish to show the actual form, override\n w20e.forms.pyramid.pyramidformview. Let's do some imports\n first. Please note that it is more convenient to use the XML\n implementation, as shown later on. Also, if you insist on using the\n Pythonic implementation, it is better to make a factory create the\n form, so you can just call the factory from your view. Anyway,\n let's go for the not-so-smart way:\n\n >>> from w20e.forms.form import Form\n >>> from w20e.forms.formdata import FormData\n >>> from w20e.forms.formmodel import FormModel\n >>> from w20e.forms.formview import FormView\n >>> from w20e.forms.submission.attrstorage import AttrStorage\n >>> from w20e.forms.data.field import Field\n >>> from w20e.forms.rendering.control import Input\n >>> from w20e.forms.pyramid.formview import formview as pyramidformview\n \n Phew, that was a load of imports. Now do the actual view\n class. It's a pretty simple form, but you should get the picture.\n\n >>> class yourformview(pyramidformview):\n ... def __init__(self, context, request):\n ... data = FormData()\n ... data.addField(Field(\"foo\", \"some default value\"))\n ... data.addField(Field(\"bar\"))\n ... model = FormModel() \n ... view = FormView()\n ... # We'll leave the poperties out for now, check the main\n ... # README for details\n ... view.addRenderable(Input(\"input0\", \"Input foo\", bind=\"foo\"))\n ... view.addRenderable(Input(\"input1\", \"Input bar here\", bind=\"bar\"))\n ... submission = AttrStorage(attr_name=\"_data\")\n ... form = Form(\"test\", data, model, view, submission)\n ... pyramidformview.__init__(self, context, request, form)\n\n Now, a view for pyramid just takes a context, and a request, so let's \n create the view instance:\n\n >>> class Context:\n ... \"\"\" nothing needed here, but we'll store the data in here \"\"\"\n >>> class Request:\n ... def __init__(self, params=None):\n ... self.params = params\n >>> ctx = Context()\n >>> req = Request()\n >>> view = yourformview(ctx, req)\n\n Ok, we're ready for some action now. Let's try to render the form.\n\n >>> print view.renderform()\n
\n \n
\n
\n \n
\n
\n \n
\n
\n \n
\n
\n \n
\n
\n \n\n Nice. Now let's give the request some content, and let the view handle the\n submission. This should result in the context having the form data stored\n in the _data attribute. formprocess is the marker used by w20e.forms\n to assume that the form is posted.\n\n >>> req = Request({'formprocess': 1, 'input0': 6, 'input1': 'whatever'})\n >>> view = yourformview(ctx, req)\n >>> view()\n {'status': 'stored', 'errors': {}}\n >>> ctx._data.getField('foo').value\n 6\n >>> ctx._data.getField('bar').value\n 'whatever'\n\n\nXML implementation\n------------------\n\n Using the XML implementation makes life even easier::\n\n from w20e.forms.pyramid.formview import xmlformview as pyramidformview\n from w20e.forms.xml.formfile import FormFile\n\n class yourformview(pyramidformview):\n \n def __init__(self, context, request):\n pyramidformview.__init__(self, context, request, FormFile(\"forms/yourform.xml\"))\n\n where you have a directory 'forms' containing the XML definition\n called yourform.xml. Check the w20e.forms.xml module for details\n on XML definitions.\n\n\n * Create a template (form.pt for example) that calls the render\n method of the view::\n\n

\n\n\n * Wire the stuff into zcml (assuming you use that), like so::\n \n ", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "UNKNOWN", "keywords": "forms", "license": "GPL", "maintainer": null, "maintainer_email": null, "name": "w20e.forms", "package_url": "https://pypi.org/project/w20e.forms/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/w20e.forms/", "project_urls": { "Download": "UNKNOWN", "Homepage": "UNKNOWN" }, "release_url": "https://pypi.org/project/w20e.forms/1.0.2b/", "requires_dist": null, "requires_python": null, "summary": "Python API for creating and handling forms", "version": "1.0.2b" }, "last_serial": 801482, "releases": { "1.0.0a": [ { "comment_text": "", "digests": { "md5": "0ad5d724fe3f7d3b40cd92ad009c8a50", "sha256": "c3fecdd332fe1802f9c63695f718b881fbd699b5cc63109c5d908922303c05ba" }, "downloads": -1, "filename": "w20e.forms-1.0.0a.tar.gz", "has_sig": false, "md5_digest": "0ad5d724fe3f7d3b40cd92ad009c8a50", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 46262, "upload_time": "2012-07-10T12:22:59", "url": "https://files.pythonhosted.org/packages/56/fe/852916d6311081a9ba17b46231930dc4f4a989e9b94f5e3c1523e4dc9ca3/w20e.forms-1.0.0a.tar.gz" } ], "1.0.2b": [ { "comment_text": "", "digests": { "md5": "fe34744c9fc3e7e00898b49ef886b7c8", "sha256": "2c06945271aa0dca4f540bc0a093a01e06db718e54192ef0f353b1f6ceb7b06a" }, "downloads": -1, "filename": "w20e.forms-1.0.2b.tar.gz", "has_sig": false, "md5_digest": "fe34744c9fc3e7e00898b49ef886b7c8", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 49583, "upload_time": "2013-02-05T12:07:18", "url": "https://files.pythonhosted.org/packages/4b/51/52e615cc75761725acae43cc602ddc53723dad78d35812e8ad3b111b7e05/w20e.forms-1.0.2b.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "fe34744c9fc3e7e00898b49ef886b7c8", "sha256": "2c06945271aa0dca4f540bc0a093a01e06db718e54192ef0f353b1f6ceb7b06a" }, "downloads": -1, "filename": "w20e.forms-1.0.2b.tar.gz", "has_sig": false, "md5_digest": "fe34744c9fc3e7e00898b49ef886b7c8", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 49583, "upload_time": "2013-02-05T12:07:18", "url": "https://files.pythonhosted.org/packages/4b/51/52e615cc75761725acae43cc602ddc53723dad78d35812e8ad3b111b7e05/w20e.forms-1.0.2b.tar.gz" } ] }