embel -- rationale and limitations

embel.py has two major advantages when compared to merging with SVN branches:

• no manual setup required (i.e. you don't need to recreate source- and target-projects as branches)
• "idempotence", i.e. you can re-run embel.py for a given source- and target-project as often as you like, the result is always the same (http://wikipedia.org/wiki/Idempotence). In other words: if the target file (or project) is embellished already, another run won't mess it up.

As explained in the embel overview, doing the work of retrofitting PhoneBook tutorial features to a uigen.exe-generated new and improved PhoneBook is BORING, but that is an oversimplification. Truth is, this task is BORING, TEDIOUS AND ERROR-PRONE. Keep in mind that with all those
SearchResultXForms, SearchResultXControls, EditXForms, EditXControls, ascx.cs, aspx.cs, ascx, aspx, the retrofitting embellisher soon feels like the lost protagonist in the Colossal Cave text adventure (http://en.wikipedia.org/wiki/Colossal_Cave#Maze_of_twisty_little_passages). Even with practice, mistakes, errors, bugs and head-scratching are the human condition after modifying templates (and this includes theming).

Limitations

API upgrades not covered (of course)

embel.py shines if you modify uigen.exe templates and want to re-embellish your PhoneBook web application. This presumes that nothing changes in the API calls you need for your embellishments. As soon as this presumption is violated, your embellishments will clearly fail. A contrived example for this: Let's say the name of Call methods changes to CallWxeFunction. In our old embellishment event handler for the BOC list in {{}}, the line with the call becomes incompatible with the new API:

    protected void PersonList_ListItemCommandClick (object sender, BocListItemCommandClickEventArgs e)
    {
      if (e.Column.ItemID == "Edit")
      {
        try
        {
          // *** WRONG! It's not "Call" anymore, it is "CallWxeFunction"
          EditPersonForm.Call (WxePage, (Person) e.BusinessObject);
          ClientTransaction.Current.Commit ();
        }
        catch (WxeUserCancelException)
        {
        }
      }
    }

Automatically adapting to API-modifications probably is feasible for SOME cases, but most certainly not for all.