also check the ancient BwToRox
The question was how we can migrate the code in htdocs/bw to build based on the rox framework.
Migration type I: Radical Rewrite
The safest way of "migration" is to take the bw markup from your web browser, paste that into a new template (which are usually stored in templates/apps/appname, but you can choose to store them in build/appname/templates instead). Then you can work on this code and replace the explicit things by dynamic things.
You'd have to create controller and page classes from scratch, after you decided which request should go where.
It is helpful to have a look how rox applications work in general, see
- RequestRouting is a good reference how applications work. (though it does not explain everything)
- InversionOfControl can also be a useful read.
- The Platform PT article used to be the reference of choice, but is not completely up to date.
Creating a Model
For MySQL things, I would do the following
- look at some of the queries in the old app
- look at the DB tables (test.bewelcome.org/debug/dbsummary might help)
- think of how you would pack that in model classes, and write them.
The typical thing will be that your controller or page wants to say "$model->findMemberWithId(..)" etc. Or, often the controller asks the model for something, which is then given to the $page object. The benefit of that is that the controller has the possibility to choose a different page object, if the model does not find an appropriate object.
For instance, the MembersController? could check if a member "brian" is found, and give the retrieved object to a fresh instance of ProfilePage. If no member "brian" is found, it can instead create a MemberNotFoundPage?.
Often the retrieved object will not be a dumb stdClass as returned by MySQL, but can have some interactivity itself. For such purposes I created the class RoxEntityBase? that you can derive from. For instance, the members app has a class Member extends RoxEntityBase? (or so I remember).
If you have a
- $member = $model->findMember($id),
then you can call
- echo $member->something;
and it will implicitly call
- $member->__call('something');
defined in RoxEntityBase
This method will first try to look into the private $member->_store['something'], and if nothing is found, call a method $member->get_something(), to fill the $member->_store['something']
well, sounds complicated..
The important thing is that the model is not one biig class, but nicely split up.
- Objects like $member or $group which represent a specific entity in our universe are a perfect example of "Communicational cohesion", which is good (http://en.wikipedia.org/wiki/Cohesion_(computer_science)). This means, it is ok to put a lot of data into this object.
- Objects like $model = new RoxModel? can have rather unrelated functions, and do usually not operate all on the same data (well, they operate on the DB). They are a typical example for "Logical cohesion", which is bad. To bring it back down to "Communicational cohesion", it is a good idea to NOT let this object know too much. Things like $member_id should therefore only appear in method arguments or return value, and not be stored as object attributes for $model. Instead, such things can be stored in an appropriate entity $member.
Problem with the radical approach
- It needs "thinking from scratch".
- There is no intermediate stable state. Instead, we have to cross the entire river at once.
Advantages with the radical approach
- A lot of the work is already done.
- We start with a quality code right away. (well, in an ideal world..).
Migration type II: Incremental modification
Guaka says:
Is there a way to simply copy code from /bw/ into /build/ and then gradually create the .page, .ctrl and .model? Working gradually is soo much easier and much less error prone.
Refactoring inside htdocs/bw
Yes, one thing we have not tried so far, but which can make a lot of sense, is refactoring things as long as they're still in bw folder. This can make it easier afterwards to copy pieces of this code.
BW Sandbox Application
This application allows to run bw files in a sandbox from rox front routing.
See
- #593
- build/bw/bw.ctrl.php
- http://test.bewelcome.org/bewelcome/mymessages.php
Advantages with this approach
It can be really confusing to have some things in htdocs/bw, and others in build/*. It's better if the request routing is the same for all. And it will be faster to get rid of the htdocs/bw folder if we do an incremental transition.
Problems with this approach
However, this will go with some problems:
- The BW sandbox will be tricky for forms with POST queries, mainly because of the nasty "Posthandler" in Platform PT. The Posthandler tends to steal away queries with POST, and redirect them somewhere else.
- relative vs absolute file inclusion paths. We have to take care that files are included from build/bw/templates, and not from htdocs/bw/*
- previously global scope statements suddenly become local method scope of BwPage::render(). This has some consequences for using variables (need 'global' keyword, if you really want to make them global).
- after doing a lot of copypaste from old bw, the Rox classes tend to become more complex, and it is not easy to factor that out later. I only think of login, which was really a pain.
I'm sure there are more problems waiting, but at the moment I don't know. We have to be especially careful with signup, as this is not tested that often. Again, in general I prefer clean rewrite. But, I only came to that conclusion after working a bit with the old bw code.
Existing new Apps
Most of the things already have a new rox implementation started on test.bewelcome.org.
These apps have been created with the "radical rewrite" approach, and so far it has worked quite well (says lemon-head).
build/members
should replace all the profile, comments, mypreferences etc
Anu is working on it.
See
- http://test.bewelcome.org/members/henri
- http://test.bewelcome.org/editmyprofile (if it works already)
build/groups
should replace bw/groups.php
See
build/messages
should replace bw/mymessages.php and the other pages related to it
See
build/admin
should replace bw/admin/*.php
build/about
does already replace bw/about.php, but should also replace the FAQ (in future)
See
- http://test.bewelcome.org/about
(the about/faq doesn't work at the moment, dunno why)
build/signup
should replace the old bw/signup.php
See
