Learning XPages Part 4 : Breaking Up Is Easy To Do
Tags : lotus domino XPages OneUI Custom Controls
Bookmark :
When developing an XPages application you can, if you want, put everything into a single XPage but this can lead to inconsistencies in the look and feel of your application if it contains multiple XPages, for example in our Phonebook application we will have an XPage for the homepage, an XPage for the list of people at a single location and an XPage for the persons details. All of these XPages will have the same basic layout but if I put that layout directly in each XPage it means you have to change three different XPages if you want to change part of the layout that is common for each page.
So lets break up our XPage into Custom Controls that we can then include them in future XPages in the application. We'll use the oneUI structure as the basis for the custom controls that we need. Let's look at that original simple HTML again to see the DIV names :
Each of the DIVs that contain content make a logical breakup of the html into Custom Controls. You may be tempted to also create custom controls for lotusFrame and lotusMain but there really is no need, they are just containers and will probably never change.
To get started open up the Custom Controls view in Domino designer and click the 'New Custom Control' button. You will be prompted for a name for the custom control. You can give it whatever name you like but I have found that I am leaning towards a standard naming convention for the different types of custom controls that I create so I'm going to call mine layout_Banner. You can name your custom control however you like but you should also try stick to a standard naming convention so if you come back to the application after a while you can easily work out how everything fits together.
Once you have you blank custom control open, switch to the source view and put in the single div for lotusBanner and then save and close it. Here is how it's going to look in the source view once your done :
UPDATE : The above screenshot should say class='lotusBanner' and not id='lotusBanner' the OneUI css does not have a DIV style for lotusBanner, just a class style. the reast of the div's are fine and should read id= for their names.
Do the same for the other parts of the oneUI structure with one exception, for the lotusContent DIV give it's custom control a slightly different name, I'll be calling mine content_HomePage. The reason for this is that I'll eventually have different custom controls to include in this spot for the other XPages I'll be making in my application. Here are the Custom Controls I currently have in my demo database :
If we open up the original XPage we can now replace the DIVs in there with links to the Custom Controls. Just drag the custom controls in from the controls pane on the right hand side and then switch to the source view and move them to the correct places in the source for the XPage, remembering to delete the unneeded DIVs. Here is the new source for my XPage
If we preview this in our web browser we end up with the exact same result as before but now it has been broken down into little chunks that will be easier to work with. In the next few parts of the series we will be looking at each of the custom controls and adding some real content to them.
Bookmark :
When developing an XPages application you can, if you want, put everything into a single XPage but this can lead to inconsistencies in the look and feel of your application if it contains multiple XPages, for example in our Phonebook application we will have an XPage for the homepage, an XPage for the list of people at a single location and an XPage for the persons details. All of these XPages will have the same basic layout but if I put that layout directly in each XPage it means you have to change three different XPages if you want to change part of the layout that is common for each page.
So lets break up our XPage into Custom Controls that we can then include them in future XPages in the application. We'll use the oneUI structure as the basis for the custom controls that we need. Let's look at that original simple HTML again to see the DIV names :
<div id="lotusFrame">
<div class="lotusBanner">Banner Contents Here</div>
<div id="lotusTitleBar">Titlebar Here</div>
<div id="lotusPlaceBar">PlaceBar Here</div>
<div id="lotusMain">
<div id="lotusColLeft">Left Sidebar Here</div>
<div id="lotusContent">Main Content Here</div>
</div>
<div id="lotusfooter">Footer Contents Here</div>
</div>
Each of the DIVs that contain content make a logical breakup of the html into Custom Controls. You may be tempted to also create custom controls for lotusFrame and lotusMain but there really is no need, they are just containers and will probably never change.
To get started open up the Custom Controls view in Domino designer and click the 'New Custom Control' button. You will be prompted for a name for the custom control. You can give it whatever name you like but I have found that I am leaning towards a standard naming convention for the different types of custom controls that I create so I'm going to call mine layout_Banner. You can name your custom control however you like but you should also try stick to a standard naming convention so if you come back to the application after a while you can easily work out how everything fits together.
Once you have you blank custom control open, switch to the source view and put in the single div for lotusBanner and then save and close it. Here is how it's going to look in the source view once your done :
UPDATE : The above screenshot should say class='lotusBanner' and not id='lotusBanner' the OneUI css does not have a DIV style for lotusBanner, just a class style. the reast of the div's are fine and should read id= for their names.
Do the same for the other parts of the oneUI structure with one exception, for the lotusContent DIV give it's custom control a slightly different name, I'll be calling mine content_HomePage. The reason for this is that I'll eventually have different custom controls to include in this spot for the other XPages I'll be making in my application. Here are the Custom Controls I currently have in my demo database :
If we open up the original XPage we can now replace the DIVs in there with links to the Custom Controls. Just drag the custom controls in from the controls pane on the right hand side and then switch to the source view and move them to the correct places in the source for the XPage, remembering to delete the unneeded DIVs. Here is the new source for my XPage
If we preview this in our web browser we end up with the exact same result as before but now it has been broken down into little chunks that will be easier to work with. In the next few parts of the series we will be looking at each of the custom controls and adding some real content to them.
Comments
You can take that a step further. Add a content place holder control inside your new custom control and your can customize as needed.
Posted by Stephan H. Wissel At 12:20:36 PM On 02/24/2009 | - Website - |
Now, however, you have us building "custom controls", a new concept to me and then we replace our original HTML with "links" that don't look like any links I've seen before.
I guess I'd need a few more definitions before I could fully understand this lesson fully.
BACKGROUND
I've been using Notes/Domino to build web sites for about 12 years, but I'm only up to version 7. I'm studying this to see if I want to upgrade now or later. Your series is giving me the details to help me decide ... so, thanks again.
Peace,
Rob:-]
Posted by Rob At 11:27:29 PM On 03/11/2009 | - Website - |
Do you think Porlet Factory of IBM, will be remplaced by Notes 8.5 , so xpages ?
main idea : an existing Notes Application up to web using Porlet Factory ( without Domino )
Nico
Posted by NICOLAS At 10:44:05 AM On 04/11/2009 | - Website - |
<xc:layout_Banner></xc:layout_Banner>
the closing element is underscored as an error, and the explanation is given as:
The prefix "xc" for element "xc:layout_Banner" is not bound.
If I delete that line, the error transfers to the next line; i.e., the TitleBar element).
Got any idea what this might mean?
Let me know.
Steve Kobb
Posted by Steve Kobb At 05:08:29 PM On 04/20/2009 | - Website - |
Advice to those who are following along:
Don't create one Custom Control and then make copies. The reference names will be wrong and unfixable.
Instead, click on the New Custom Control button for each control that you need.
Posted by Steve Kobb At 12:24:27 PM On 04/21/2009 | - Website - |