Document-Driven Development in Practice: Rethinking sfForms
If you’ve watched or read my presentation on Documentation-Driven Development, you may wonder how to put that new methodology into action. A practical example is often better than a long explanation, so let’s see ho to apply it to the new Forms sub-framework introduced by symfony 1.1.
Not DDD
In order to use the new sfForm library, you must either read a book (not yet completely written) or dive into the source code and guess how to use it. To my mind, this is pretty much the contrary of what leads to a large adoption.
The Form framework was designed with power in mind, and reaches this goal very well: you can use it to create forms of any level of complexity, including forms embedding other forms, forms with a variable number of fields, forms split into several steps (”wizards”), etc. It is very much object oriented, so everything can be reused or overridden.
But unfortunately, in order to create a simple form, you need to learn a lot more and write a lot more code than what you used to do in symfony 1.1. The current Forms documentation describes the API and justifies its implementation. It goes very much into the details of each part of the sub-framework, and quite early in the learning process. The result - for me, at least - is that the reader feels overwhelmed by the huge amount of classes, features and options, and dismisses the whole sub-framework for being too complex.
“Let’s use that new Form stuff for complex forms and keep the current form helpers and YAML validation for everyday forms”, I hear. That’s a pity, because once you understand how the new Forms sub-framework works and accept its verbosity, there is no good reason to stick with the old system.
An Ideal sfForm Documentation
I think that a piece of documentation is missing. This piece is probably an introduction to the Form sub-framework.
In symfony 1.0, a single chapter of the book was enough to master forms for most use cases. Even if the new form sub-framework is more powerful than the 1.0 one, it should not be more complicated to learn and use in similar cases. So the sfForms introduction should be short, requiring at most one hour to read it.
After reading this documentation, an average developer should be able to use sfForms in 80% of the cases. That includes at least all the features described in the original Forms chapter of the symfony book:
- Displaying a form
- Available form helpers
- Displaying a model-based form
- Dealing with Foreign keys
- Handling a form submission
- Validating a form
- Available validators
- Repopulating a form
- Complex use cases
The target audience would be people knowing some concepts about symfony, but not yet everything. In fact, they should know what the Chapters 1 to 9 of the symfony guide cover, not more. So some advanced concepts should probably be skipped, or explained only after the fundamental usage is clear.
This introduction should not require additional lookup in the Forms book. That means that it should be self-sufficient. It probably also means not including the justifications of the Forms implementation that you can find in the current Forms book. The reasons why the API was designed the way it is should become obvious at the end of the introduction. Expert customization and rare use cases should probably also be left aside.
The symfony 1.0 documentation introduces concepts and features in a certain order, with a precise purpose: not loading too much information into the reader’s mind at a time. In a similar fashion, the forms introduction should be a linear piece of documentation, not a set of articles that you can read in any order with hyperlinks everywhere to break the reading flow.
The forms framework is powerful, but the current form book somehow translates that into length, and verbosity. On the contrary, I think the reader should feel exalted: the documentation should put him in a rush to start using the new forms. So the forms introduction should “tell a story”, and gently lead the reader to a point where he feels he can grab the steering wheel and drive the car by himself.
API enhancements
The problem is that explaining the current API takes much longer than a single piece of documentation. That’s because of the many options available, because of the many objects to learn, and because even the simplest things (like a list of form controls) look complicated (sfWidgetFormSchema).
There is not much choice to overcome this problem. In order to write a short and readable guide to the forms sub-framework, its API must be adapted. That’s right, the API must be changed so that the documentation can be made shorter, and more usable. This is one of the principles of the Documentation-Driven Development methodology.
These API enhancements should be completely backward compatible, so that any existing application using the current sfForms implementation can continue to work seamlessly with the modified implementation. In a way, that qualifies the API enhancements as a simplicity layer on top if the existing code. As a side note, the current Forms book still remains indispensable for advanced usage.
Note that the API enhancements don’t need to be implemented before the new documentation is published. The implementation comes second, after the documentation. That’s another of the DDD principles: explain first, make it work afterwards. After all, project managers write requirements for web applications before they exist, all the time.
Do As I Do, Not As I Say
Some people are getting sick of reading me criticizing parts of the symfony framework. Well, I’m not criticizing: I’m actively improving.
Rethinking sfForms is a good example for a Documentation-Driven Development. To illustrate this methodology, I’m going to rewrite the Chapter 10 of the symfony book for symfony 1.1. That’s right, the current Chapter 10, which describes the “old way” of doing forms, can be rewritten in a similar fashion and serve for symfony 1.1.
But since the current API requires too much explanation to be used, I’m going to introduce the necessary API changes to the sfForms library. I’ll create and manage forms in a way slightly different from what the current API allows, to make it simpler to use - and to explain.
When the new Chapter 10 is published here in this very blog, this piece of documentation will be of no use since the features it describes won’t be implemented yet. But I know that writing documentation is not enough to convince people (yet), so I will Implement the API changes as a second step to the exercise. As I’m not a very good developer, any help will be welcome during that phase (contact me If you want to give me a hand after the documentation is published).
If everything goes well, the implementation of the API changes will be be released as a symfony plugin - maybe called sfSimpleForms. I hope it can lead more developers to adopt the greatest open-source Forms framework around.
Possibly related posts (automatically generated):
Thanks for the effort you’re putting into Symfony. Even though your opinions are not always well received, I’m glad you’re continuing to stay involved with the community. I am looking forward to seeing the new documentation, as well as the code that will follow.
Hi françois,
sfForm is a real improvement for symfony (I remember creating my own ugly sfForm for a project). I hope you will manage to make it as easy as DbFinder is,..
And for this, I have a small idea I’d like to share here : using template for forms / row / widgets / errors, instead of “decorators”.
This would allow us to reuse template code, instead of calling $form['my_input'])) ?> in each editSuccess templates…
Just I Idea… A
and is there a chance the sfSimpleForm plugin could be integrated into core?
If it really shines and makes developers life easier, plus is well documented…
Really impressed and happy when readind this post!!!. You are great!!!I came thinking about what you wrote in this article since the new form framework was released. It’s a bit frustrting to read the documentation and see that you have to “Call an Expert” to do a simple login form with all its validation….
I know the sfForm framework is very powerful and really appreciate the work of all developers working on the symfony project, but i don’t understand very well why such a really powerful php framework like symfony can not be easy to develop and has to be too ‘verbositive’.
I hope Fabien take care about what the community think of this kind of things…maybe just a poll to know what developers think could be enought to learn about the community…to learn that we want new functionality(of course i love that from sf) but not to make things more complicated. Take too much time to read all the sfForm book(API) and this goes against RAD.
It ‘d be really great if you can join the symfony team to help them to think about the best way to do changes in the way a common developer can understand…but i know….is not your decision i suppose…
Great news!!!
I’m looking forward to reading it! I guess that I’ll leave symfony 1.0 after all…
Please continue to make remarks about the new symfony forms framework and keep up giving good ideas about how to use it. I am sure lot of people read your blog.
But, recently you wrote an article about sf 1.1 (a smart move or somehting like that). I read it and I found out that I should wait for sf 1.2. I was expecting a new administrator stuff and it’s coming. You should probably wait for it before coding sfsimpleform. It is supposed to be released in a month. Will come very fast.
Francois, one of the main reasons I am still using 1.0 forms in my 1.1.2 project is for all the helpers in creating ajax driven forms, and the quick configuration of validators. It seems this funcionality has been lost.
I also wholeheartedly agree that going from one chapter to an entire book on the topic is definately offputting to users who just want to dive into the framework.
Oh I see, this would be the “tease” phase I just read about in your DDD presentation
Fracois, I agree with you on your point of view about documentation, but at the same time I see lack of documentation on symfony. For example, recently I was searching for a complete set of options available for the admin generator (generator.yml). I haven’t found it anywhere. At last I went to forums to search something. I agree, the learning must be easy, but maybe should be an extensive documentation somewhere. Anyway thank you very much for your work, I appreciate it very much, and follow your blog with high interest.
@Enrique: Perhaps you don’t know the admin generator cheat sheet?
http://www.symfony-project.org/blog//2006/04/25/admin-generator-cheat-sheet
This is quite great, and so is your presentation sheet.
Are you about to write a book about this subject ? I think you really should, I’d buy it for sure.
@François: yes I know the cheat sheet, but I didn’t find the ‘filename’ parameter used for admin_input_upload_tag, the ‘upload_dir’, ‘include_remove’, etc.
@Enrique: Then the cheat sheet needs to be updated… Would you like to start working on it?
@François: ok, I’ll be pleased to do it. Do you know who has the original file, and where can I find all available options?
[...] This document is the first draft of a methodology experiment explained earlier in this blog. It documents the sfForm framework found in symfony 1.1, but with some changes in the API and [...]
Hi Francois,
I think you’re onto something with this DDD methodology. I look forward to seeing your experiment unfold.
Kris
[...] but almost never when someone works on his own framework. So his recent reaction about my DDD experiment is rare enough to be thoroughly analyzed, and distilled. Let’s look for the very substance of his [...]
[...] proprio sul suo blog che ha dato il via ad una discussione su come secondo lui dovrebbe essere affrontato al meglio lo sviluppo del nuovo form framewor. Un [...]
Francois,
Thanks for the insightful remarks on Symfony and its new Forms framework.
I have used Symfony (see also my post on how to set it up on OS X: http://www.burobjorn.nl/blog/?p=159), but I have left Symfony for now.
My feeling is that Symfony has become too ‘heavy’.
This new Forms framework (a framework in a framework..makes me wonder) - how powerful it may be - is a symptom of the movement behind Symfony which in my humble (no sarcasm!) opinion is leading to a bloated over-engineered framework trying to solve ‘everything’ and thus in the process becomes ‘nothing’. It might be just my taste, inexperience or lack in striving towards pure OOP, but Symfony is not my framework of choice anymore due to these developments such as the Forms framework.
However I’m very happy with your critical, yet positive constructive insights and I do hope that your DDD methodology becomes more used by the Symfony team. It might make Symfony useable and perhaps even more important ‘fun/nice’ to work with.
[...] a forms fejezetet a symfony könyvhöz sfForm alapokon, ahogy ő gondolja / szeretné látni. Korábban már többször szapulta a jelenlegi sfForm dokumentációt, meg még sok minden mást is, ami nem symfony 1.0 (nyilván fáj neki, hogy az 1.1 már nem [...]