Today I’m starting a new series of blog entries about extending the upcoming Lotus Quickr. The series will cover some of the new features, from a developers point-of-view, that will be available for you. You will be able to test most of them on upcoming beta releases, if you’re part of the beta program.
The tutorial today will show you a way of creating modal floating windows that can have any HTML you want in it. Click the thumbnail to see a larger image of what it looks like. The code is developed on top of the Dojo Toolkit that is now distributed as part of Lotus Quickr.
It is a modal window because the end user can not do anything else on the page until he clicks either of the buttons in the floating window or the close button in the top right corner of the floating window. (This “window” does not prevent the user from clicking the browsers back or close buttons.) It really is not a floating window. It’s not a window at all. It is a div object that is set to be on top of everything else on the web page when it is shown. The good thing about this is that we don’t have to worry about pop-up blockers. Another thing that the modal floating window does is that it darkens everything else on the web page to really focus in on the contents of the floating window. On to the tutorial.
First we create a new HTML page in our favorite editor. My new favorite is Eclipse Callisto with the Aptana plug in. Add a script tag inside the body tag. We have to add the script tag inside the body tag because Lotus Quickr will strip everything from our HTML code that is not within the body tag. So we have something like this:
<html>
<head>
</head>
<body>
<script type="text/javascript">
</script>
</body>
</html>
Time to add some functionality to our HTML code. First we add the reference to the ModalInput widget by adding the following code inside our script tag:
<script type="text/javascript">
dojo.require("dojowidgets.widget.ModalInput");
</script>
dojo.require is the Dojo way of referencing one of its JavaScript files. This happens to be a widget created by me and not by the Dojo developers but can still be called this way since it is referenced by its name space “dojowidgets”. Let’s not go in more on that. This tutorial would lose its focus very quickly, if I did that. If you want to read more about the Dojo Toolkit and how to create your own widgets please visit their website.
Next we want to add the button and the function that opens the floating window. Just before the end of the body tag we add:
<input name="mybutton" type="button" value="Open Modal" onclick="openMyModal()" />
Inside the script tag we add the function openMyModal:
function openMyModal(){
var sHTML = 'Your Name';
sHTML += '<br />';
sHTML += '<' + 'input type="text" id="modal_name" value="" style="width:95%;" />';
sHTML += '<br />';
sHTML += 'Your interests';
sHTML += '<br />';
sHTML += '<' + 'textarea rows="3" id="modal_interests" style="width:95%;"></textarea>';
var myModalParams = {
widgetId: "MyModalInput",
title: "My Custom Modal Form",
formText: sHTML,
submitFunction: "myModalSubmit"
};
var myModal = new dojowidgets.widget.ModalInput(myModalParams);
}
This function is what opens or show the “window” and whatever HTML we have chosen pass in. Let’s go over the function in more detail. The first part is where we declare a variable sHTML and add a string of the HTML that we want to show inside the floating window. As you can see we have a couple of labels, a text field and a text area field in the string representing the HTML. In the next part of the function we declare a variable myModalParams and add an object to it. This object represents the parameters that we pass into the floating window widget. More on these parameters in a moment. Last we call the ModalInput widget code and pass in our parameter object. We do this by setting a variable myModal.
Back to the parameter object that we created. As you can see we declared 4 properties to our object: widgetId, title, formText and submitFunction. These are not the only parameters that we can pass into the widget and all parameters, including these 4, are optional. Let’s go over them one by one.
- widgetId:
- Default: “modalInput” (string)
- If you have more then one floating ModalInput on the page it is important to set their unique ID’s.
- title:
- Default: “” (string)
- This is the title text in the window bar.
- iconSrc:
- Default: “information.gif” (string)
- This is the image icon before the title in the window bar. Pass in the full URL to the image. The image should be 22×22 pixels.
- formText:
- Default: “” (string)
- This is the HTML that you pass in to be displayed within the window.
- width:
- Default: “350px” (string)
- The width of the window in pixels.
- height:
- Default: “250px” (string)
- The height of the window in pixels.
- resizable:
- Default: false (boolean)
- Should the window be re-sizable or not.
- displayCloseAction:
- Default: true (boolean)
- Should we display a close button in the top right corner of the window.
- submitFunction:
- Default: “” (string)
- The name of the function we should call when the Submit button is pressed. This function should return true or false if we should hide the window.
- cancelFunction:
- Default: “” (string)
- The name of the function we should call if the Cancel button is clicked. This function should return true or false if we should hide the window. Use only if you need to have a Cancel function. I.E. you need to undo something when the user clicks Cancel.
- submitValue:
- Default: “Submit” (string)
- The text inside the Submit button. Could be “OK” or “Yes”.
- cancelValue:
- “Cancel” (string)
- The text inside the Cancel button. Could be “Close” or “No”.
Now we only need to add one more thing to our code to complete this tutorial, the function we call by clicking the “Submit” button inside our floating “window”. Inside our script tag we add:
function myModalSubmit(){
var sName = dojo.byId("modal_name").value;
var sInterests = dojo.byId("modal_interests").value;
if(sName == ""){
alert("FAILURE!nn" + sName + 'n' + sInterests);
return false;
}else{
alert("SUCCESS!nn" + sName + 'n' + sInterests);
}
return true;
}
We had added the value myModalSubmit to our submitFunction property above so we need to add a function with that name to our code. This function would in reality probably be much more complex than alerting “SUCCESS” or “FAILURE”. However in this basic demo that’s all we are doing. The function checks if you added a name in the field and alert result either way. If we did add a name it will close/hide our modal window by returning true, if not it will leave the window open by returning false. In the code you see that I’m using dojo.byId. That is just a more robust and shorter way of using document.getElementById.
Now all you have to do is to create a new “Imported Page” inside your Lotus Quickr place and select your HTML file as the file to import. Save and you will see the page with the button to click to open the modal floating window.
If you are lazy like me, and don’t want to create the file yourself, you can download the [download#3#nohits] zip file, unzip it and upload like above.
Now you can go and update the HTML to whatever you want and play with the widget parameters to suit your needs. In reality we would add this code to a custom HTML form and save our data down to regular or hidden fields on it. As an example I’ll show you a screen shot of the upcoming Lotus Quickr QMeeting template that we just finished.
If you have any comments about this tutorial, please submit them below. I will have a new tutorial for you as soon as I have another sleepless night.