[development] Data API

[adrian rossouw]

On 01 Sep 2006, at 4:33 PM, Mark Fredrickson wrote:

> After the previous round of talks on the form api, I have a proposal
> for future Drupal development: let us rename the form API to the data
> API and start to look at it as the central method of implementing a
> full MVC in Drupal.

I am going to be discussing this in Brussels.

>
> First, some observations: HTML forms are simply a method of getting
> data from users, nodes are collections of defined data, nodes are
> increasingly represented as "forms" - however, coupling our data to an
> XHTML representation blurs the line between model and view.

I have always stated, the model and view are muddled, we need to  
separate the concerns.



>
> Let me map the model, view, and controller to current and future
> Drupal constructs:
>
> 1. Model: I think most people would say that the current model is just
> the db schema. I say that the model should be the schema AND the data
> definition (currently in the shape of a form definition). In fact, I
> might argue that schemas should be phased out for a database
> abstracted system. Imagine if you could just define a simple data
> structure in the form:
>
> $mydata = array(
> '#type' => number,
> '#name' => 'My Number',
> '#default_value' => 1234,
> );


Here's my current pseudocode for it.

function model_module_thing() {
    $model['myid' ] = drupal_field('id'); // returns an array, with  
defaults for that specific type
    $model['title'] = drupal_field('title'); // automatically  
includes check_plain filtering, and defaults to a textfield in forms
    $model['content'] = drupal_field('content'); // assumes html,  
does the filters , and can have a filter selecter
    // any property can be a 'callback' instead.
    $model['somenewfield'] = drupal_field('text', array('value' =>  
drupal_callback('somefunctionhere'));

    //relationship api stuff
    $model['uploads'] = drupal_has_many('file');

    return $model;
}

All models use a model_alter process. But , importantly ..
the use of callbacks instead of assignments, means that the entire  
data structure can be
cached, and only checked when necessary.

This ties into CRUD too :

function read_module_thing($nid) {
   // return an array of fields that can be validated against the model.
}

function update_module_thing($thing) {
   // save it to the database
  // keep in mind this does not mean we are moving it away from SQL.
   // certain models, like each of the individual admin screens,  
share the same update and read functions.
}

Just by definining these to functions for a model, it can have a  
basic form scaffolding created for it, with the constraint
/validation you specified (it's about validation at this point, not  
display). If you want fields that aren't in the forms you can just do
$model['name'] = drupal_field('value');

If you then wanted to make a more fancy form , instead of the default  
scaffolding , you just define :

// calling it structure instead of view because of the views module,  
and also
// the difference between theme and the forms array.
function structure_module_thing_update($model) {
   $structure['fieldset'] = drupal_widget('fieldset', array 
('collapsed' => TRUE));
   $structure['fieldset']['title'] = drupal_widget($model['title']);
   $structure['content] = drupal_widget($model['content'], array 
('widget' => 'otherthemefunc'));

   $structure['submit'] = drupal_submit('title', 'path or callback');
   return $structure;
}

This is the same mechanism used to build node / user / blah views, as  
every field type
has a default widget it uses for both views and forms. Similarly, the  
node summary
for instance, is just a different view of the node model.

> While I agree that we having a drupal specific DDL is bad, the reality
> is that we already do have one: the current formAPI. Accepting that
> fact and writing tools to turn $mydata into a db schema will only help
> development, not raise the barrier.
Yup, CCK already does a lot of that.


>
> 2. Controller: These are the _submit and _validate functions right
> now. I know there is work going on to more flexibly work with these
> items (eg. I owe a patch to allow binding of buttons to functions). I
> think the controller layer probably needs the most work. The recent
> nodeapi vs. formAPI (call it Data API now!) illustrates this fact.

Yup, more comes of this though, including extending other models with
new controllers.  An obvious one would be adding an action to nodes
which just promotes that node.

>
> 3. Views: Arguably, these are the theme_* functions; however, this is
> where the coupling of data to XHMTL forms I mentioned earlier comes
> in. Take for example '#type' => 'checkbox'. This definition makes me
> cry every time. Multiselects and checkboxes should be collapsed into
> one type: multi. Radios and drop downs should be collapsed into one
> type: single. Text boxes and text fields should just be one type,
> varied on size (and perhaps something else to allow filtering). If we
> move these functions into the theme layer, forms API will stop being
> just about forms and wills start being about data. Good.

Yup. hence why we need the model_. These are different widgets used
to represent the same field. with different validation.

> So, what are the benefits of this system? First, I think changing the
> semantics of the name will allieviate some confusion regarding the
> role of the Data API. The recent nodeapi discussions have shown that
> there is confusion over where and when data should be manipulated.
Forms has had very little to do with forms the whole time. I was  
going to
call it the action api, as each form is an action you can take. it  
has parameters,
it has an identifier  , but as of yet it has no identifiable output.

Anyone who's ever seen apple's automator will understand how I view  
forms api.

> I think it gives us CCK like features right out of the box. Since most
> of the data api will be used for defining nodes, it seems natural to
> me that users could define forms online and Drupal would turn them
> into types on the fly.
That's why I am basing as much of the code on cck's field types as  
possible,
since it already gets us a chunk of the way there.

It also centralises all cck like things, and makes it easier to build  
forms of all kinds,
not just node forms. (also , the separation of concerns makes the  
data model far cleaner
and much much less magic (like form_builder) needed to get them to work.

> This email is getting long as it is, so I'll end it here. Of course,
> discussion is welcome.
I would love to chat to you on skype or similar about your ideas.  
I've been
spending some time these last few weeks reading documentation on cakephp
and other php MVC frameworks, to try and consolidate it all, but I  
would love some extra
input.