S.H. Parker (c) 1999
Well, it’s been an interesting couple of months. From a plethora of complaints about the absence of a searchable database about Clarion, i.e. knowledge bases, we now have three. In the order they came on line (I think), they are: mine ("Cheat Sheet" at www.par2.com), Troy Sorzano’s (www.cwsuperpage.com/kb) and Arnor Baldvinsson’s (accessible from www.icetips.com ). All were deployed in less than two weeks (I keep saying that great minds think alike). And all are also accessible from www.cwicweb.com, just select Clarion.
To look at each, no three applications could be more divergent. I use a traditional Clarion browse-form combo. Troy’s knowledge base has the traditional kb look and feel. Arnor’s looks like a standard HTML page with a parameter collection form on it.
"Divergent?" nothing could be further from the truth (well, that’s not entirely true, each has a unique theme but that does not talk to how they are coded, which is what we are about here). All three are Internet Connect applications. And, all three, to varying degrees, use Clarion as a dynamic HTML generator. Tony makes such extensive use of this that he uses virtually none of the custom Java classes that characterize IC (he has two version of the knowledge base; one makes some use of the IC Java applets, one makes no use of them at all; you should check out his template modifications at www.cwsuperpage.com/kb). If you were to look at his HTML in your browser’s source viewer, you might never even know he’d used Clarion. Arnor uses it to eliminate browses, the heaviest user of the custom Java classes. And I use it as a substitute for a report, to make tips and FAQs more presentable and easier to read.
Dynamic HTML
I am not intimate with the Dynamic HTML (DHTML) specification. But what I have read about it does not impress me much. It seems to me that while DHTML allows a page to be updated without a round trip to the server, it offers little not already available through Javascript. A computation still seems to require pushing a button. In short, my initial impression is that DHTML just incorporates certain Javascript functionalities into the HTML specification.
To me, "dynamic" has always meant, in our context, something like "created at runtime." And that means that you can generate different code under different conditions and display conditionally without user intervention.
Perhaps it would be more accurate to describe what I am thinking of as "dynamically generated HTML." IC, itself, is a dynamic HTML generator. First, all the HTML delivered to the user is generated as requested, at runtime. Secondly, you can set conditions and switches that change precisely which HTML is generated.
For example, if you do not want the standard toolbar locator button to appear when your application runs on the web, you can access its Internet properties and check "Hide if launched from browser." The HTML to create this button will never be generated. Or, if you embed
If WebServer.Active Disable(?Insert:1) End
after the window is opened, but before it is displayed, the Insert button will not appear when the app is run on the web.
And, of course, judicious use of the Accept loop will ensure that computations, etc., are displayed without further user action.
Why is this important?
IC apps can appear to take a big performance hit in two areas. First, downloading the custom classes can be quite time consuming (40 seconds from my home to the CWICWEB server at 28.8). And, this is not always a one-time thing. Internet Explorer 4.x is known to randomly delete files from its cache. So even if the classes have been downloaded, IE may download them again (I have had this happen to me in mid-session, simply while moving from one page to another, during local testing). Second, Java applets have to be interpreted on the client, like batch files, one line at a time. While this gives us cross-platform functionality, it certainly does not match compiled native code execution speed.
Digression: Did you notice that I said that IC apps can "appear" to take a performance hit? Such language would imply that the observed phenomenon is not real, but apparent only.
Let me remove any lack of clarity here. That is precisely what I mean. The claim that IC apps are poor performers can only be justified when comparing IC apps to Windows apps. Compared to other Internet apps, the poor performance claim is entirely unjustified. There are Internet apps that perform better and there are Internet apps that perform worse.
Finding sites that load more slowly than an IC app downloads the classes is simplicity itself. Just find a page with several graphics (or anything created with the Fusion line of products). My own homepage as well as a number of my own articles written for this very journal will do very nicely. Similarly, finding sites that go from list to detail (i.e., browse to form) as "slowly" as an IC app is just as easy. Any page that does a database lookup will do. (For the sake of this tirade, I am presuming that the IC site is approximately the same number of hops as the graphics intensive app. It just won’t do to compare a page five hops away with an IC app 15 away.)
The one thing IC does not do that these other sites do do is display progressively (actually, it does, but not in the way we expect -- from the top down or by dithering). That is, graphics heavy sites fill progressively, so you can see (usually) that something is happening. IC does not provide a progress meter; so, while an IC site may, by the clock, actually load more quickly, the other site may appear, quite subjectively, to be faster. In other words, there would be no performance "issue" if we could figure out how to do a progress screen while loading the classes.
Appearance, not reality.
End of tirade.
Straight HTML displays quickly, if you skip graphics. Clarion provides superb built in data access. The best of both worlds would be Clarion for file access and HTML for display.
And, this is indeed quite possible and, if you are familiar with basic HTML, not especially difficult. If you are not familiar with basic HTML, there are ... efficiencies possible. Ok, it requires a bit of planning and a lot of typing, sometimes, but it isn’t like re-inventing the wheel.
Planning
One thing we do not have to plan for is the required HTML page layout code:
<html>
<head>
<title></title>
<body>
</body>
</html>
Any IC Window or Form provides this for us. In C4, both templates also handle file opening and closing (a 2003 Window does not, you must handle this yourself).
This means that all we really need to worry about is what is inside the <body> tag. That is, all we need to provide is the content of the page.
The question now is "How do we get our variables into the body of the page?" And, there are two kinds of variables we need to consider: file and application variables. By "application variables" I mean variables created in the application: global, module and local variables. While we are at it, we also need to consider constants like string literals.
IC gives us two important built in tools: HTML strings (WebHtmlStringClass) and the Target.Writeln method to create pages with minimal, or no, Java.
To demonstrate the general methods for reducing your dependence on the Java classes, consider the Window template based page I use to display FAQ articles in my kb. In the Clarion IDE, it looks like this:
Figure 1
but when called at runtime might look like this:
Figure 2
WebHtmlStringClass
When you place a String on a window/page that uses a variable, the IC templates will default to using the WebJavaStringClass. Similarly, an image placed on a window/page using a runtime property assignment, like
?Image1{Prop:Text} = ‘that_image.jpg’
or
?Image1{Prop:Text} = Clip(Pre:ImageFileName)
will use the WebJavaImageClass.
In each case, Java classes are being used. And that is what we are trying to avoid. (Yes, this does mean that, if you want to lower the caffeine level of your IC app, you cannot use images on buttons.)
Strings need to be overridden to use the WebHtmlStringClass instead. This class creates HTML strings, not Java strings. A further benefit is that HTML strings are transparent and a background or color image will show through. Java strings are not. (In my student job viewer app, all of the strings on the Form are HTML; you can globally override the default Java strings, should you wish.)
The only time you cannot use the WebHtmlStringClass for a variable displayed as a String is on a browse (a/k/a "hot" field).
Static strings, like "And the FAQ is:" in Figure 1, default to HTML strings. So, nothing further needs to be done with them.
The first two strings on the page are created, at runtime, in the standard way. For example:
WindowManager Method Executable Code Section
Init (),Byte
Line1 = ‘FAQ # ‘ & Clip(FAQ:FAQId) & | ‘ posted on ‘ & Format(FAQ:DatePosted,@D8)
Line2 = ‘by ‘ & Clip(DEV:FullName)
(If you are using 2003 or the C4/Clarion templates, the embed is "After Opening Window.")
The third and fourth strings are just file variables assigned to strings. All standard stuff.
But, for each of these strings, I have ensured that they use the WebHtmlStringClass. The steps are: Procedure Properties ... Internet Options .... Controls ... find the control in the list ... Properties ... Classes ... check Override Default Class ... then select WebHtmlStringClass from the drop down list.
If you want to globally override the standard string class, the steps are: Global ... Extensions ... Internet Application Extension ... Classes ... locate "SString" ... Properties ... check Override default class ... and enter WebHTMLStringClass.
Target.Writeln
We now know how the five strings in Figure 1 were created without using any Java. "But," you must be asking yourself, "where is the text of the article?" Figure 2 clearly shows some text and Figure 1, just as clearly, doesn’t.
Well, it’s in a memo field in the file. (Not very helpful, is that?)
The memo field does not appear to be on the window because it isn’t. (Whole truth time: the window in the app actually does have a text field to display the memo. I didn’t show it to you in the figure because it is also marked "Hide if launched from browser." In other words, it displays only when running in Windows, which also explains the large empty space on the window.)
Target.Writeln is a method of embedding HTML into a page in addition to the Static HTML and Dynamic HTML code templates (for a total of a typical-for-Clarion three ways of doing something). The Static HTML template is ideal for adding HTML tags like <i>, <center> or <strong>. You can neatly use it for string literals too. The Dynamic HTML template is perfect for combining text and variables. In fact, the assignments to the variables Line1 and Line2 shown above could just as easily have been handled with the Dynamic HTML template.
Target.Writeln is much more powerful and, therefore, a bit more work. According to the IC manual, Target.Writeln "allows you to use Clarion code to write the HTML code."
The manual further states that the Target.Writeln method gives us the ability to control the HTML code written by using "the logical structures in the Clarion language to control what is written. You can write one line or another using an IF ... THEN ...ELSE clause, or a CASE statement." Cool. And the power is obvious.
Yes, this does mean that everything you already know about the Clarion language can be put to use to determine what shows on the Web.
So, if the article text is contained in a field called FAQ:Text, what we can do is:
Target.Writeln(Clip(FAQ:Text))
Two questions immediately come to mind. (1) Where? and (2) Can it really be that simple?
Where?
Which embed is appropriate? Actually there are two for the page in Figure 1 (or any other page, for that matter). You can call this method either after the last string (i.e., the last control before where you want the text to appear) or before the Return button (i.e., the first control after the text is displayed). It really does not matter which you choose.
In the first case, you select an embed which accepts standard Clarion code, "Internet, after generating HTML for control" for the string. In the second, you select the "Internet, before generating HTML for control" for the button (emphasis added). Both are accessible by left clicking the control and selecting "Embeds."
Figure 3
That simple?
Almost. Most of the time. Usually. (Not very helpful, am I?)
If the field or string you wish to place on the page requires no formatting, it is actually this simple. All you really need to do is write whatever standard Clarion code you need to get the string you want and Target.Writeln it.
A memo field, however, may very well require formatting. Memo fields usually do not contain any end-of-line characters. Your page, then, will be (dynamically) formatted wide enough to display all of the text (i.e., on a single line -- the FAQ memo field is 10.000 characters -- hmm ... ).
However, if long text is in an HTML table, you automatically get word-wrapping (one of the very few genuinely good things inherent in HTML). So, obviously, we want to surround the text in an HTML table.
We can write any HTML we like, so why no just construct the whole table? The memo will then wrap without having to do any kind of string parsing.
The finished code for the embed looks like this:
Target.Writeln('<<br>') !add a blank line
Target.Writeln('<<center>') !assure centering of the table
Target.Writeln('<<table border="1" cellpadding="3" width="75%">')
!create a table
Target.Writeln('<<tr>')
Target.Writeln('<<td width="100%">')
Clear(TempString)
TempString = FAQ:Text !write memo to a string
Target.Writeln('<<pre>' & Clip(TempString) & '<</pre>')!use formatted text
Target.Writeln('<</td>') !close table parameters
Target.Writeln('<</tr>')
Target.Writeln('<</table>') !close table or NS will puke
Target.Writeln('<</center>')!end centering
It would also have been perfectly acceptable to concatenate everything, stating with "<<br>", into TempString and do a single Target.Writeln(TempString) at the end. It is totally a matter of preference; I happen find this code a bit easier to read.
Since IC creates a table corresponding to the window, this code places another table within that table. This allows you to get very fine control over the layout, something default IC does not always make easy. In my student job viewer app, if you tag a job or two and press Print, you will see this technique, again, used to substitute for a report (you can see what the Report template output looked like in the Integrated app).
The work involved was substantial when the text needs to be highly formatted, but controls end up exactly where I want them. That was worth it (of course, the fact that I still have the DOS version of the report which allowed me to count columns really helped, so did some old FORTRAN coding sheets).
There is a bit more to this. If the field or memo you wish to display contains HTML reserved characters (like "<" or ">"), your app will treat what follows like HTML and try to execute it. This is not a bug; it is in the HTML spec.
To display these characters, your text must substitute "<" and ">" respectively. Thus, if you think your text might include these characters, you will have to create a mechanism for substituting the acceptable HTML substitutes at runtime.
Learn HTML! Oh, no!
No, you really don’t have to learn HTML, though it won’t hurt.
In any decent visual HTML editor (i.e., one that lets you edit the HTML source), create a page that looks like what you want and "requisition" the code ...
Summary
These techniques do not, in any way, compromise the dual nature of IC apps. In one case, as I mentioned, a text control displayed in Windows is hidden on the Web and, of course, the substitute code in the Internet embeds execute only on the web. So, one window still works in both environments. In the other case, I use a switch:
If WebServer.Active ShowFAQ Else PrintFAQ End
to ensure that the reduced caffeine window shows on the Web while the standard report displays in Windows.
Also note, and this is important, that pushed to its logical extreme, apps created totally caffeine free can become unstable on your Web server. Arnor, Troy and I have all experienced this and, at the time I am writing this (early June), have no explanation.
I haven’t taken this technique as far as it can go. Consider, for example, creating an HTML page with a set of tables with a banner across the top, a banner down the side and a blank table. If you placed a marker,
Figure 4
you could easily deduce which embeds to use to surround your Clarion window (you only need two) and copy the code into them:
<html> <head> <title>Sample HTML for IC Page</title> </head> <body bgcolor="#FFFFFF">
<table border="1" cellpadding="0" cellspacing="0" width="80%"> <tr> <td colspan="3" width="100%">Top Banner or Graphic here</td> </tr> <tr> <td rowspan="5" width="20%">Side<p>banner </p> <p>or </p> <p>Menu</p> <p>here</p> </td>
<td rowspan="5" colspan="2" width="67%">IC window here</td> </tr> </table> </center>
</body> </html>
(N.B.: The parts that are struck through are supplied by the Clarion Window template.)
But, I really don’t have to push this discussion all the way, do I? I’ve never met a Clarion user yet who needed more than a push in the right direction.