============
 Data Model
============

In the typical scenario, the master view's
:attr:`~wuttaweb.views.master.MasterView.model_class` is set to a
:term:`data model` which maps to a table in the :term:`app database`.
For instance::

   from wuttjamaican.db.model import Person
   from wuttaweb.views import MasterView

   class MyPersonView(MasterView):
       model_class = Person

With a mapped model class, the view can inspect the class to derive
the model name, title, etc.  In particular it can determine the model
"key" automatically, which is used in the URL to identify a given
record.  This is just ``uuid`` for normal mapped models.

But the "model" can really be any tabular data set; for instance you
could have a master view which showed the file contents of a folder on
disk.  In such "ad-hoc" scenarios the model data can just be a list of
dicts.  In that case instead of setting ``model_class`` you would just
set :attr:`~wuttaweb.views.master.MasterView.model_name`, but you also
must set the :attr:`~wuttaweb.views.master.MasterView.model_key` since
that cannot be determined from introspection::

   from wuttaweb.views import MasterView

   class SpecialFileView(MasterView):
       model_name = "special_file"
       model_key = "filename"

In any case you may also want to set/override the
:attr:`~wuttaweb.views.master.MasterView.model_title` and
:attr:`~wuttaweb.views.master.MasterView.model_title_plural`::

   from wuttaweb.views import MasterView

   class SpecialFileView(MasterView):
       model_name = "special_file"
       model_key = "filename"
       model_title = "Special File"
       model_title_plural = "Special Files"

If the view has a mapped ``model_class`` then it should already have
logic needed to fetch data for the grid and CRUD interfaces.  But in
the ad-hoc scenario you must define methods to handle that::

   import os
   from wuttaweb.views import MasterView

   class SpecialFileView(MasterView):
       model_name = "special_file"
       model_key = "filename"

       SPECIAL_DIR = "/tmp"

       def get_grid_data(self, **kwargs):
           """
           Override parent method to define how the full data set can
           be fetched.
           """
           data = []
           for fname in os.listdir(self.SPECIAL_DIR):
               fpath = os.path.join(self.SPECIAL_DIR, fname)
               if os.path.isfile(fpath):
                   data.append(self.normalize_file(fname))
           return data

       def get_instance(self, **kwargs):
           """
           Override parent method to define how a single "instance"
           (record) can be fetched.
           """
           # nb. the 'filename' (key) is embedded in current page URL
           fname = self.request.matchdict["filename"]
           fpath = os.path.join(self.SPECIAL_DIR, fname)
           if not os.path.isfile(fpath):
               raise self.notfound()
           return self.normalize_file(fname)

       def normalize_file(self, fname):
           """
           Helper method to ensure grid/instance use the same logic to
           construct data records.
           """
           fpath = os.path.join(self.SPECIAL_DIR, fname)
           return {
               "filename": fname,
               "filepath": fpath,
               "filesize": os.path.getsize(fpath),
           }

A master view can also define a *row model* which would represent a
"secondary" data set associated with a single primary instance/record.
But we'll get into more detail on that later.

Here are most of the relevant docs for customizing the primary data
model:

**Model Proper**

* :attr:`~wuttaweb.views.master.MasterView.model_class`
* :attr:`~wuttaweb.views.master.MasterView.model_name`
* :attr:`~wuttaweb.views.master.MasterView.model_key`
* :attr:`~wuttaweb.views.master.MasterView.model_title`
* :attr:`~wuttaweb.views.master.MasterView.model_title_plural`

**Fetching Data**

* :meth:`~wuttaweb.views.master.MasterView.get_grid_data()`
* :meth:`~wuttaweb.views.master.MasterView.get_instance()`