Quick search:

4. User interface specifications in the domain model

This application is situated in the example4 folder. To run it on your own server you the same data as for example3. To try it out on the phpPeanuts website click here.

It extends a copy from example 3, which has no user interface customization, with specifications for the user interface. (Puzzle: Spot an example of each of the five types of differences between example3 and example 4, then check your answers against the explanation below)

In the first place we have added some property labels. The names of properties are limited by php's function name limitations. Sometimes users will find the property names that are logical for the programmers strange and unneccesarily complicated. Or the user may use a different language from the one used for building the software. Having separate 'labels' to present properties to the user solves this. They are set on the propertyDescriptor by its 'setLabel' method. Easiest place to do that is in the initPropertyDescriptors method where the property is created. Click here for an example. 

Second, we have selected some columns to show up in tables in the user interface. By default the user interface will show all properties except id's, because it has no way to know which ones are the most important to the user. By overriding the getUiColumnPaths method of a peanuts class one can inform the user interface which columns to show. The simplest way to do that is to let the getUiColumnPaths method return a string with the names of the properties to show, in the same order to show them (example). Another way is to let it return an array with the property names as values. This has the advantage that special column labels can be specified by using them as keys (example).

Third we solved a problem with the property 'id' overridden in Country. We used that property to hold the ISO code for the country. It would be nice if the user could see the ISO code, but the user interface hides id properties. By making an explicit specification of the properties to show this can be overridden. How this works is similar to the specification of columns, except that the method to override is getUiFieldPaths (example).

Forth, just as an example, we added a custom filter to the filters of Hours by overriding the static method getFilters (example). To see the filter click on the Hours option in the application submenu, then on the 'advanced' hyperlink at the right, and finally on the select list at the left. For more information see how to add a non-standard SQL filter.  

Finally we added a column to show up only in reports. By default tables in reports will show the same columns as tables in the rest of the user interface. This can be overridden by adding a method getReportColumnPaths to the class of the peanuts shown in the table. In our case we made the reports show one extra column by adding its property name to the result of getUiColumnPaths. This way, if we change the user interface columns, the report columns will change as well (example).

Of special interest is the implementation of Employee::getUiFieldPaths. It works the same way as how the default is uiFieldPaths are calculated by the classDescriptor, but removes the nHours property. This way the user interface will still adapt when the developer adds more properties to Employee or removes some.  (Mind the use of references: without references objects get copied all the time by php, giving poor performance and sometimes wrong results)