|
The SSP/3.0 Developer's Guide Version 1.2.0 Scalara Technologies Ltd. Last revised 15 October 2003 [Note: This documentation serves as a reference guide both for legacy users of the 2003-era Scalara platform and for developers of the new 7.0 version.]
SSP/3.0 Overview With the new 3.x updates to the Sirius and Ra product lines, Scalara Technologies has once again significantly improved the feature set and functionality of these products. However, much more so than with previous updates, the 3.x series also represents a fundamental shift in the overall Scalara web service architecture, narrowing the focus to lightweight, high-performance platforms supporting Web Service standards natively. To power much of this new architecture, a much more powerful template parser was also required. The 2.x "SCL" parser, the successor to the JML and WebPlus template languages, was--like its predecessors--still at its core a simple text transformation tool operating on a single in-line string. SCL pushed the limits of what that paradigm could achieve, but with the 3.x series, a more flexible and powerful paradigm was needed. With the 3.x series, Scalara introduces the new SSP/3.0 syntax as the successor to SCL/2.0. SSP, short for "Scalara Server Pages," provides full parse-tree-powered template processing with a "page" paradigm and Server-Side Compilation (SSC) technology to significantly improve performance. Many experienced web developers will note that SSP is still far less flexible than competing template languages like PHP. This limited flexibility is intentional by design. SSP exists primarily to provide a front-end display to an existing application stack (the Dictionary), and many control functions required for advanced post-processing (such as FOR and WHILE loops) are notably missing from SSP. Instead, SSP assumes that your server module application will complete all major data processing. SSP then renders that data without significant post-processing. One seemingly notable exception to this traditional Model-View-Controller (MVC) paradigm is the inclusion of database QUERY support in the SSP syntax, allowing templates to query any server-supported datasource directly. However, from the web-centric view of SSP, this is still consistent with a general MVC paradigm, in that the database exists as a repository of information to be displayed. SSP perhaps exceeds the limits of a traditional display-only language, but does so in the interest of clarity, in a way that clearly divides front-end SSP jurisdiction from the more complex functionality of Scalara server modules. In other words, it would confuse developer boundaries and overall application management to require a series of server modules that query simple data only because the front-end lacked such capability. In fact, the stored-query approach used here significantly improves security and allows developers to separate sensitive query code from the web designer working with SSP.
SSP/3.0 vs. Other Template Languages With the wide variety of existing template languages, one must ask why yet another language should be created. SSP provides a set of language primitives tailored to support the Scalara web service architecture, and this makes it as integral a component of the overall architecture as any other server or component. Its tailored command set, while more limited than other choices such as embedded Python or PHP interpreters, serves the architecture well by removing functionality that often leads to security vulnerabilities or performance issues, pushing the focus of application development to the server instead of the scripted front-end. SSP also simplifies the work of the web designer or web applications developer, by providing language syntax similar to other languages with which he/she may be familiar. In fact, with its history since 1995 largely paralleling the development of many of these other template languages, SSP is very much a best-practices implementation that blends many other language conventions and routes around some of their limitations or confusions. The basic SSP tag syntax, for example, has survived from the earliest 1995 JTEK WebPlus incarnations, and as such, looks very similar to the tag syntax used by other languages from that era, such as Allaire ColdFusion. However, where ColdFusion uses a set of <CFIF>, <CFSET>, etc. tags which include the command in the initial tag, SSP instead uses a more generic <ssp if>, <ssp set>, etc. syntax for developer clarity. The difference may seem trivial to more advanced C++ developers for whom all template languages are generally the same, but in the world of scripted web development, the difference between these two formats is significant in improving the readability of the language. Both ColdFusion and other template engines like Velocity use the # symbol frequently in its syntax, often creating confusion with HTML's own frequent use of the same character. (ColdFusion has historically been particularly bad about this, requiring developers to use additional CFOUTPUT tags to wrap content that will be parsed to avoid internal confusions about mixed characters. Even Velocity's inline command syntax, interspersed with content, is less readable than clearly separated <ssp> tags. Meanwhile, SSP's simple __variable1__ substitution provides a great alternative to the overkill approach of PHP's... <?php echo $variable1 ?> As a display language supporting C++ modules, SSP specifically diverges from the common PHP/JSP/ASP/etc. practice of putting significant business logic in the templates. Especially in the case of JSP, such code easily mixes with intended output content to create a messy and unmanageable template set with long-term maintenance consequences. With SSP, the real work is accomplished in server modules, and templates are cleanly structured to aid web developers in both initial creation and on-going maintenance. (The Sirius 3.0 editor also simplifies SSP development significantly compared to standard IDEs.) SSP follows a Model-View-Controller (MVC) paradigm similar to that used by Velocity, where templates really only view the data already available within a program. Even then, there are important distinctions. Velocity forces template developers to call Java objects, and doesn't make it obvious where a particular object came from. That is, object calls are interspersed equivalently with template language calls, requiring web designers and application developers to coordinate carefully beforehand, defining objects and object methods, ie. myCalendar.showDaily(). SSP instead lets the web designer spec out a template showing application developers exactly what is needed, making obvious in the template what functionality is required, ie. <ssp ra_exec name="DailyCalendar"> (Note that when the template exists prior to development of the server modules, SSP supports use of canned data to simulate server functionality, further helping web developers design applications which can then be coded by more advanced application developers based on emulated functionality. The Sirius 3.0 editor's tabbed view, in fact, allows real-time editing of Dictionary values in one pane while viewing the rendered file in the other, allowing web developers to build full web user interfaces long before any server development has begun.) While perhaps not obvious, this specificity is a key feature of SSP, allowing for more consistent support of SOAP-based Web Services beyond the local network architecture, as opposed to the in-line Java syntax of Velocity. Put even more simply, Velocity is a language for Java developers to view their program's output, while SSP is a web developer's language for viewing server content, both on the local web server and elsewhere in the Web-Services-connected world. SSP further supports web developer site management by supporting standard methodologies like the Fusebox approach commonly used to improve the readability and maintenance of ColdFusion, PHP, and JSP templates. (See the section Using SSP/3.0 with the Fusebox Methodology for more information about this.) But beyond all of these niceties, the real advantage of SSP/3.0 is its wide variety of page output formats. Through these special output types, SSP templates can be used not only to generate web content, but also to write static HTML files, to generate dynamic emails, and to send debugging information directly to the Sirius IDE. All in all, the SSP/3.0 output types blow the socks off every other typical "web" server on the market today, and provide a great example of how SSP's focus on a specialized niche provides its target audience with amazing capabilities not easily supported in other more generalized template languages.
The Scalara 3.x Web Service Architecture More than just a set of independent software components, the Scalara servers collectively comprise a web service architecture philosophy representing the best practices of security, scalability, and capability from our work with high-end sites in the financial services and entertainment arenas. With such an approach, even the smallest of details fits into a more significant big-picture view. PHP, for example, provides direct database access through its own QUERY syntax. However, in secure environments where literally dozens of firewalls may exist between the webserver and the database server, such direct access is a deal breaker. Instead, SSP provides for a limited set of server-stored queries, allowing peaceful co-existence with existing firewalls and network security policies. With the 3.x series, the interactions between these products have become even more carefully scripted, and in some ways, have been redefined to more closely match functional roles of various developers. For example, web designers and script-based web developers will work with the Sirius 3.0 editor and its SSP/3.0 template syntax at the content level, while more advanced application developers will use C++ and the sirius-core library to build server modules to do the real work of the web service. (For more information about Ra 3.x server modules, see the Ra 3.x Module Developer's Guide.) From the network workflow view, Web Service requests (in HTML, XML-RPC, or SOAP/1.1 protocols) are received at the Osiris 3.x server, a high-performance webserver supporting thousands of concurrent connections. Unlike the more-generalized Osiris 2.x, which supported HTML, SHTML, SCL templates, and CGI applications, Osiris 3.x is now streamlined to support only simple HTML pages and SSC modules. SSC modules, auto-compiled from SSP templates by the Ra server, provide a significant performance improvement over typical template-parsing approaches. All SSC modules and HTML pages must then be pre-registered with the Osiris 3.x engine before use.
As noted in the architecture diagram above, the Sirius 3.0 IDE provides a an internal httpd server for use in testing web applications during development. So, with a template open in the Sirius editor, a developer can direct any standard web browser to the local machine as well, where the template will be rendered just as it would be in production. This embedded staging server significantly reduces template development time and avoids the overhead of having to setup and manage a separate webserver solely for template development.
The SSP/3.0 "Page" Paradigm While all previous Scalara template parsers used a file-based paradigm much like HTML itself, SSP/3.0 diverges from tradition to instead use a new "Page" paradigm for greater flexibility and control. In a file-based paradigm, a template named "test" would be stored in a file named "test.scl" and would be invoked with a single run through the parser object. The contents of the file, typically a series of SCL tags, would be executed sequentially in standard procedural style, and the resulting output, interspersed with HTML or plain text output, would constitute the resulting string delivered to the client (usually a web browser). SSP instead uses a "Page" paradigm, in which program blocks are pre-defined within a single file or across multiple files. So, for example, while the previous "test.scl" would include a single large string of HTML content and SCL tags, an equivalent "test.ssp" file may include several program blocks (called "pages") separating the HTML content in some way meaningful to the SSP developer.
<ssp page name="welcome" content="text/html"> Welcome to the Scalara SSP/3.0 example page, __web.user__.<p> This page was created to introduce you to SSP/3.0 programming, and provides information to help you get started.<p> </ssp> <ssp page name="closing" content="text/html"> Copyright © 2003, Scalara Technologies Ltd.<br> For help, <a href="mailto:info@scalara.com">email us</a>.<br> <br> </ssp> Pages can then include other pages with the simple INCLUDE tag, allowing for clean separation of content and layout-formatting within the same file.
<ssp page name="main_layout" content="text/html"> <html> <head> <title>Some WebPage Title</title> </head> <body> <ssp include page="welcome"> <hr noshade size="1"> <ssp include page="closing"> </body> </html> </ssp> In addition to the pre-defined pages, each SSP/3.0 page requires at least one EXEC page which provides commands which are directly executed at the root level. Such a page typically only includes top-level calls to pull together the other pages required to output a full page. The following example shows one way this could be accomplished, though we'll see an even cleaner approach in the In-line Commands section.
<ssp exec content="text/html"> <ssp include page="main_layout"> </ssp> Since this EXEC page will pull in the "main_layout" page, which in turn will pull in the "welcome" and "closing" pages as needed, it becomes possible to cleanly organize blocks of content within a single file without requiring multiple files. The biggest benefit of the new "Page" paradigm is seen in plain-text contexts where spacing is significant, such as in server-generated emails with database content. Because SCL/2.0 only allowed for full "files" of content, an email template might include query tags which incorrectly resulted in extra space or new-line characters at the top of the email template. And unlike HTML where such extra spaces or new-lines would simply be ignored, the plain-text nature of email meant that a file with extra new-lines at the top breaks the RFC-822 formatting requirements for an email message. SSP/3.0 avoids that issue entirely by separating content into executable blocks where exact spacing can be more easily preserved. (Also see the important new "execute" command in the next section for an example of plain-text email rendering.)
Page Actions in SSP/3.0 While the organization of SSP content into sub-pages allows for a great deal of flexibility, the real power of this approach is achieved through a set of "page actions" which can be defined for each <ssp> page. These actions greatly exceed the standard "web output" of most template language, allowing the server to write content to files, email content elsewhere, and perform other actions that significantly increase the functionality of the system. The following page output modes are currently supported in SSP/3.0: 1. Web interface output. This is the default output mode for all requests received over the HTML interface in Osiris. It automatically outputs a "Content-type: text/html" type header for all pages defined with a valid MIME type, and automatically generates Cookie headers if any content is found in a magic Global.Cookies DataTable. Also, if the variable Global.Redirect is set, Osiris will output a proper Location: redirect for that URL instead of outputting any display content. 2. Direct output. This mode outputs content directly with no support for website cookies or redirects. This mode is typically only used for custom interfaces, such as creating a time server that returns the current time upon telnet to a certain port, or returning the results of a filesystem 'df' query upon connect. This mode is used, for example, in defining a series of monitoring system checks called from Perl scripts which don't support http request headers. 3. XMessage. This output type hooks into the XMessage communications channel within the sirius-core library, allowing output directly to any supported XMessage peer. This could be used to send status messages to a Scalara server, to send debugging output to a Sirius 3.0 IDE, or even, theoretically, to relay through a valid XMessage server to send IM messages to any connected IM user. The possibilities here are truly mind-boggling. 4. File. File output, while a simple concept, also provides a variety of interesting uses. For example, a coordinated use of this output type can easily create a viable solution for developing and managing large static-html sites with the convenience of templates. Many developers welcomed the use of HTML frames to re-use content (such as a site header) without copying the HTML text to every single website page. However, because of the unwieldy implementation of frames and its subsequent demise over the past five years, today's sites need a finer-grained method for defining content pages which can ultimately appear seamlessly within single HTML pages. SSP/3.0 serves this role simply and perfectly. To create a static site using the 'file' output type, the SSP developer would define a set of <ssp> pages containing the various content blocks that might normally be defined in HTML frames. So, a page "header_content" might be defined to contain the top part that appears on every page of the site, while page "side_menu" might define the site's menu that appears along the left-hand side. Then, simply create a master site.ssp to pull these content pages together... <ssp> execute page="main_page"; execute page="page_2"; execute page="page_3"; </ssp> <ssp comment "now define the static pages..."> <ssp page name="main_page" content="text/html" output="file" filename="index.html"> <ssp include page="header_content"> Main index.html content here!<p> </ssp> <ssp page name="page_2" content="text/html" output="file" filename="second.html"> <ssp include page="header_content"> Secondary page content here!<p> </ssp> [... etc...] <ssp comment "now define the content blocks..."> <ssp page name="header_content" content="text/html"> <html><body> <font size="5">Your Company Name</font> </ssp> [... etc...] When the parser runs through the site.ssp main page, it will of course execute the <ssp> exec page directives. Each of those directives executes a page which defines the content of a single static html file, the output filename of which is defined in the <ssp page> tag. So, each page is sequentially run, which in turn includes the content blocks like "header_content" as necessary, and builds each page before outputting each to its own HTML file. The result? A set of HTML files containing the content of your site, and a set of SSP templates allowing easy on-going maintenance. Imagine changes applied to literally hundreds of HTML pages with a simple change to a single "header_content" page and a single re-parse of site.ssp. 5. Email. Although email could technically be sent by relaying an XMessage through a messaging server (such as Scalara Hobnob), there are many cases when a simple SMTP mail message could be sent without the full XMessage overhead. For those cases, the 'email' output type will simply email the page content out through the mail host pre-defined in the Osiris server's configuration. While the possibilities with these output types are vast, a simple example shows how easily an SSP developer can create a report with online content, email content, and an email notification. In a single SSP file called "report.ssp," let's create three page blocks. The first will be an HTML content block that will be displayed in a browser. <ssp page name="web_content" content="text/html"> <html><body> Here is your report data...<p> <table> <ssp foreach $row (report_data)> __row[0]__ : __row[1]__ <br> </ssp> </table> </body></html> </ssp> The second will be a plain-text representation of the same report data, which we will email to the user for their own records. Note that the output type is set to "email" and the email address is pulled from a variable, which could be set in any number of ways. Typically, this value would be pulled from the database. <ssp page name="email_content" content="text/plain" output="email" email_address=$EmailAddress> From: Reporting System <reports@yourdomain.com> To: __UserName__ <__UserEmail__> Date: __Global.TIME__ Subject: Your requested report Here is your report data... <ssp foreach $row (report_data)> __row[0]__ : __row[1]__ </ssp> </ssp> Finally, let's create an email notification that is sent to the Reporting System manager, alerting them that a requested report was generated. <ssp page name="email_notify" content="text/plain" output="email" email_address="reports@yourdomain.com"> From: Reporting System <reports@yourdomain.com> To: Alerts <reports@yourdomain.com> Date: __Global.TIME__ Subject: ALERT: Report request completed A report was generated for __UserName__ at __Global.TIME__. </ssp> With these three pages defined, all that remains is a simple page to pull them all together when the user requests this page from a browser. Note that this also calls a pre-defined query "get_data" that retrieves the correct data for the sample report. <ssp> query name="report_data" select="get_data" datasource="test_db"; include page="web_content"; execute page="email_content"; execute page="email_notify"; </ssp> That's it. With four simple content blocks, we're able to string together a series of actions in a far more powerful way than most other template languages would support. Even further, with a little additional work, this example could easily be extended to email the report only if there were no errors during processing, and to instead email the broken report along with a full DATAVIEW showing what went wrong to the report developer in the event of any run-time issues. Or, do the DATAVIEW one better and send it directly to the Sirius IDE. This is one of the most powerful features envisioned for web development, allowing real-time production templates to send debugging output to a connected IDE for further examination. By viewing real customer data with the reported error messages, debugging problematic apps becomes trivial. And best of all, the entire feature is enabled with just three lines... <ssp page name="debug" content="Dictionary" output="XMessage" send_address="developer@workstation.yourdomain.com"> dataview mode="Dictionary"; </ssp> Of course, there are significant security issues with running this over insecure networks (including the Internet). But for carefully managed networks with proper firewalls and VPNs, especially during the development and initial Quality Assurances stages, XMessaging the DATAVIEW to an IDE represents one of the cleanest development approaches around.
The SSP/3.0 In-line Command Syntax One of SSP's most significant changes from its SCL predecessor is the inclusion of a new in-line command syntax to complement the traditional tag syntax. As you can see in the previous examples, the SSP tag syntax provides an INCLUDE call within the <ssp ... > format resembling traditional HTML tags. However, with SSP/3.0, the same INCLUDE could also be represented as a single-line command:
include page="main_layout"; In fact, a series of these commands can be issued in sequence to create more readable blocks of programming than could be achieved with tags.
set $variable = "some string"; eval $another_var = "Welcome, __web.user__."; query datasource="test_db" q="test_query"; With SSP/3.0, this in-line command syntax is now possible through use of the "Page" paradigm. In the last section's examples, each page definition included a content tag set to "text/html" to denote HTML content. However, the content type can be any valid MIME type, including "text/html" and "text/plain," as well as "SSP/3.0" to define a page of in-line SSP commands. In fact, SSP/3.0 is the default value for a page block where no content type is defined. Also note that a simple <ssp> ... </ssp> tag block applies a default EXEC and a default content type of "SSP/3.0", creating a valid EXEC page with SSP/3.0 in-line command content. The following block is therefore equivalent to (and preferred to) the INCLUDE-tag example at the end of the last section...
<ssp> include page="main_layout"; </ssp> The following in-line commands are supported in SSP/3.0: 1. COMMENTS. Comments are defined with a # character, as they are in Perl or in other shell scripting syntaxes.
# comments are defined with a '#' character and # must exist on their own lines with no other tags
Also note the Python-style operation of $var2, where a string multiplied by a number will result in a string that consists of the original string repeated that many times. In this case, $var2 would be "----------".
set $var = "asdf";
set $var2 = ("-" * 10);
set $var3 = ($var . '\n' . $var2 . '\n');
define "magic_value" "setting"; [A full list of magic values should be defined here.]
eval $var; In the second example, EVAL evaluates the provided string, expanding it into its resulting string and setting that string equal to the provided variable, in this case $var.
eval $var = "hello __user__...";
If the conditional clause consists of a single line, it can be indented below the IF statement without use of braces. Multi-line conditional clauses must use braces to surround the clause, and blank lines within the braces are not considered for the ending blank line of the IF statement.
if ( $var eq $asdf ) :
{
set $var = ($asdf . $asdf);
set $var2 = ( "-" * 40 );
}
elsif ( $var == 1 ) :
{
set $var = ($asdf . $asdf);
# you can nest conditionals
if ( $var == 1 ) :
echo "still 1!";
else
echo "now changed";
}
else :
set $var = "wtf";
(By the way, note the equivalent echo statements below using either strings with variable substitution or command-line variables.)
foreach $row (table) :
{
echo "__row(0)__";
echo $row(0);
echo "__row('name')__";
echo $row('name');
}
foreach $item #list :
echo $item . '\n';
switch ( $var ) :
{
case "asdf" :
set $status = "just as we expected";
case "asdf2" :
set $status = "a little more complicated";
set $secondary = "something else here";
case "asdf3" :
set $status = "downright ambitious";
default :
set $status = "wtf";
}
include page="main_layout"; In this usage, when the program reaches this INCLUDE, the program will branch to the pre-defined page "main_layout" and will include it in the current page's output. The EXECUTE command offers the same functionality without including any output from the called page in the output of the calling page. This is particularly useful for defining queries, such as might be used in a plain-text email message. The queries could be defined on a page "several_queries" while the email text itself, including variable substitutions using the queried content, might exist in page "message"...
<ssp> execute page="several_queries"; include page="message"; </ssp> The second usage of INCLUDE is to pull another physical file into the current file for processing. This usage was far more common in previous SCL/2.0 templates, which used separate files in lieu of SSP "pages", but remains a powerful feature for linking together groups of code pages in an organized fashion. In fact, because of the way pages are defined before execution, it is possible to build "libraries" of pages stored in a single physical file, even if only a single page from the "library" file may be needed in the current template. So, for example, imagine a Calendar file defining several different views (each in a separate <ssp> page). Then, a main SSP template could be created to take a user-input date and render just the daily view...
<ssp> include filename="calendar_lib.ssp" path="/path/to/file"; set $date = $web.today; include page="daily_view" date=$date; </ssp> (Note that EXECUTE is identical to INCLUDE when called on a file. One might imagine that it would operate differently, without including content, for example. But upon further consideration, note that any PAGEs defined in the called file won't be included anyway unless specifically called, and any EXEC pages would be exec'd anyway. So, if you don't want content from the called page to appear in the original template, simply set the EXEC page of the called file to be a series of "execute page" calls, which will run the defined pages without any resulting content.)
query name="myQuery" select="saved_query";
ra_exec name="myCalendar" date="2003-04-12" view="daily";
The SSP/3.0 Tag Syntax Although the new In-line Command Syntax allows for much clearer syntax in some places, there are still many places where the traditional tag syntax is required. As a general rule, the tag syntax should be used whenever calls will be embedded in traditional content, such as in HTML text. There are also a few commands which only exist in tag syntax, as noted in the following list of SSP/3.0 tags: 1. SET. The SET tag follows the same syntax as the in-line SET command.
<ssp set $var = "asdf">
<ssp define "magic_value" "setting">
<ssp eval $var> <ssp eval $var = "Hello __user__!">
<ssp full_eval $queryString> SELECT * FROM account WHERE user_id = __userID__ AND name = __userName__ AND status = 1 </ssp>
<ssp comment "This is a sample comment."> <ssp full_comment> This is another sample comment. The full_comment allows much more flexibility in defining comments, and have no use beyond visibility to the SSP developer. They're also handy for wrapping blocks of HTML text that you want to exclude, since they can wrap full HTML tags better than <!-- comment -->. </ssp>
<ssp if ( $var eq "hello" ) > <tr><td> __var__ </td></tr> </ssp>
<ssp foreach $row (table)> __row(1)__ : __row(2)__ </ssp> <ssp foreach $item #list> __item__ </ssp>
<ssp include page="main_layout"> <ssp execute page="several_queries"> <ssp include filename="some_file.ssp" path="/path/to/file">
<ssp query name="myQuery" exec="saved_query">
<ssp full_query name="myQuery2" datasource="test_db"> SELECT * FROM account WHERE user_id = __userID__ AND name = __userName__ AND status = 1 </ssp> Special Note: The Security Implications of FULL_QUERY For those curious about these dire warnings, the general rule against FULL_QUERY use in production environments is a result of the security implications of these two tags being wildly different. Although only SELECT calls are shown in our examples, SQL allows INSERTS, UPDATES, and DELETES which materially affect the back-end database. If your webserver has the FULL_QUERY privilege enabled, someone with access to your webserver can execute any random commands they wish against the back-end server. This type of activity is seriously restricted and often completely prohibited in production environments, especially in security-conscious environments like those performing financial services activities. With the QUERY command, even a malicious intruder on your webserver cannot execute any destructive commands (like "DELETE FROM table") that are not pre-defined as stored server queries. This note should also include a secondary warning to give careful consideration to the types of queries which you deem fit for "stored query" status. It may seem convenient, for example, to define a generic "UPDATE __row__" type query which pushes significant power to the template, and the server administrator may well welcome such convenience as it reduces the overhead of supporting SSP developers. But in the long run, this only serves to circumvent the intentional security of the SSP paradigm. If you really want more flexibility at the cost of reduced security, just use PHP! :-)
<ssp ra_exec name="myCalendar" date="2003-04-12" view="daily">
Using SSP/3.0 with the Fusebox Methodology Fusebox enthusiasts will be happy to learn that SSP/3.0 supports the Fusebox methodology far better than its SCL/2.0 predecessor did. In fact, SCL developers may recall the serious performance cautions discouraging use of the Fusebox methodology with SCL templates. With the benefit of SSP/3.0's new Server-Side Compilation (SSC) technology, though, the use of a Fusebox methodology is actually preferred for creating a single binary object containing the full application. (Without SSC, SSP would require loading and re-loading of dozens of files on each run, which inspired the cautionary notes in earlier versions.) For those unfamiliar with it, the Fusebox methodology provides a pipe-and-filter approach to web application development, aimed at increasing developer clarity and reducing the "70% software failure rate" often noted among web application developers. As the Fusebox website explains, Fusebox requests are made of the server through a central controller, often called "the Fusebox," which manages the messages passed to it. Responses are then sent to the client based on that message. Therefore, rather than requesting a file directly, such as...
http://www.mydomain.com/FrenchQueens/EatCake.ssp ... Fusebox applications instead use a central controller page (typically index.ssp), with a message representing the requested file. This message, called the "fuseaction," is sent to the module through either the URL GET syntax...
http://www.mydomain.com/index.ssp?fuseaction=Marie.EatCake ... or by sending the same "fuseaction" variable via an HTTP-POST from a previous form page. Quoting from the Fusebox website again, "Here, the central controller, called inside index.[ssp], receives the fuseaction message of 'Marie.EatCake' and in a manner irrelevant to the client determines that 'Marie.EatCake' means to serve up (pardon the pun) the file 'EatCake.[ssp]' in the 'FrenchQueens' directory." (CFM-based filenames from the Fusebox site were changed to SSP-based references in the examples here.) So, how does an SSP developer best leverage the convenience of the Fusebox methodology in SSP/3.0 applications? As you might imagine, such a scheme is made excessively simple through use of SSP pages even within the same file. The following example shows a fully-working example of an SSP/3.0 application using the Fusebox methodology, as defined in the following (single) index.ssp file:
<ssp>
if ( $web.fuseaction ) :
{
switch( $web.fuseaction )
{
case "Marie.EatCake" :
include page="Marie";
case "Anne.EatBread" :
include page="Anne";
default :
eval $ERROR = "__web.fuseaction__ is not a valid fuseaction";
include page="fuse_error";
}
}
else :
{
set $ERROR = "No 'fuseaction' found.";
include page="fuse_error";
}
</ssp>
<ssp page name="Marie" content="text/html">
<html><body>
This is a page for Marie Antoinette.
</body></html>
</ssp>
<ssp page name="Anne" content="text/html">
<html><body>
This is a page for Queen Anne.
</body></html>
</ssp>
<ssp page name="fuse_error" content="text/html">
<html><body>
An error has occurred: __ERROR__
</body></html>
</ssp>
As the above code shows, if the "fuseaction" is set to "Marie.EatCake", the page "Marie" is displayed in the browser, while the page "Anne" is instead displayed if the fuseaction is "Anne.EatBread". In fact, readability and on-going maintenance could be simplified even further by isolating the HTML opening and closing tags into "header" and "footer" pages of their own, allowing for global site changes within a single content page. And keep in mind, while this example shows the convenience of fuseactions within a single file, the traditional behavior of including files based on different fuseactions continues to work as well, allowing for even cleaner management of related functions in grouped files. When this SSP file is completed and uploaded to the server for live/production use, the server will invoke its SSC compiler to build a binary object from this file. All content and conditional logic defined here will be transformed into compiled directives, creating a binary module that executes even faster than traditional compiled C++ CGI applications. With such a convenient process, the SSP developer benefits from the Fusebox methodology without paying a significant performance cost for its use.
|