 |
Interactive
|
Chapter points in this section:
How WorshipSession Animates Web Pages
In detail - how to use WsCmd
Changing content ‘on the fly’
Running scripts in WorshipSession
Supplied Interactive Examples
How WorshipSession Animates Web Pages
WorshipSession makes it easy to animate your HTML items, providing simple facilities for building bulleted lists, scrolling to the next item, etcetera. The interactive features are primarily designed to support teaching, where the main points of a lesson can be revealed as the teaching progresses.
How it works - the WsCmd attribute
To understand how WorshipSession animates Items, we need to look briefly at the HTML code inside the Item. Consider the following HTML extract:
<p>The first important point of my sermon</p>
When this HTML is displayed, it looks like this:
The first important point of my sermon
The actual appearance of the text is determined by the Style Sheet attached to the Item, and you can also add ‘Attributes’ to the <p> tag, like this:
<p align="right">The first important point of my sermon</p>
Now when the HTML is displayed, it will be right justified:
The first important point of my sermon
There are many attributes you can add to HTML tags. If you use an unknown attribute, it is ignored by Web browsers, but WorshipSession can still read it. This is how you add the instructions to animate pages.
<p WsCmd="reveal">The first important point of my sermon</p>
The WsCmd="reveal" command causes WorshipSession to hide the paragraph until the pedal or arrow key is pressed.
The first important point of my sermon
You can add WsCmd attributes to a variety of HTML tags, including <p>, <li>, <div> and <img>. The “E1” HTML Utility can add them for you, and your favorite HTML editor should be able to add custom attributes. Alternatively, you can make use of one of the Interactive Templates supplied with WorshipSession.
In detail - how to use WsCmd
Add a class attribute to the body element
To add interactivity to your HTML Items, the first step is to declare the Item as interactive, like this:
<body class="interactive">
This instructs WorshipSession to initialise the interactive facilities described in this section. (If instead you declared class="song", WorshipSession would initialise the Item as a song, adding scroll points between paragraphs.)
The “E1” HTML Utility always adds the class="interactive" attribute.
The class attribute is part of standard HTML - it is used to apply style rules to an element, but can also be used, as here, as a general purpose label.
When WorshipSession initialises an interactive Item, it searches the HTML for blocks with WsCmd attributes, and excecutes the commands as the user presses the arrow key or foot pedal.
WsCmd="Reveal"
This is the basic command from which ‘bulleted list’ Items are constructed. In a typical case, a simple sermon outline with an introduction, three points and a conclusion may look like this:
<div wscmd="reveal">Introduction</div>
<blockquote>
<div wscmd="reveal">1. First point</div>
<div wscmd="reveal">2. Second point</div>
<div wscmd="reveal">3. Third point</div>
</blockquote>
<div wscmd="reveal">Concluding remarks</div>
When this is HTML displayed it looks like this:
1. First point2. Second point3. Third point
WorshipSession hides all the elements initially, revealling them individually as the right arrow key or pedal is pressed.
Using different transitions
WorshipSession offers many different styles of transitions, which are implemented by filters built into Internet Explorer. To use a different transition, add a transition attribute with a number, like this:
<p WsCmd="reveal" transition="10">The first important point of my sermon</p>
Here is a list of available transition styles - the default style is 12.
| 0: | Box in | 12: | Random dissolve |
| 1: | Box out | 13: | Split vertical in |
| 2: | Circle in | 14: | Split vertical out |
| 3: | Circle out | 15: | Split horizontal in |
| 4: | Wipe up | 16: | Split horizontal out |
| 5: | Wipe down | 17: | Strips left down |
| 6: | Wipe right | 18: | Strips left up |
| 7: | Wipe left | 19: | Strips right down |
| 8: | Vertical blinds | 20: | Strips right up |
| 9: | Horizontal blinds | 21: | Random bars horizontal |
| 10: | Checkerboard across | 22: | Random bars vertical |
| 11: | Checkerboard down |
The transition will usually take 1 second, but you can change this using the duration attribute, like this:
<p WsCmd="reveal" duration="10">The first important point of my sermon</p>
Now the first important point will take 10 seconds to fully appear.
If you are using the “E1” HTML Utility, you can specify custom attributes by holding Shift while pressing the WsCmd button. See the E1 documentation for details.
Use the "delay" or "time" attributes for automatic WsCmd execution
WorshipSession can automatically process WsCmd commands after a given period of time. If you add a delay attribute like this:
<p WsCmd="reveal" delay="15">The first important point of my sermon</p>
The paragraph will automatically be revealed 15 seconds after the previous WsCmd.
The time attribute is similar, but it counts from the time the page is first loaded, rather than the previous WsCmd. Use time when you want to synchronise your animation with a video or soundtrack.
<p WsCmd="reveal" time="2:15">Timely comment!</p>
Here the ‘Timely comment’ appears 2 minutes and 15 seconds after the page is loaded.
The delay and time attributes can be used to create self-running presentations, and may also be useful for instances where a list of items should be revealed in succession.
Where a delay or time attribute has been applied you don't need to wait for it - pressing the pedal or arrow key cancels the timer and executes the next WsCmd as normal.
If you want to synchronise your WsCmds with a soundtrack (for example when you are displaying the lyrics for a pre-recorded song), you can use sync attribute instead of time. In this case the WsCmd will be excecuted when the Background Sound reaches the time specified.
<p WsCmd="scroll" sync="2:15">song words verse 2</p>
The BackgroundSound itself is also defined as a custom attribute, like this:
<p backgroundsound="audio/music/KK/tinylittleme.wma">Have you ever wondered
When specifying a Background Sound in this way, note that a “WS relative path” must be used - i.e. a path from the root folder of WorshipSession, not the folder in which the HTML file is stored.
When the page is loaded, WorshipSession looks right through the HTML looking for a Background Sound. If more than one backgroundsound attribute appears, only the latest one will be heard.
If you are using the “E1” HTML Utility, you can specify custom attributes by holding Shift while pressing the WsCmd button. See the E1 documentation for details.
Use the ‘scroll’ command to show the next page
Because it is based on HTML, WorshipSession is not ‘slide based’ like most other presentation systems. A single song Item can be indefinitely long, and WorshipSession scrolls the Item to show each verse of the song.
When an Item is declared class="interactive" to enable interactive features, the normal scrolling rules are not used, and you can add your own scroll points using a WsCmd attribute like this:
<p WsCmd="scroll">Next section of my sermon</p>
When WorshipSession executes this WsCmd, it scrolls the <p> element to the top of the screen, using its familiar ‘slow to stop’ style.
You can combine the the scroll and reveal commands in creative ways to give your presentation more of a ‘slide show’ feel. Look at this HTML:
<div WsCmd="scroll" class="fullscreen">
<p WsCmd="reveal">Next section of my sermon</p>
</div>
The class="fullscreen" attribute applied to the <div> element causes that element to occupy the whole screen (note this depends on CSS style rules associated with the document), so when the scroll command is executed, it looks like a new blank slide.
You can add a delay attribute to make a scroll command execute automatically. For details see above.
Other WsCmds - jump, nextpage, target, javascript, & feature
The WsCmds "reveal" and "scroll", together with the "delay" and "time" attributes, form the core of WorshipSession's interactive features, and using these together with traditional HTML skills, you can create effective interactive presentations in WorshipSession. In certain specific applications you may need to use other WsCmds and attributes as shown here.
The jump command works exactly like the scroll command, except that there's no ‘slow to stop’ effect - the Item is scrolled immediately to the new position. This gives a more ‘slide show’ style, and can be used to create animation effects.
The nextpage command is rarely needed - When WorshipSession has executed all the WsCmds on a page, the next arrow key or pedal press would normally cause the next page to be displayed. The command has been included primarily for use with the delay attribute - you can make WorshipSession display the next page automatically after waiting a few seconds.
The target attribute is used together with the scroll or jump commands. If you write HTML like this:
<p WsCmd="jump" target="firstitem"></p>
WorshipSession will not scroll the Item to this paragraph, but instead will attempt to find an element marked id="firstitem", and scroll the Item to there.
The target attribute allows you to create looping presentations. After WorshipSession scrolls the Item to the "firstitem" element, the search for subsequent WsCmds continues from that point, so you can make it go right through your Item again.
Note that using target does not re-hide any elements that have been shown with the ‘reveal’ command. Looping presentations should only use the ‘scroll’ or ‘jump’ commands.
For users familiar with scripting in HTML, you can call a script function from a WsCmd like this:
<p WsCmd="javascript:MyFunction ()"></p>
This is similar to the syntax used for calling a JScript function from within an <A> tag. See the section below on scripting.
You can use id="feature" to create an alternative branch in a presentation, or to break a loop. If the user presses the keyboard f key, or presses both pedals together, WorshipSession searches the Item for an element marked with id="feature", and executes the WsCmd there.
Use of target and feature is an advanced topic, and most users can avoid it altogether. If you want to create looping presentations, take a look at the Interactive Examples provided with WorshipSession.
Changing content ‘on the fly’
This topic and the next are for HTML experts, and assume some knowledge of scripting. The “E1” HTML Utility simplifies this process by handling the details for you - see the E1 documentation for details.
If you don't want to write any HTML, you can still benefit from the advanced features contained in the Supplied Interactive Examples.
Using a Microsoft extension to standard HTML, you can write pages that can be changed at run-time. If you write HTML like this:
<p contenteditable>This paragraph can be changed.</p>
The result looks like this. You can click the mouse on the paragraph and edit the text -
This paragraph can be changed.
Any changes you make in the paragraph above will be lost when this page is reloaded, but WorshipSession can make this feature much more powerful by remembering the changed content. If you add a savecontent attribute:
<p contenteditable savecontent="1">This paragraph can be changed.</p>
..and display the page in WorshipSession, the content of the paragraph will automatically be saved, and restored when the page is next displayed. This simple facility opens up a huge range of creative possibilities, and is extensively used in our Interactive Examples.
savecontent - how it works
Saving and restoring content is triggered by adding a savecontent attribute to your body tag:
<body class="interactive" savecontent="1">
WorshipSession does not modify your HTML document - it saves the modified fields in the Session. Alternatively you can specify a filename for saved content, by adding a DataUrl attribute:
<body class="interactive" savecontent="1" dataurl="MyPageData">
Dynamic content will be loaded and saved to the file MyPageData.ws_xml, in the same folder as the HTML document. If a document saves its content in a file like this, you can use it several times in one Session, and the content will be preserved. Items that store content in the Session can also be used several times, each instance having its own independent content.
WorshipSession creates one XML entry for each savecontent element in your document. If you edit your document and add or remove savecontent attributes, remember to delete any matching ws_xml file to avoid mismatch errors when the elements are restored.
Note that contenteditable and savecontent can be applied independently. You can create editable elements that are not saved (great for collecting input at brainstorming sessions), and also you can save elements that are not editable - you could use this facility within a script, to store the value of a variable. See the next section on scripting.
Sometimes you don't want the previous values in a page to be restored
(for example your saved content might say, ‘Happy birthday George’, but today is Samantha's birthday!) You can prevent WorshipSession restoring
the content by holding down the Keyboard Alt key while displaying the page.
Running scripts in WorshipSession
If your HTML pages include scripts, these will run as normal in WorshipSession. You can use the onload event to perform initialisation, start timers etcetera. Your pages will receive all the normal mouse events, but no keyboard events, since WorshipSession itself handles keypresses. In place of the usual keypress events, WorshipSession issues two calls that you can implement in your page:
| PreWsKeypress (Ch) | Called before WorshipSession performs any keypress handling - return true to suppress normal handling of this keypress within WorshipSession. |
| PostWsKeypress (Ch) | Called after normal keypress handling, only if the keypress was not handled within WorshipSession. |
Initialising your script
For pages that rely on the savecontent facility described above, WorshipSession issues two calls for initialisation. It calls InteractivePreInit() before performing its own initialisation, and InteractivePostInit() afterwards. You should implement one or both of these functions in preference to the usual onload handler, because you can rely on the state of the restored elements. To see how this works in practice, examine the code in the Interactive Examples.
InteractiveFinalise
WorshipSession also calls into your page just before it is unloaded. Implement the InteractiveFinalise() function to take any final actions, such as transfering variables into savecontent elements so that WorshipSession will save them. Use InteractiveFinalise() in preference to the usual onbeforeunload handler, to avoid potential sequencing problems.
Calling WorshipSession functions
WorshipSession is implemented entirely in JScript, and your scripts can call functions within WorshipSession. The majority of functions should not be called, but some are provided specifically for use from client HTML pages. To call a function from your script, use window.parent.FunctionName().
| InteractiveGetPosition () | Returns the current ‘Position’ of the interactive presentation. (The actual value returned is not useful, except as a parameter to InteractiveSetPosition.) |
| InteractiveSetPosition (Pos) | Sets the current ‘Position’ of the presentation. Use this in conjunction with InteractiveGetPosition() and savecontent to save the current state of a page for later display. Also call InteractiveSetPosition(0) to reset the ‘Position’ to the first WsCmd in your document. |
| RestartPageTimer () | For WsCmd elements marked with a time attribute, this function resets the timer to 0. |
| SetBackgroundSound (URL) | Play a sound file (WAV, MP3, WMA etc) using WorshipSession's ‘BackgroundSound’ object. When specifying a Background Sound in this way, note that a “WS relative path” must be used - i.e. a path from the root folder of WorshipSession, not the folder in which the HTML file is stored. |
Supplied Interactive Examples
WorshipSession is supplied with some interactive HTML pages that may be used ‘as is’, and may also spark your imagination, enabling you to write creative Items suited to your own situation. All these pages are included in the original WS distribution, and can be accessed by pressing F12 and typing the name as below.
To see the URL of any Item being displayed in WorshipSession, press U.
Note: Take care when changing the editable text in HTML pages. In general, don't press Enter, which creates a new paragraph. Use Shift-Enter to create a new line, and Tab to move to the next editable field.
When you finish editing text, press Esc to resume WorshipSession's normal keypress handling.
If you mess up the editing and can't recover it, hold down the keyboard Alt key while displaying the page. This instructs WorshipSession not to restore the saved content.
Brief description of supplied Interactive Items
| #Big Title | A simple 72pt Title page. Edit the text as required. |
| #Number plate | A UK-style vehicle registration plate. Edit the text as required, and add a message to the car owner. |
| #3 Point Sermon template | A title, sub-title, and three points, all with ‘disolve’ transitions. To change the text, you must reveal all the points first - best done before you start to preach! |
| #Notices | Similar to the sermon template, this shows up to 7 items - each item can have a time with it. The items scroll up the screen so they fit in the space. |
| #Countdown timer | A big ‘remaining time’ display counts down from a specified time, and an alarm sounds when zero is reached. The remaining time is remembered when the page is unloaded, enabling you to display other Items while the countdown continues. |
| #Timer / stopwatch | A big ‘elapsed time’ display counts in seconds, and adds hours and days as appropriate. The time is remembered when the page is unloaded, enabling you to display other Items while the timer continues. |
| #Congratulations! | An animated page that shows a simple message in various font styles and colours. (You may need to modify this to use fonts that are present on your system.) |
| #Dice | A fun ‘roll the dice’ Utility. |
| #2 Dice | A fun ‘roll two dice’ Utility. |
| #Bible Verse (editable) | An editable page that’s formatted like a Bible Passage. Useful if you need to quote a verse in a version that’s not installed. |
| #Cute Quote (editable) | A nicely formatted page for displaying a quotation. |
| Kidz Klub/songs/ tinylittleme.html | (Display this page using F11.) Illustrates the use of the sync attribute to show song lyrics synchronised to a pre-recorded sound track. |
The actual HTML files for these Items are in the /Interactives folder - please feel free to modify them to suit your requirements. If you write any new Items suitable for distribution to others, why not send them to the WorshipSession Team, and we will be pleased to put them on our server.