This week it's another request for a lesson about Custom Properties on Custom Controls.

The aim of a custom property is to make a custom control even more re-usable, so you can pass in settings to it from the xpage or custom control on which it is embedded. At the simplest level you can pass in boolean or string settings to configure elements on the custom control, but you can also pass in complex objects such as a document data binding.

1. Create a new database (or download the sample database)
2. Create a new custom control called layout_title
3. In the custom control properties pane, go to the Property Definition tab and click the "New Property" button
4. Set the name to "showtitle"
5. Set the type to boolean and set the default value to "true"
6. Now add another new property
7. Set its name to title
8. Set its default value to "Test Title"
9. Now drag a computed field onto the custom control
10. Set the Visible property to be computed, in the script editor type the following...

compositeData.showtitle

11. Now set the value to use Javascript and set it to...

    compositeData.title

12. Save the custom control and then create a new XPage called test
13. Drag the layout_title custom control onto the xpage, save and preview
14. The title is displayed and says "Test Title"
15. Now if we go back and look at the all properties for the custom control on the XPage we can see that we can override the default settings.
16. First change the title property to something different, save and preview
17. Now set the displaytitle property to false (note the selector based upon the data type) and the title disappears when it's previewed.
18. Which is all well and good but what if we want to pass more complex data such as a Document data binding?
19. First we'll need to create a form and just put a few dummy fields on it
20. Now, back in the test XPage, add a document binding to the new form
21. Create a new custom control called form_dummy
22. Add a new property called thedoc
23. From the type dialog select Data Sources --> ModelDataSource
24. Now we need to change the editor to String and we'll leave the default value as blank
25. Finally we want to add some fields and a save button
26. Drag an Edit Box onto the custom control and in the data tab set the binding to use Advanced
27. The type of binding will be Expression Language and then in the code window we're going to type:

    compositeData.thedoc.Untitled

28. Finally we'll add a Submit type button so that we can save the data
29. Back on our test XPage, drag the new custom control onto the design view
30. In the custom properties, set the "thedoc" variable to be computed and set it's value to "document1"
31. Finally save and preview the XPage