[sword-devel] SWORDWEB Footnote / Cross-ref support

[DM Smith]

Troy A. Griffitts wrote:
> Hey guys,
>     Thank you for the feedback.  I will say once again for the 
> newcomers, in case they haven't realized it yet: I am terrible at 
> making things look pretty.  Anything that looks good on swordweb is 
> due to other people writing nice CSS and HTML, etc.  If anyone has 
> graphic design talent and would like to change some of the CSS styles 
> to replace the X and N with nice neo-conservative abstract art icons 
> we could show instead, I would love for people to use their gifts!
>
>     Concerning hitting the server.  DM, you made a comment about jumpy 
> redraws?  Please be specific about when this happens.  It should do no 
> such thing.  I'd like to fix whatever the problem is.
The following is fairly long as I took some time to reproduce the 
problem and am being very detailed so you can see what I saw.

For today's testing, I used Firefox 1.5, and I cleared the cache and 
cookies related to crosswire.org.
I then restarted the browser to start with a clean slate as far as 
session cookies go.

Today, I used Sloppy, a slow proxy, from http://www.dallaway.com/sloppy 
to simulate a 28.8 connection. (Your point about broadband is well 
taken. I stumbled across this program earlier last week.) The purpose 
was to slow things down enough to see the redraws. (I think that this 
program or something like it should be part of our toolkit.)

I then went to the page http://crosswire.org/study/passagestudy.jsp and 
James 1 was displayed with James 1.19 highlighted. Once shown, I changed 
the size of the font, using Ctrl-scrollwheel, to show all the text, but 
not all the page.

I then clicked on "Show Notes" and the page drew one verse at a time 
until all verses were drawn. At the point when the last verse was drawn, 
I could see all the verses. Then the page scrolled to the bottom.

I guessed it was because it was trying to show the selected verse. So I 
selected verse 1 and it did not scroll to the bottom. Selecting a much 
later verse caused a scroll to the bottom.

I then scrolled to the top and removed the arguments from the address in 
the address bar and reloaded the page. The page redrew with the 
requested state. (I guess cookies are remembering my selections.) And 
the page did not scroll to the bottom. But if I were not at the top, it 
would place me at the top.

Anymore these days, I don't expect the page to scroll on me when I click 
on the page, especially something at the top of the page is clicked, I 
don't expect to be scrolled to the bottom.

These jumps were due to the page being requested again. And using GET 
and not POST. I think that using post may cause a faster redraw. To do 
this, create a form with hidden elements for all the fields that can be 
used for the request. For those that have a value, fill it in. For those 
that don't leave them blank. Then at a place which calls the page 
directly, replace it with an onclick to a function that will fill in the 
argument and then submit the form.

In the case of clicking on the number in front of a verse to select the 
verse, it appears unnecessary to go back out to the server at all times. 
Again, if the direct page request were replaced by an onclick call to a 
function, that function could evaluate the state of the page and 
determine whether the fetch was needed, as in the case of strongs being 
on, or not needed as in the case of notes. In the case where it is not 
needed, it could just change the value of the class attribute. This 
would eliminate a return to the server.

Basically, I am suggesting that all direct requests be changed to 
onclick calls to javascript. The javascript then decides whether to do a 
page fetch, to use AJAX or to do the work directly.
>
>
>     Thank you for the suggestion about preloading data.  Our first 
> impl of these pages work this way.  We've changed to the current impl 
> because not everyone has high speed access and some people pay by 
> bandwidth usage.  Those pages have been way too hot, since adding word 
> click strongs/morph lookups, to grab all the data in one hit to the 
> server.
The suggestion I am making is not to grab everything in one hit. But 
some of it. I am suggesting that the notes and x-refs that show in the 
verses are gotten in advance. But the content referenced by them are 
gotten on demand. I'm assuming that you are using some variant of AJAX 
on the page. I think it could be more widely used.

If I time the refresh of the page with notes and x-refs on versus both 
off, while simulating a 28.8 modem, I don't see an appreciable change in 
load time.

Have you considered or are you using Apache's mod_gzip to deliver 
content? Modern browsers all have the capability to do uncompression on 
the fly.
>
>
>     Always open for patches and help with other items on the todo list:
>
>     http://crosswire.org/~scribe/todo/
>
>
>
> Daniel Blake wrote:
>> FYI - I did the exact same thing.  Toggled the Footnotes on and 
>> immediately scrolled to the bottom of the page to see them.  It may 
>> not be right, but I think most of us have been trained to think and 
>> expect to find things that way.
>>
>> Thanks for the work.  It looks good.
>>
>> Daniel Blake
>>
>> DM Smith wrote:
>>
>>> Looks good. Some thoughts.
>>>
>>> In the NASB module each of the notes and cross references has an "n" 
>>> attribute which can be used for a marker. I don't know if the sword 
>>> api exposes them. If it does, you might want to use it.
>>>
>>> In the "It's just my preference" category, I think that since you 
>>> are not listing the notes at the foot of the page, they are not foot 
>>> notes. The first thing that I did after clicking on "Show footnotes" 
>>> was to scroll to the foot of the page to see the notes. Perhaps just 
>>> call them "Notes".
>>>
>>> In the KJV, notes often have references. How would that be handled?
>>>
>>> If the reference is to something on the same page, should it do 
>>> something different?
>>>
>>> I run my monitor at a high resolution and it is hard for me to click 
>>> on the little 'n's or 'x's. I noticed in the html that the spacing 
>>> is outside the span. Perhaps putting it into the span would help. I 
>>> think that using different marks might also help, such as †. 
>>> You might not need to superscript it or make it smaller.
>>>
>>> It appears that the showing or hiding of footnotes or cross 
>>> references goes back out to the server. It is pretty fast but it 
>>> causes a redraw and a jumping around of the page. I don't know what 
>>> is done during that refresh, but I think that the page could be 
>>> gotten with all the notes and references and the page built with 
>>> them, but making them visible based on the state of the settings.
>>>
>>> To do this, the "Study Tools" options would need to change to call 
>>> javascript to toggle the setting and then invoke the appropriate 
>>> behavior. The spacing around spans would need to be moved inside.
>>>
>>> The appropriate behaviour may be to call passageStudy.jsp as it does 
>>> now or to change the display state of the span with something like 
>>> the following pseudo code:
>>>
>>> /*
>>> * Set the display state of sought tags.
>>> * @param root         the element whose descendants are examined
>>> * @param tagname      the tag of the elements being sought
>>> * @param classvalue   the class of elements being sought
>>> *                     An empty classvalue means that all elements 
>>> match.
>>> * @param displayState "none" to hide, "inline" or "block" to show
>>> */
>>> function setState(root, tagName, classValue, displayState)
>>> {
>>>  // Get all the descendants of root having the desired tagName
>>>  var elements = root.getElementsByTagName(tagName);
>>>  for (var i=0; i < elements.length; i++)
>>>  {
>>>    var item = elements[i];
>>>    // for those elements that match on classValue
>>>    if (!classValue || item.className == classValue)
>>>    {
>>>      // set the state as desired.
>>>      item.style.display = displayState;
>>>    }
>>>  }
>>> }
>>>
>>> I have used something like this to manage a tree made from a nested 
>>> list. If you find this interesting and want more details please ask.
>>>
>>> In His Service,
>>>    DM
>>>
>>> Troy A. Griffitts wrote:
>>>
>>>> A first attempt at footnote / crossref support is available for 
>>>> testing at:
>>>>
>>>> http://crosswire.org/study/passagestudy.jsp
>>>>
>>>> Notice 2 new tools on the right: Show [Footnotes | Cross-references]
>>>>
>>>> Your feedback is appreciated.