1

"""

     2

    Form rendering and handling

     3

"""

     4

     5

from svv.html import tags

     6

from svv import database as db

     7

     8

import collections

     9

import datetime

    10

import logging

    11

    12

try :

    13

    # Python2.6 stdlib

    14

    import json

    15

    16

except ImportError :

    17

    # simplejson, API should be similar

    18

    import simplejson as json

    19

    20

    21

log = logging.getLogger('svv.forms')

    22

    23

class FormError (Exception) :

    24

    """

    25

        A user-level error in a form field

    26

    """

    27

    28

    def __init__ (self, field, value, error) :

    29

        """

    30

                field       - name of field with error

    31

                value       - the errenous value in the form that we recieved it

    32

                              may be None if it was the *lack* of a value that caused the issue

    33

                error       - descriptive text for user

    34

        """

    35

    36

        self.field = field

    37

        self.value = value

    38

    39

        super(FormError, self).__init__(error)

    40

    41

class BaseForm (object) :

    42

    # processed POST data

    43

    data = None

    44

    45

    def __init__ (self) :

    46

        """

    47

            Setup state.

    48

    49

            Note that a Form is stateful, and should only be used for one form transaction.

    50

        """

    51

    52

        # accumulated errors

    53

        self.errors = collections.defaultdict(list)

    54

    55

    def defaults (self) :

    56

        """

    57

            Update our attributes with default values

    58

        """

    59

    60

        raise NotImplementedError()

    61

    62

    def fail_field (self, form_error, field=None) :

    63

        """

    64

            Mark the field mentioned inside the given FormError as failed.

    65

    66

                form_error      - the FormError to store

    67

                field           - the name of the field to store the error under, if not the same as in form_error

    68

        """

    69

    70

        field = field or form_error.field

    71

    72

        log.warn("Marking field %s as failed: %s", field, form_error)

    73

    74

        self.errors[field].append(form_error)

    75

    76

    def build_name_for_armed_input (self, name) :

    77

        """

    78

            Return the name used for the checkbox associated with the named armed text input

    79

        """

    80

    81

        return name + '_enabled'

    82

    83

    84

    def process_raw_field (self, name, default=None, required=None) :

    85

        """

    86

            Process a generic incoming data field.

    87

    88

                default         - value to return if no value was present

    89

                required        - raise a FormError if no value present

    90

    91

            Returns the value as a str, or default

    92

        """

    93

    94

        if name in self.data :

    95

            return self.data[name]

    96

    97

        elif required :

    98

            raise FormError(name, None, "Required field")

    99

   100

        else :

   101

            return default

   102

   103

    def process_text_field (self, name, default=None, required=None, strip=True) :

   104

        """

   105

            Process a generic incoming string field.

   106

   107

            Trims extra whitespace from around the value, unless strip=False is given.

   108

   109

            Returns the value as unicode, or default.

   110

        """

   111

   112

        value = self.process_raw_field(name, required=required)

   113

   114

        if value is None :

   115

            return default

   116

   117

        try :

   118

            # XXX: decode somehow, or can werkzeug handle that?

   119

            value = unicode(value)

   120

   121

        except UnicodeDecodeError :

   122

            raise FormError(name, value, "Failed to decode Unicode characters")

   123

   124

        if strip :

   125

            value = value.strip()

   126

   127

        return value

   128

   129

    def process_integer_field (self, name, default=None, required=None) :

   130

        """

   131

            Process a generic incoming int field.

   132

   133

            If the field is empty, uses the default value.

   134

   135

            Returns the value as int, or default.

   136

        """

   137

   138

        value = self.process_raw_field(name, required=required)

   139

   140

        if not value:

   141

            # not included in POST, or empty

   142

            return default

   143

   144

        try :

   145

            return int(value)

   146

   147

        except ValueError :

   148

            raise FormError(name, value, "Must be a number")

   149

   150

    DATETIME_FORMAT = "%d.%m.%Y %H:%M"

   151

   152

    def process_datetime_field (self, name, default=None, required=None, format=DATETIME_FORMAT) :

   153

        """

   154

            Process an incoming datetime field.

   155

   156

            Returns the value as datetime, or default.

   157

        """

   158

   159

        value = self.process_raw_field(name, required=required)

   160

   161

        if value is None :

   162

            return default

   163

   164

        try :

   165

            return datetime.datetime.strptime(value, format)

   166

   167

        except ValueError, ex :

   168

            raise FormError(name, value, "Invalid date/time value: " + str(ex))

   169

   170

    def process_checkbox_field (self, name, required=None) :

   171

        """

   172

            Process an incoming checkbox input's value.

   173

   174

            Any non-empty/non-whitespace value will be accepted as True.

   175

        """

   176

   177

        value = self.process_raw_field(name, required)

   178

   179

        if not value and required :

   180

            raise FormError(name, value, "Must be checked")

   181

   182

        elif value and value.strip() :

   183

            # checked

   184

            return True

   185

   186

        else :

   187

            # unchecked

   188

            return False

   189

   190

    def process_armed_text_field (self, name, required=None) :

   191

        """

   192

            A text field that must be enabled by a checkbox before being used.

   193

   194

            If not enabled, returns False. Otherwise, text field value, and fails if empty but required.

   195

        """

   196

   197

        checkbox_name = self.build_name_for_armed_input(name)

   198

   199

        if self.process_checkbox_field(checkbox_name) :

   200

            # use input value

   201

            return self.process_text_field(name, required=required)

   202

   203

        else :

   204

            # not selected

   205

            return False

   206

   207

    def process_action_field (self, name, required=None) :

   208

        """

   209

            Given a form with multiple named submit buttons, checks if the given one was used to submit the form.

   210

   211

            If required, raises a FormError if the button wasn't pressed.

   212

        """

   213

   214

        value = self.process_raw_field(name, required)

   215

   216

        if value and value.strip() :

   217

            # pressed

   218

            return True

   219

   220

        elif required :

   221

            raise FormError(name, None, "Must be pressed")

   222

   223

        else :

   224

            # some other submit was hit

   225

            return False

   226

   227

    def process_list_field (self, name, required=None, type=unicode) :

   228

        """

   229

            Process an incoming multi-value field, returning the full list of values, converted using the given converter.

   230

   231

            Returns an empty list if no incoming values, and not rquired.

   232

   233

            XXX: doesn't strip() the values

   234

        """

   235

   236

        if name not in self.data and required :

   237

            # fail

   238

            raise FormError(name, None, "No values given")

   239

   240

        elif name not in self.data :

   241

            # empty/default

   242

            return []

   243

   244

        else :

   245

            # type'd list of values

   246

            # uses werkzeug's MultiDict API

   247

            return self.data.getlist(name, type)

   248

   249

    def process_multifield (self, table, id, fields) :

   250

        """

   251

            Process a set of user-given field values for an object with an unique id, and some set of additional fields.

   252

   253

            If the id is given, look up the corresponding field values, and return those.

   254

   255

            If any of the fields are given, either look up a matching row, or create a new one, and return its id.

   256

   257

            Returns an (id_name, field_name, ...) N-tuple.

   258

        """

   259

   260

        id_name, id_col, id_value = id

   261

   262

        if id_value :

   263

            # look up object from db

   264

            columns = [col for name, col, value in fields]

   265

   266

            sql = db.select(columns, (id_col == id_value))

   267

   268

            for row in self.app.query(sql) :

   269

                # XXX: sanity-check row values vs our values

   270

   271

                # new values

   272

                fields = tuple(

   273

                    (name, col, row[col]) for name, col, value in fields

   274

                )

   275

   276

                # ok, just use the first one

   277

                break

   278

   279

            else :

   280

                # not found!

   281

                raise FormError(id_name, id_value, "Item selected does not seem to exist")

   282

   283

            log.info("Lookup %s=%d -> %s", id_name, id_value, dict((name, value) for name, col, value in fields))

   284

   285

        elif any(value for name, col, value in fields) :

   286

            # look up identical object from db?

   287

            sql = db.select([id_col], db.and_(*[(col == value) for name, col, value in fields]))

   288

   289

            for row in self.app.query(sql) :

   290

                if id_value :

   291

                    log.warn("Duplicate %s=%d for %s", id_name, id_value, dict((name, value) for name, col, value in fields))

   292

   293

                # found object's id

   294

                id_value = row[id_col]

   295

   296

                log.info("Found %s -> %d", dict((name, value) for name, col, value in fields), id_value)

   297

   298

            # create new object?

   299

            if not id_value :

   300

                sql = db.insert(table).values(dict((col, value) for name, col, value in fields))

   301

   302

                id_value, = self.app.insert(sql)

   303

   304

                log.info("Create %s -> %d", dict((name, value) for name, col, value in fields), id_value)

   305

   306

        else :

   307

            # not known

   308

            log.debug("No %s known for order...", id_name)

   309

   310

        # return full set of values

   311

        return (id_value, ) + tuple(value for name, col, value in fields)

   312

   313

    def process (self, data) :

   314

        """

   315

            Bind ourselves to the given incoming POST data, and update our order field attributes.

   316

   317

                data        - the submitted POST data as a MultiDict

   318

   319

            Returns True if all fields were processed without errors, False otherwise.

   320

        """

   321

   322

        # bind

   323

        self.data = data

   324

   325

        raise NotImplmentedError()

   326

   327

        return not self.errors

   328

   329

    def render_text_input (self, name, value=None, multiline=False, rows=10, autoscale=True) :

   330

        """

   331

            Render HTML for a generic text field input.

   332

   333

                name            - field name, as used for POST

   334

                value           - default field value

   335

                multiline       - use a multi-line <textarea> instead

   336

                rows            - number of rows for <textarea> per default

   337

                autoscale       - automatically scale the <textarea> to the number of lines of text

   338

        """

   339

   340

        if multiline :

   341

            if autoscale and value :

   342

                rows = value.count('\n') * 5 / 4

   343

   344

            # XXX: textarea can't be self-closing for some reason?

   345

            return tags.textarea(name=name, id=name, rows=rows, _selfclosing=False, _whitespace_sensitive=True)(value)

   346

   347

        else :

   348

            return tags.input(type='text', name=name, id=name, value=value)

   349

   350

    def render_select_input (self, name, options, value=None) :

   351

        """

   352

            Render HTML for a generic select control.

   353

   354

                name            - field name, as used for POST

   355

                options         - sequence of (value, title) options. `value` may be None to omit.

   356

                value           - the selected value

   357

        """

   358

   359

        return tags.select(name=name, id=name)(

   360

            (

   361

                tags.option(value=opt_value, selected=('selected' if opt_value == value else None))(opt_title)

   362

            ) for opt_value, opt_title in options

   363

        )

   364

   365

    def render_datetime_input (self, name, value=None) :

   366

        """

   367

            Render HTML for a generic datetime control (using jQuery).

   368

   369

                name            - field name, as used for POST

   370

                value           - selected date

   371

        """

   372

   373

        return (

   374

            self.render_text_input(name, (value.strftime(self.DATETIME_FORMAT) if value else None)),

   375

   376

            tags.script("$(document).ready(function () { $('#" + name + "').datetimepicker(); });"),

   377

        )

   378

   379

    def render_checkbox_input (self, name, checked=None) :

   380

        """

   381

            Render HTML for a checkbox.

   382

        """

   383

   384

        return tags.input(type="checkbox", name=name, id=name, value="1",

   385

            checked=("checked" if checked else None)

   386

        )

   387

   388

    def render_armed_text_input (self, name, value=False, default=None) :

   389

        """

   390

            Render HTML for a text field that must be enabled by a checkbox before being used.

   391

   392

                value       - the three-state value

   393

                                False       - not checked, use default as value

   394

                                None        - checked, use empty value

   395

                                str         - checked, ues value

   396

        """

   397

   398

        checkbox_name = self.build_name_for_armed_input(name)

   399

   400

        if value is False :

   401

            checked = False

   402

            value = default

   403

   404

        else :

   405

            checked = True

   406

   407

        return (

   408

            self.render_checkbox_input(checkbox_name, checked),

   409

            self.render_text_input(name, value),

   410

   411

            tags.script("$(document).ready(function () { $('#" + name + "').formEnabledBy($('#" + checkbox_name + "')); });")

   412

        )

   413

   414

    def render_reset_button (self, value, return_url=None) :

   415

        """

   416

            Render HTML for a <input type="reset"> that abandons the form and returns the user to a page when pressed.

   417

   418

                value                   - button title

   419

                return_url              - (optional) URL to redirect user back to when button is pressed

   420

        """

   421

   422

        return tags.input(type='reset', value=value, 

   423

            onclick = (

   424

                "$.redirect('" + return_url + "')"

   425

            ) if return_url else None,

   426

        )

   427

   428

    def render_submit_button (self, value, name=None) :

   429

        """

   430

            Render HTML for a <input type="submit">.

   431

   432

                value                   - button title

   433

                name                    - optionally give the button a name for use with process_action_field

   434

        """

   435

   436

        return tags.input(type='submit', name=name, value=value)

   437

   438

    def render_form_field (self, name, title, description, inputs) :

   439

        """

   440

            Render the label, input control, error note and description for a single field, along with their containing <li>.

   441

        """

   442

   443

        # any errors for this field?

   444

        errors = self.errors[name]

   445

   446

        return tags.li(class_='field' + (' failed' if errors else ''))(

   447

            tags.label((

   448

                title,

   449

                tags.strong(u"(Virheellinen)") if errors else None,

   450

            ), for_=name),

   451

   452

            inputs,

   453

   454

            tags.p(description),

   455

   456

            # possible errors

   457

            tags.ul(class_='errors')(tags.li(error.message) for error in errors) if errors else None,

   458

        )

   459

   460

    def render (self, action, submit=u"Tallenna") :

   461

        """

   462

            Render the entire <form>, using any loaded/processed values.

   463

   464

                action          - the target URL for the form to POST to

   465

                submit          - label for the submit button

   466

        """

   467

   468

        raise NotImplementedError()

   469

   470

   471