Manual

Next chapter: Extending Scripturian
Or, go back to the manual's table of contents

Part 5: Text-with-scriptlets Documents

A common use case for adding language engines on the JVM is dynamic generation of textual formats: as HTML pages, XML, JSON and many others. Dynamic languages offer many advantages over Java for this use case. The code is often simpler that Java; these engines offer on-the-fly compilation or interpretation making the development process much easier; and more languages means allowing access to a wider range of programmers and even to web designers.

With this use case in mind, Scripturian has been designed from the ground up to support text generation. However, note that if you do not need this feature, it comes at no cost to you. "Text-with-scriptlets" is simply an alternate way of parsing and composing executables: once created, they are identical to any other executable.

Parsing

To get Scripturian to treat your document as text-with-scriptlets, simply set the flag to true when creating it:

DocumentDescriptor documentDescriptor = Executable.createOnce( documentName, true, parsingContext );

And, that's it. You can execute or enter the executable exactly as you learned earlier in the tutorial. The only difference is in how the executable was parsed.

Parsing

The document is parsed very differently than usual: rather than source code for a specific programming language, such as a ".js" or ".py" file, the document is treated as a text file with source code optionally embedded in it in delimited sections called "scriptlets." For example:

The text here will go to standard output
(which of course you can redirect anywhere via setWriter in the execution context)
We will now output 10 more lines:  
<%javascript for (var i = 0; i < 10; i++) { %>
This is line <%= i %>.
<% } %>
And that's it!

A few things to note:

• Parsing happens once and only once per document. Using text-with-scriptlets causes absolutely no performance loss for execution.
• You can configure different delimiters in the parsing context (ASP and PHP style are supported by default).
• You can even create your own tags! (This will be detailed in the next tutorial section.)
• A scriptlet does not have to be a fully closed program. Above, we've separate a for-loop into two separate scriptlets, with non-delimited text in between. Simply think of the non-delimited text as "print" statements to standard output.
• When parsing text-with-scriptlets, Scripturian does not figure out which language to use depending on the document filename extensions. For example, the file above may be named "run.html". Instead, Scripturian expects you to specify the language in the tag (as in "javascript", above), or you can set a default language tag to use. Once you do specify a language tag, it is used for subsequent scriptlets unless a different tag is specified, which is why we specified "javascript" only once above.

Including Other Documents

A special scriptlet tag is used to include other documents in place:

Let's include another document!
<%javascript
for (var i = 0; i < 10; i++) {
%>
This is from another document: <%& 'line.html' %>
<% } %>
And that's it!

A few things to note:

• The other document is not simply pasted into our current document: instead, it is dynamically executed when we execute our own document and we reach that point.
• The include tag used an actual language expression. That means you can have the name of the included document determined at runtime, when the executable is executed.

The above code won't "just work." What the include tag actually does depends entirely upon your specific container environment. To allow for this to work, you must specify a special container service when you execute the document, detailed below.

The Container Service

You set up the container like so:

class MyContainer {
	public void include( String documentName ) {
		DocumentDescriptor documentDescriptor = Executable.createOnce( documentName, true, parsingContext );
		documentDescriptor.getDocument().execute( executionContext, this, null );
	}
}

Object containerService = new MyContainer();
executable.execute( new ExecutionContext(), containerService, null );

For the include scriptlet tag to work, you need only have an "include" method on your container. It's up to you, your threading requirements, application setup, etc., to determine how best to execute other documents in-place.

In fact, the include scriptlet tag simply delegates to your container service. You can also call the service directly. The following is exactly equivalent to the include scriptlet tag:

<% executable.include('line.html'); %>

You can change the name of the container service (it's "executable" by default) via setExposedExecutableName in the parsing context.

Mixing Languages

Because you specify the language to use per scriptlet, you can actually mix scriptlets of different languages into the same document! This is a very powerful Scripturian feature. It lets you, for example, mix programming languages with templating languages. Here we'll put a Velocity template next to some JavaScript code:

<%javascript for (var i = 0; i < 10; i++) { %>
This is line <%= i %>.
<% } %>
<%velocity #set($value='big hello') %>
And now: <%velocity here is a $value from Velocity %>

This 1) lets you use the best tool for the job, and 2) lets you access libraries written in different languages. For example, you data access library might be using Ruby, but you would rather write your main text generation in JavaScript. Scripturian lets you use both without forcing you to create separate documents.

The result is still a single executable: internally it is composed of multiple programs executed in sequence.

Scripturian goes one step further and lets you mix scriptlets of one language inside a program written in another languages. This is explained in further detail in the FAQ, under "in-flow tags."

Next chapter: Extending Scripturian
Or, go back to the manual's table of contents