Model hooks documentation and examples

Gumster

Back in the v0.93 docs,the Model tutorial showed (I think) examples of model hooks being used. I can't seem to find a similar example in the new documentation, although the general information about them has increased. The relationships section warns that the on_after_save model will need to have a parent call if it's ever used with an existing relationship, but there's no actual example. Do you think the tutorial should include a hooks example, just to be complete?

I've just been wrestling with the on_after_post() method, trying to change a value and - after scouring this forum - found that method doesn't return the altered $values array, but switching to on_before_clean() does. So the functionality is as I wanted it now, but I think the documentation might explain which hooks can operate on $values for saving, and which don't?

admin

That's a good point. The new 1.0 features allowed us to remove a lot of the hooks that use to need to be manually created and so the tutorial was altered to reflect that. I think the addition of using hooks (and maybe altering the _common_query()) may be good additions. I'll have to think about where to add that.

Gumster

Although tagging, categorisation, and relationship properties have lessened the need for model hooks, they still have a place, and it would be a shame for them to be forgotten.

Gumster

Just a thought - the documentation should specify the order in which hooks are called.

Gumster

Also, fields POSTED that are not present in the model table are present in some hooks, but not in others. Could this be clarified too?

admin

Thanks for the documentation report. That fix has been posted in our develop branch for the next release and is updated on the live site. We'll work on that documentation a little bit as well to add some clarity.