Hosted by Three Crickets

Scripturian
Scalable Alternative to JSR-223

Scripturian logo: kitten in shawl

FAQ

Why does Scripturian provide its own "include" facility, and why would I prefer it over that provided by the programming language?

You are absolutely free to use your programming language's facilities, which in some cases could be very powerful. Scripturian's optional facility offers you two advantages:

First, in that your container environment can work with specialized DocumentSource implementations. For example, you might have a DocumentSource that reads all its documents from a zip file. This would be great if you're using Scipturian for enabling plugins to your application, in which case a plugin could be provided via a single zip file. Internally, your plugin can be composed of many documents. Using Scripturian's include facility, you can guarantee that documents can include each other no matter how they are actually stored.

Second, Scripturian allows you to include documents which include scriptlets in other programming or templating languages. As to why you would want to do mix languages, see the FAQ below.

Why does Scripturian support mixing scriptlets in different languages in the same document?

Programming languages differ widely in performance, capabilities, and security considerations. For example, let's say you are using a very scalable and flexible language, but it does not support some higher-level programming structures, which you need. On the other hand, a higher-level language would do a poor, slow job at the kind of templating work you need. With Scripturian, you are able to have one scriptlet in a templating language, such as Velocity, and others in a higher language, such as Ruby. Scripturian lets you cleanly get the benefits of both in the same document.

What is the "in-flow" tag for?

These scriptlets are only useful in documents which contain scriptlets in more than one language, in which case the "in-flow" tag lets you insert one scriptlet "into the flow" of the other. Consider this example:

<%js if(isDebug) { %>
The debug information is:
<%:velocity
#foreach($line in $log)
	$line.date: $line.message
#end
%>
<% } %>

We are using JavaScript to do our main coding. However, we would like to use a facility in Velocity to dump our actual debug information. Without using the in-flow tag for the Velocity scriptlet, we would be getting a JavaScript syntax error. Why? Because Scripturian by necessity separates scriptlets according to languages, and executes them in order. Without the in-flow tag, it would attempt to run the first JavaScript scriptlet, then the Velocity scriptlet, and finally the last JavaScript scriptlet, as so:

First segment:

<%js if(isDebug) { %>

Second segment:

<%velocity
#foreach($line in $log)
	$line.date: $line.message
#end
%>

Third segment:

<%js } %>

As you can see, both JavaScript segments in this case are fragmentary and un-runnable.

The in-flow tag solves this problem by keeping us in the flow of JavaScript, so that we are dealing with a single JavaScript scriptlet.

How is this possible? Behind the scenes, Scripturian uses its include facility to handle in-flow scriptlets. In this case the Velocity scriptlet is extracted into an in-memory script file. The above would then be equivalent to:

<%js if(isDebug) { %>
The debug information is: <%& 'dump.fragment' %>
<% } %>

Where the 'dump.fragment' file is:

<%velocity
#foreach($line in $log)
	$line.date: $line.message
#end
%>

The in-flow tag saves you from creating separate files for such uses. Note that the entire separation process occurs only during parsing, and is generally very fast. Additionally, all scriptlets will be pre-compiled for maximum performance if you request it. Also note that parsing automatically detects cases in which you are using an "in-flow" scriptlet in the same language, and optimizes by treating the in-flow scriptlet as a regular scriptlet.