The ScrollWindow is a highly versitile piece of code which takes care of loading files into layers for you. If you've used the original Scroll widget before, you'll recognize much of the functionality of this object. It was specifically built for my new Scroll2 widget, but it most certainly can be used on it's own.
What this component does is draw a few layers and provides all the functionality you'd ever need when dealing external pages. It does not have any scrolling mechanism like the Scroll object does, however it gives you all the information and hooks that you need to create one. The Scroll2 widget fully utilizes these hooks to control the content inside the ScrollWindow. If you wanted to do some crazy scrolling mechanism (a turnable knob has been mentioned) this is the object you'd want to base it on.
As well you can use it for manipulating inline content (content which is in the same page as the ScrollWindow itself) in a nice manner. You can have multiple inline blocks, and even load a bunch of inline blocks all from one external page! This way you quickly tab through several blocks of content and have all content already loaded instead of loading each piece of information from and external file as with the previous Scroll widget.
As always the ScrollWindow follows the build-writeCSS-writeDiv-activate sequence. However the activate method is special in this instance. You only call the activate() method normally if you are using inline content (read below). If you load external pages into the ScrollWindow you have to call the activate() method from the external page, not the page that the ScrollWindow is in (ie. don't activate from the init() function).
The Constructor
objectName = new ScrollWindow(x,y,width,height,frame,name)
The first 4 are obvious, frame and name are both optional.
The ScrollWindow has full support for frames. I know this was a much requested feature you now you have it. You have to send the name of the frame as a string:
mywindowinaframe = new ScrollWindow(50,50,200,200,'myframename')
But there's more involved when dealing with frames, so keep reading...
The name parameter is just a way to force all the div's that will be written to have a unique name. If you don't send a name parameter the ScrollWindow will choose it's own, each ScrollWindow will have an index and write all it's div's with that index, the first one will be called ScrollWindow0, the next one ScrollWindow1, and so on. If you want all the layers to be named with something else you'd give it a string like 'myscrollLayers' or whatever. But beware the name you choose cannot be the exact same as the object otherwise you'll recieve a JavaScript error.
Most of this is verbatem from the Scroll and Scroll2 ways to load files so I'll be brief. You just call the load() method and pass whatever filename you want:
mywindow.load('myfilename.html')
This file must contain an onLoad handler which calls back to the ScrollWindow object to activate it.
<html> <head> <title>My External Page</title> </head> <body onLoad="parent.mywindow.activate()"> The content of my page goes here </body> </html>
Example: demo-external.html [source] - shows a scrollwindow that loads an external file
External pages when using Frames
If your ScrollWindow is in a frame, and you load an external page you have to do the activate() call with window.top.yourframename.yourscrollname.activate(), for example if your frame is named 'myframe', and your scrollwindow is name 'mywindow', you're external page would look like this:
<html> <head> <title>My Title</title> </head> <body onLoad="window.top.myframe.myscroll.activate()"> The content of my page goes here </body> </html>
Buffering and Non-Buffering of the external pages
As in the original Scroll widget, the ScrollWindow will by default "buffer" the external page. What it does is write a hidden IFrame and uses that to mirror the contents of the page to an empty layer in the page. This avoids a whole lot of trouble with IFrame's, but creates a few problems. The pages work best if they are mostly static content - images, text and so on. If you have forms and layers and a whole pile javascript that you want to do in the external pages you might be better off not using this buffer feature. You can turn it off by doing:
mywindow.usebuffer = false
This will cause the ScrollWindow to write an IFrame that is not hidden, the page you load with the load() method will simple change the the location of the IFrame to the url.
A non-buffered page needs to have a layer inside it because the ScrollWindow needs to be able to move this layer around, and thus all the content in the page too. This layer can be created by inserting the stuff in red:
<html> <head> <title>My External Page</title> <script language="JavaScript"> parent.mywindow.writeContent() </script> </pre> </head> <body onLoad="parent.mywindow.activate()"> <div id="content"> The content of my page goes here </div> </body> </html>
Things to note when using non-buffering:
If there is a situation where you don't need the content to come from another file you can use this optional way to write the div's for the ScrollWindow:
<script language="JavaScript"> document.write(mywindow.divStart) </script> My inline content goes here <script language="JavaScript"> document.write(mywindow.divEnd) </script>
This is useful particularly if page is being auto-generated from a script of some sort.
Example: demo-inline.html [source] - shows a scrollwindow with inline content
Multiple blocks of content is a new feature I've introduced into the ScrollWindow and thus also supported by the Scroll2 Object. Say you had 4 or 5 pieces of content that you wanted to be able to flip between quite quickly. If you had each of these in separate pages and did a load() to bring each one of them in on demand, you have to wait for the browser to go to the server again and retrieve that file. Well, the new multiple blocks option will avoid this. It allows you to have have several pieces of inline content.
To set this up you must tell the ScrollWindow how many blocks it will contain. You must do this after it is defined, and before you build it:
mywindow = new ScrollWindow(200,50,250,200)
mywindow.inlineBlocks = 4
mywindow.build()
Inline Blocks
Now, when you're writing the div's you have to manually assemble the DIV tags for each block. If you do not use the name parameter then you have no choice as to the format of this. For your first ScrollWindow your div's will look like this:
<script language="JavaScript"> document.write(mywindow.divStart) </script> <div id="ScrollWindow0Block0"> This is the first block </div> <div id="ScrollWindow0Block1"> This is the second block </div> <div id="ScrollWindow0Block2"> This is the third block </div> <div id="ScrollWindow0Block3"> This is the fourth block </div> <script language="JavaScript"> document.write(mywindow.divEnd) </script>
Obviously these are indexed, so the numbers start at 0, and end at inlineBlocks minus 1. If you don't get this correct you'll get an error.
Now if you happen to use the name parameter you have use that name instead of the 'ScrollWindow' part of those div's. If you're name is 'mywinLayers', your blocks would be 'mywinLayersBlock0' and so on.
External Blocks
I also allowed you to have the inline blocks all come from an external page (external inline blocks? :) I call it the externalMulti feature, but really there is no difference as to your coding except that you don't write the blocks in your main page:
<script language="JavaScript"> document.write(mywindow.div) </script>
Instead you put those exact same block DIV's into an external page:
<html> <head> <title>external page, with multiple inline blocks</title> </head> <body onLoad="parent.mywindow.activate()"> <div id="ScrollWindow0Block0"> This is the first block </div> <div id="ScrollWindow0Block1"> This is the second block </div> <div id="ScrollWindow0Block2"> This is the third block </div> <div id="ScrollWindow0Block3"> This is the fourth block </div> </body> </html>
You then have to load this external page as normal with the load() method.
Swapping Between Blocks
By default the 0 block will be displayed, all others are hidden. To swap which one is shown you use the showBlock() method:
mywindow.showBlock(2) // send the index of the block you want to show
Example: demo-multi.html [source] - inline blocks
Example: demo-ext-multi.html [source] - external blocks
| Property Name | Description |
| name | holds the name used for all the layers |
| w | the width of the window |
| h | the height of the window |
| frame | points to the frame that the window is in (eg. parent.yourframe) |
| border | the size of border to put around the content, defaults to 1 |
| borderColor | default is 'black' |
| bgColor | default is null (transparent) |
| url | holds the currently loaded page location |
| usebuffer | boolean whether or not to use the buffer feature, default is true |
| inlineBlocks | number of inline blocks the content will have |
| inc | the number of pixels to move each time it is scrolled (when the up,down,left,right methods are used), defaults to 10 |
| speed | the speed in milliseconds the content will scroll |
| contentWidth | width of the content in the window |
| contentHeight | height of the content in the window |
| offsetWidth | difference between the contentWidth and and the width of the window |
| offsetWidth | difference between the contentWidth and and the width of the window |
| enableHScroll | boolean whether the content is wider than the window (if it can scroll horizontally) |
| enableVScroll | boolean whether the content is taller than the window (if it can scroll vertically) |
| Method Name | Description |
| build() | assembles the css and div properties to create the layers needed |
| activate() | assigns all DynLayers and gets relevant information to allow the object to function |
| up() | begins scrolling the content in the window up |
| down() | begins scrolling the content in the window down |
| left() | begins scrolling the content in the window left |
| right() | begins scrolling the content in the window right |
| stop() | stops all scrolling action, cancels the up() down() left() or right() methods |
| getXfactor() | returns a value between 0 and 1 according to the x-position of the content. 0 means it's at the left boundary, 1 means it's at the right boundary |
| getYfactor() | returns a value between 0 and 1 according to the y-position of the content. 0 means it's at the top boundary, 1 means it's at the bottom boundary |
| load(url) | loads a page into the window |
| reload() | and internal method to reload the current external page |
| back() | loads the previous page in the ScrollWindow's built in history |
| forward() | loads the next page in the ScrollWindow's built in history - if no page is available this will do nothing |
| showBlock(i) | shows a particular inline block |
| setMargins() | before you build() the object you can set the 4 margins (left,right,top,bottom), by default they are all 0 |
| DynLayer Name | Description |
| lyr | the top-most layer of the ScrollWindow |
| blocklyr[] | array of the multiple block layers if there are any |
| screenlyr | a placeholder layer for the content (this is a mostly for proper formating, you usually don't have to worry about it) |
| contentlyr | the layer that actually contains the external or inline content, multiple block layers will be nested inside this layer. This is the layer that is moved up down, left or right when you scroll |
The onScroll Event
The onScroll event is called each time the content is scrolled, for each step it moves. This allows you a way to "do stuff" when the content in the window is being scrolled.
mywindow.onScroll = MyOnScrollHandler
function MyOnScrollHandler() {
// code to do stuff when scrolling
}
From that function you may access any of the properties and methods of the ScrollWindow, for example you could show a status of the X and Y factors:
function MyOnScrollHandler() {
status = "ScrollWindow Factors: x="+this.getXfactor()+" y="+this.getYfactor()
}
You could take a look at the Scroll2 widget source code and see how I use the onScroll handler to accomplish the scrollbar code.
The onLoad Event
The onLoad event is called whenever the content changes. More precisely it is triggered each time the activate() method is called, so it will also be called when you use the load(), showBlocks(), back(), or forward() methods as well.
mywindow.onLoad = MyOnLoadHandler
function MyOnLoadHandler() {
alert('the page is done loading')
// code to do stuff when scrolling
}
Using the down(), up(), left(), right() methods
These methods give a simple scrolling mechanism to the ScrollWindow. These work in the exact same manner that the MiniScroll Object does. When you call these methods, it will activate a slide call on the contentlyr DynLayer. Once that slide is in action, it will slide the contents all the way to the bottom, top, right, or left boundary (depending on which one you call). You can stop any of these slide actions at any time by calling the stop() method.
For a simple scrolling mechanism you can put hyperlinks on your page, like buttons for up and down or whatever. The hyperlink call should follow the good old mouse-click-animation technique:
<a href="javascript://" onMouseDown="mywindow.down(); return false" onMouseUp="mywindow.stop()" onMouseOut="mywindow.stop()">Scroll Down</a>
Using only layers inside the ScrollWindow
In order for the ScrollWindow to scroll it's contents it has be able find the contentWidth and contentHeight values. These are the width and height of the content in the contentlyr DynLayer. However, in Netscape if you have only layers in your content, these values will be 0, and thus you won't be able to scroll the content. In order to get around this you can manually set what you want the contentWidth and contentHeight to be when you call the activate() method:
mywindow.activate(500,850) // (width,height)
Example: demo-methods.html [source] - utilizes most of the functionality of the ScrollWindow
| Home | Next Lesson: ScrollBar Object |