Using Control Templates
According to the online help “A control template is a set of controls that can be re-used in several windows or pages.” It a very handy way to create a “mini” feature and then incorporate it into several pages. This included local variables and procedures, etc. Another benefit to doing the CURE as a control template was the ability to test it as a self contained unit without having the rest of the “page” possibly interfere. By using the Run Page Test (F9) button you can test and display just the control template.
The Control template can be seen (and added) from the Project Explorer , the File->New->Page Interface.
But the “Coolest” method is by selecting several controls and using the right click Refactoring menu option, which will not only create a control template with those controls, but remove the controls and add them back into the page as a control template.
Adding an existing control template to a page is also very simple. You can drag the control template from the project explorer on to a page, or you can use the Insert->Special->Template Control menu option.
You can tell that a control is part of a control template because it will be have little Yellow boxes in the top left corner of the control
Another very cool feature of control templates is that you are not locked into the “original” template. You can overload the template. Meaning you can override some properties of the template for a specific page. While still staying linked to the control template so that any other changes to the control template will still be reflected. In the image above notice the Blue Box about the “E” that means that the control has some overloaded properties. You can even overload the code behind a control, either in it’s entirety or you can add additional code to run before or after the code of the template by the placement of the “ExecuteAncestor” statement.
That’s a brief overview of control template, if you are not using them currently I strongly encourage you to experiment with them they can come in handy for alot of different things, and its yet one more way to refactor portions of your application, site, code, etc. and we all know that refactoring is the key to productivity and maintainability!
Timers all you to setup a procedure that is ran on a timed interval. When you go to theTaxCure.com the “Big Letters” and the alternate text rotate automatically from “C” to “U” to “R” to “E” and then back to “C” continuously. This is accomplished with this statement in the browser “onload” process.
Timers run in browser code, meaning the browser is actually performing the operation and there is no communication with the server. The above line calls the LetterTime browser procedure ever 1.5 seconds. TimerNumber will contain the unique identifier assigned to the Timer, which will come in handy in a second.
A word about our design choice of 1.5 seconds. You will notice that it is a slightly shorter amount of time than the average person can actually read the alternate text. This is one of those “marketing” tricks, the copy is not as important as the copy of the rest of the page, and the feature is mainly “eye candy”, but those that notice the alternate text are more interested because they can’t easily read it so they investigate further. And just like that we have “tricked” you into noticing and reading text that if it was just static text you likely never would have read in the first place.
When a visitor does investigate further they likely do so by moving their mouse over the area, we have all learned that behavior from things like the “Google Doodle”. And as soon as the mouse enter the area a couple of new features are exposed.
The “Big Letter” and alternate text for the section the mouse is in, lights up and the mouse cursor turns into a hand indicate to those web conditioned visitors that they are now in a clickable area. We will cover those features in more detail later in the article, but the other thing that happens when the mouse enters the area is the timer stops. You don’t want the text alternating automatically if the visitor is manually investigating the area; that would likely frustrate them. To stop the timer you issue the following command when the mouse enters one of the regions.
Remember getting TimerNumber when the Timer was started. Now you know how that comes in handy. Which hints at another feature of timers, that I am not using here, but do use to accomplish other effects; you can have multiple timers that each run on their own.
The last feature of the CURE to cover in relation to timers is when the visitor moves the mouse out of the CURE region, the automatic rotations picks back up where it left off. This is accomplished using the exact same command as the one used in “onload” to start the timer.
With WB you code and procedures are designated as either Server code or Browser code. As discussed the Timer runs on the browser so the procedures etc. called by the browser also need to run in browser code. Generally speaking there isn’t any difference in the language between the two, except certain functions are only allowed on one or the other. And there are certain things you can’t do in the browser code. For me the easiest way to “get my head around it” is to think of it as the browser code runs completely inside the browser of the visitors computer. At that point it has no connection or communication with the server at all (with the exception of AJAX calls which I will cover in a future article). Once you think about it like that it become obvious why the browser code can not create or access global variables, perform file functions, etc.
The CURE uses three Browser Procedures, actually four but we will discuss the forth when we discuss popups.
- You have already seen the call to this procedure. This is the procedure that runs every time a the Timer fires. It keeps track of which letter is currently lit up and moves to the next letter every time it is called. It makes a call to LetterOut for the old letter and a call to LetterOver for the new letter.
- This is the function that lights up a letter and also changes the alternate text. It is called by the LetterTimer procedure and also when the mouse moves into a specific region.
- This is the function that turns off a letter and changes the text back to its original text. It is called by the LetterTimer procedure and also when the mouse moves out of a specific region.
Most of the code of these procedures will be discussed in the later sections of this article and the complete code of each will be included at the end of the article.
Altering Text and Color Programmatically
And now the “real” magic begins! In each region there are three static controls: the big letter, the bold heading and the short paragraph of text. When each section lights up, the big letter changes color and the text of the paragraph changes to alternate text. This code is in the LetterOut and LetterOver functions.
The LetterOver function contains this code
SWITCH WhichLetter CASE 1: STC_C = [ theTaxCure can create a plan for you to become compliant and stay compliant once your problem has been cured. ] STC_BigC..Color = ColorPalette(colorBorderNoteWarning,2) CASE 2: .... CASE 3 .... CASE 4 .... END
The …. represent code very similar to the code of Case 1:
Which letter is a numeric value that is incremented by the LetterTime function, which it goes over 4 it restarts at 1. The value is also set when the visitor moves the mouse into one of the four regions.
The SWITCH statement allows you to write a complex conditional test without several nested IF or ELSE IF statements. On of the CASE statements sections will run depending on a match. Not shown here but there is also an OTHER CASE: statement that can be used as a “catch all”
STC_C is the name of the static control that contains the paragraph of text. So the first statement of the CASE 1: condition is changing the text of the paragraph to the alternate text. The [ ] are very handy for formatting and assigning complex strings in WX. Without the use of the [ ] the statement would look something like this.
STC_C = "theTaxCure can create a plan " + CR + "for you to become compliant " + CR + "and stay compliant once" + CR + "your problem has been cured."
Not the end of the world but definitely not as easy to read. Combine the [ ] with the StringBuild function and you have a very powerful feature that makes you code easier to read and easier to create and maintain and there for less error prone.
The next statement changes the Color of the Big Letter. You may not have seen the ColorPalette statement before. This is a function that works in connection with the Skins, Palette and Styles of the project.
On the Skin/Styles tab of the Project description, you specify both a Skin and a Palette. theTaxCure.com is using the Neo_Light Skin with the AzurEdge & Light Palette.
The Skin sets the general look and feel of the site, such as the background images for buttons, etc. And the Palette sets the color scheme of the site. For instance if you were to change the Palette to Cherry and Light the site would look entirely different. Had I hard coded the colors for the normal and lit up big letter, changing the Palette would also require me to change the hard coded values as well, or the colors would likely clash with the new color scheme.
So where did the values for the ColorPalette function come from? If you edit the style of a control and drop down the color combo you will see three tabs at the top with all of the different colors of the Palette.
There are equates for all of the categories (although you will have to do some deciphering to match them up). For instances the statement to light up the letter is ColorPalette(colorBorderNoteWarning,2), which translates to the Border tab, the Note category, and the second column.
The letter out function performs nearly the identical same code, except it changes the paragraph back to the original text and sets the Big letter back to its normal unlit state using the function ColorPalette(colorTextLink1,3) which translates to the Text tab, Link (1) category, and the third column.
Creating a Hover and Click Region over several controls
Over the last few weeks there have been a number of versions of the CURE as I refined the feature. One of the challenges was to get the hover over action to behave the way we desired. Not all controls have the “onmouseover”, “onmouseout”, and “onclick” processes which is where you need to place code to be executed whenever the mouse hovers over, leaves, or clicks on a control.
Static controls do not have that ability, so in the first version of the CURE, the short paragraph was actually a Link control. I set the style of the control so that it didn’t have the “normal” link underline and hover styles, because I wanted it to look like normal copy on the page. This worked well and I was able to achieve the desired hover and click effects, but only when the visitor had their mouse on the paragraph. In our usability testing it was painful obvious that the natural tendency was to hover over the Big letters instead.
You might think the solution would have been to also make the Big letters Link controls. But when I attempted that I quickly learned that Link controls do not have the ..Color property. Which meant that although I could achieve the light up effect with the standard style hover settings, I did not have a way to light up the letter automatically from the timer procedure.
This lead me to my final solution. Many development environments have some form of a “region” control concept. A region is basically an invisible box on the screen that intercepts mouse actions whenever the mouse enters, leaves or clicks in the region. WB does have a specific region control, but my first guess was that Cell (not HTML Table Cell) controls were the answer. But unfortunately they only have the “onclick” process they lack the “onmouseover” and “onmouseout” processes.
Form there I experimented with several variations of button and image controls trying the get the correct effect. Most either didn’t have the processes needed or I was not able to get the controls overlaid in a manner that would display the static controls, but still have the entire region intercept the mouse actions. When the static controls were visible, they would intercept the mouse actions instead of the control I was using as a region. Meaning that the hover effect was turning on and off within the region as the mouse touched the static controls.
The combination that finally worked for me and gave the desired effect was an Image control. Not a clickable Image control, just a normal Image control. But the real key was displaying a completely transparent image in the control, otherwise the browser would show the dreaded missing image symbol when displaying the page. So I created a 1×1 pixel transparent image, which BTW has been a mainstay “hack” of web developers for main spacing issues over the years.
So the final version of the CURE has 3 static controls. There is nothing special about their description other than they all have the “The control can be overlaid” property turned on. I like to refer to this check box as the “Make it Work” check box. When it is turned on, the resulting HTML uses CSS to overlay control on top of each other.
Without it on, a few different things happen. First in the IDE if you try to drag and drop a control over the top of another control and they do not have the property turned on, the control turns pink indicating it can not be done, and the drop action is ignored.
If you use the arrow keys or manually enter the X and Y positions of the controls you can get them placed over the top of each other but the overlapping area will display in pink, indicating you have an issue.
When displaying a page with one of these areas you are likely to get unpredictable results, depending on the browser, the version, and I believe the phase of the moon, it may display fine, it may move the controls apart effecting the layout of the entire page, or it may open a black hole in swallow the poor unsuspecting visitor to your site. Since sending people to their deaths in black holes is frowned upon, please remember to check the “make it work” property when overlaying controls!
So the three static controls all have “The control can be overlaid” property turned on. Next the Image control covers the entire “region”. The U region is selected in the below image.
On the general tab of the Image, the 1×1 transparent image is specified, and the display mode is set to stretched. Otherwise regardless of how large the image control is, when ran it would only occupy 1 pixel.
On the GUI tab the “Make it Work” box is checked!
If needed the style settings are changed to not show any border, hover effects etc.
There you have it, you just created a “region” control, but it does do much just yet. Now it is time to put a little code behind it. There is code in the “onclick”, “onmouseout” and “onmouseover” processes.
The “onclick” code is calling the browser procedure to display the Prescription Pad popup, and that will be covered later in the article.
The “onmouseout” calls the LetterOut browser procedure with two parameters, the letter number (C=1, U=2, R=3, E=4) and a Boolean value that indicates that the call is being made from the Timer procedure or not. You have already seen the SWITCH statement of the procedure that does the actual work of changing the text of the paragraph and the color of the Big letter. The only other code in the procedure is :
IF NOT FromTimer THEN TimerNumber = Timer(LetterTime,150) END
FromTimer is the Boolean parameter passed to the procedure, in this case the value is false, which executes another line of code that you may recognize. The timer is being stopped whenever the visitor manually hovers over a region of the CURE, so when the mouse leaves the region, the timer has to be restarted.
The “onmouseover” calls the LetterOver procedure with the same 2 parameters. This is the procedure that lights up the Big letter and displays the alternate text. Again you have already seen the SWITCH statement that does the heavy lifting of the function, the only other code is :
IF NOT FromTimer THEN EndTimer(TimerNumber) IF LastLetter > 0 THEN LetterOut(LastLetter,True) END LastLetter = WhichLetter END
Again this code only executes when called from the a manual mouse event when FromTimer is false. The first line stops the timer, so the automatically rollover effect stops while the visitor is manually exploring the CURE area.
LastLetter contains the letter that is currently lit up. Naturally you want to turn off the existing letter before lighting up a new one, so I call to LetterOut is made with that letter number. Notice that this time the call is made with the FromTimer being set to TRUE. That is because we only want the letter to be turned off, we don’t want the Timer to restart.
The final line of code sets the LastLetter to the new Letter that has been lit up.
And there you have it, the hover and click regions now work, and you have seen all of the code of both the LetterOut and LetterOver procedures. The code behind the other letters is identical, except for the letter number and text being passed. At the end of the document I will give you a link to a PDF showing all the code in line so that you can see the entire process.
Browser Variables via Hidden Edit controls
When I first started this article the two variable to the Page (TimerNumber and LastLetter) I had created as hidden edit controls. But when I got ready to work on this section of the article, I reread the online help page, a little closer. And then I reread it again. Then I got out a piece of paper and made a road map for myself. Suffice it to say the interaction between server variable and global variables is very complicated. At times you are able to able to reference variables from one to the other, but for the most part you are not able to effect them. For instance you can not change the value of a server variable from browser code. Remember the browser code is running on the users browser and has no access to the server. In this code, after rereading that page, I am creating my two browser variables in the “onload” process, which makes them available to all browser code. If you define them in the Global Declaration or Page Initialization processes, which are both server code, then you would get warnings about not being able to access server variables from browser code, and would get odd behavior when attempt to.
So the example I was going to show you no longer applies to this page, but for future reference, I will not that using hidden edit controls as “variables” is one method that I have used when running into variable scope issues. If you have a page that is not acting the way you think it should one of the things to look at is the variable scope of each variable and read the online help page linked above a few times.
The Prescription Pad Popup
And like any good Pitchman I have kept you waiting until the end for the feature you really came to see! When a visitor clicks on a region of the CURE, the full text both the paragraph and the alternate paragraph are displayed in a popup window that looks like a Prescription Pad.
Gimmicky? Sure but a little gimmicky here and there will help your site be remembered, as long as its not over done.
This is using a new feature of V17 called Popup pages. In V16 we could accomplish the same effect with a hidden cell but it as harder to maintain and could case sizing issues, etc in the browsers. With v17 they have made the feature really nice and easy to use.
So what are Popup Pages? Think of them as little “mini” sub-pages of your page. From a technical part they are part of your actual page and are initialized at the same time as the page. This is an import tidbit to keep in mind, since they are initialized when the page is if there are any controls that you need to have special values or properties based on changes the visitor has made to the page then you will need to apply those changes to the controls of the Popup Page before displaying it.
The good thing about them is they are part of your page so they “live” in the same context as your page
The bad thing about them is they are part of your page so they “live” in the same context as your page.
In other words they are defined on your page, they are not separate pages or anything like that. When I first created my prescription pad popup message, that was something I didn’t like about it, I would have to create the same popup on every window that I wanted use the popup on. Not exactly the refactoring Nirvana we are suppose to be living in huh?
Well I did a lot of experimenting in the last few weeks with different methods of refactoring/sharing popups between windows and I believe I have managed to work out a fairly good method of doing it.
The key to my method is that you can create a Popup Page in a control template, what more is you can actually have a control template that doesn’t have anything on it except the Popup Page. Which means that you can then drop that control template on any page, and instantly you have a Popup Page on that Window.
Now take it even one step further you can have a control template, in a control template, so once I created the Prescription Pad Popup control template, I dropped that template onto the CURE control template and the code of the CURE template can reference that popup, and when the CURE control template is dropped on a page everything will come with it as a self contained unit.
So how is the Prescription Pad popup created? Start by adding a control template, either from the Project explorer of the File->New->Page->Control Template menu.
Next from the Page->Popup->New Popup menu add a popup, which switches you to new page editor for just the popup.
This interface is a little difference that normal, you will notice if you hover over the window in the Project bar IDE, you will actually get a choice to edit the popup or the page.
There is also a Popups Button on the title bar.
Popups Pages do not have a border or a background, so adding an image of the Prescription Pad with a transparent background, achieves the Prescription Pad look.
However instead of using an image control I used an Cell Control and set the background image. The reason for this will become clear later.
A normal button would ruin the effect, so I create a button that looks similar to the Close “X” from windows, and place it on the corner of the pad.
There is one line of code for this button, which closes the Popup. Notice that this code is in the browser code!
On the general tab of the button description it is set to not perform any server actions.
And finally two static controls are added for the Heading and the text of the message. I used an HTML Static for the text so I could include HTML code and formatting in the Popup.
I hate it when a message window pops up and to tell me something I have done fails validation, but the message is over the top of what I need to see to know why. So to be kind to the site visitors, why not make the popup window movable? On the GUI tab of the Popup description, select “Movable by the mouse” and the check the Cell as being movable.
Now the popup can be dragged by the mouse and the cursor changes when the visitor is in the allowed area to indicate to them it is can be dragged.
To make it easy to use the popup create a local procedure to display the popup. This procedure takes two parameters the heading, and the text. There are also three optional parementers that control whether the popup is centered or displayed at a specific location. Its sets the two statics based on the parameters and then pops up the Prescription bad.
PROCEDURE PopupMessage(Heading,theMessage,SetPosition is boolean = False,Xpos=0,Ypos=0) POPUP_Pad.STC_Heading = Heading POPUP_Pad.STC_TheMessage = theMessage IF NOT SetPosition THEN PopupDisplay(POPUP_Pad,popupCenter) ELSE PopupDisplay(POPUP_Pad,popupPositionXY,Xpos,Ypos) END
That is all there is to creating the Popup control template. Now to add it to the CURE control template drag it from the Project explorer onto the CURE template.
Once you do you will notice the Popup button appears on the title bar. There are a couple of things to take care of. First on the general tab of the control template set its name. I wished WX would default the control templates base on the template name!
On the GUI tab mark it has not being visible.
And finally re-size and move it into the main cell of the the CURE template so you don’t run into sizing issues when putting the CURE control template on a window.
You have already seen the call to the to display the Popup, in the “onclick” process of the regions. If you look at that code again, you will notice that the procedure name is prefixed with the control template name.
A little Popup Bonus Material
Go to theTaxCure.com, click on one of the orange “Get Started” buttons. That takes you to the “Create an Account Page”. Attempt to add an account for firstname.lastname@example.org. Surprisingly, I already have an account!
A couple of things to notice, about this popup. This page has the CURE control template on it, and there for it already has the Prescription Pad popup page, so there was no need to add it a second time. Also notice that there are links for Log in and forgot password, in the message. Don’t click on forgot password, I haven’t finished that page yet! The ability to insert links into the message was why I used an HTML static control for the text. The code for this call looks like this :
PROCEDURE ValidateEmail() ReturnValue is int = AJAXExecute(ValidateEmailAddress,EDT_Email) IF ReturnValue = 0 THEN CTPL_CURE.CTPL_PopupPad.PopupMessage("Invalid Email Address","Sorry, your email address does not appear to be valid") RESULT False ELSE IF ReturnValue = 2 THEN CTPL_CURE.CTPL_PopupPad.PopupMessage("Account Already Exists","Our records show that you already have an account in our system. <a href="http://www.thetaxcure.com/theTaxCure?_WW1STPAGE_=PAGE_LogIn">Click here to log In</a>. If you have forgotten your password <a href="http://www.thetaxcure.com/THETAXCURE_WEB/US/PAGE_ForgotPassword.awp">get help here</a>.") RESULT False END RESULT True
Notice that the procedure name is prefixed with both the CURE control template and the Popup Pad template names.
In an upcoming webinar we will get into some advanced Timer functionality. For a preview take a look at our “We know why you have ignored the IRS” page. All of that fading in and out of photos is controlled by a couple of timers and pure WX code.
I also did a webinar for wxlive.us covering the CURE effect, so be sure to visit their site to watch the video.