Entering a Script on a Page

Making sure the script is a script

How did I get the samples to show (like this: {{ page.path }}) without being interpreted as a script?  I simply selected the text and assigned it a style of "Plaintext" using the style menu in the editor toolbar.  There are a lot of wrappers that can be applied around the script that will inhibit interpretation by the wiki.  Generally, when you select your script in the editor, the toolbar should show Format: "Normal" and Style: <blank>.  In other words, it is like any ordinary text you enter into the editor.

Mult-line input

A DekiScript must not span multiple paragraphs.  Therefore, you cannot hit enter in the middle of a script, because that tells the WYSIWYG editor to create a new paragraph.  Instead, if you want a multi-line script, you should use shift-enter, which will simply insert a line-break (<br />), which is fine.

Styling the script output

What if we want to style the output of the script?  The script interpreter ignores any styles applied inside the double-braces; it just looks at the text.  But if the entire script is enclosed in the style, then it'll work fine.   If you want to apply styles to only parts of your script, you have some different options.  This table summarizes this operation.

Don't worry about this too much right now, but store it away in the back of your mind because one day you will need it.

When things don't work

The most common error when working in this mode is that after you save the page, you'll see your script (or parts of it) staring at you, double-braces and all, rather than the script output.  This usually suggests one of the following problems:

1. The script is in a formatted or styled block, and is not Format:"Normal", Style:<blank>.
2. You have a carriage return in there somewhere (and therefore the script spans multiple paragraphs, which doesn't work).
3. You do not have a proper matching set of {{ and }}.
4. You have some other HTML elements hidden in the script that are breaking things.  Try selecting the entire script and clicking the "Remove format" tool (looks like an eraser, to the right of the "Source" button) in the toolbar.

Applying Styles to the block

When we used double braces, we could (for instance) italicize the script's output by simply grabbing the whole script (including the braces) and applying the desired style using the WYSIWYG editor toolbar.  You can't do that here, though.  If you want to style the output of your script, your best options are:

1. Apply the styles directly inside the script, using XML literals, like this:
2. Wrap the entire script in a <div> with the desired styles:

Both of these will produce this output:

What happened to my HTML source?

Let's say you go peek at the HTML source of the first example above.  You will see this:

<pre class="script"> var title = string.toUpper(page.title);
&lt;em&gt; title &lt;/em&gt;;<br /></pre>

Note that the the < and > characters have been replaced by their respective HTML entities, &lt; and &gt;.  Is this correct, or has the system messed up my code?  In fact it is exactly correct: when you enter XML literals into a Dekiscript block, it's merely text on the wiki page.  It is the DekiScript interpreter's job, after extracting the text from the <pre class="script"> block, to correctly interpret the XML and output the appropriate HTML to the web page.

So, unless you have a good reason and/or have become very comfortable with the way this all works, don't touch your Dekiscript blocks in the HTML source editor.  It will only make you crazy.  

A last note about using the <pre> script block: if you are creating templates that use a save: command, you must use the non-pre-formatted editor (WYSIWYG or source). There currently is no recognition by MindTouch of the save: parameter inside the formatted block, and the parser will choke if you try to use it.  This paragraph probably makes no sense to you right now: go read the section on Save: and Edit: to further clarification.

Why not to do this

This coding approach is now so strongly deprecated (by me at least) that, rather than explain how to use it, we will instead focus on understanding why you don't want to use it:

1. The HTML source editor is not a fun place to code:
   • All your code is in attributes, enclosed in quotes, so you can't use double-quotes.  This results in a lot of escaping, which is annoying.
   • The editor validates your HTML whenever exiting the HTML source editor (such as when switching back to WYSIWYG or saving the page).  If your HTML is broken, the editor will do what it can to salvage the code, which usually means silently discarding it.  So you can write a bunch of code, save it, and then find that the editor discarded all of it because you inadvertantly used a " inside an attribute.  This only needs to happen to you once (and it will, trust me) to make you want to swear off this approach forever.
   • Lots of useful programming characters need to be escaped into HTML entities (<, >, & are the primary culprits).  This makes the code hard to write and read, and mistakes can sometimes have rather severe consequences.
   • Having giant chunks of code inside attributes tends to make the HTML itself very hard to read.
2. You can't see or edit the code in the WYSIWYG editor.  You might not even know it's there.  This is generally Not Good, especially when doing copy and paste operations in the WYSIWYG editor.
3. You generally end up needing to bounce back and forth between the two editors a lot, and it's just plain annoying.

Having done what we can to steer you away from this approach, we will say that you certainly can accomplish useful work this way, and there are even some advantages to it.  But for new code, avoid it if you can.

Why you might have no choice

Despite the above warnings, there are precisely one and a half good reasons to code in the HTML:

1. Old Scripts: Sometimes you have to deal with an old script that uses it, and it's too much work to convert it.  This only counts as half a reason because often (usually?) it is in fact worth the effort to convert the script to a more modern style, especially if you'll be spending any real time modifying or maintaining it.
2. Global variables:  Variables in DekiScript are local to their block, so the only way (for now) to make variables visible across an entire page (or parts of a page) are to initialize them in HTML statements that enclose the desired scope.  So, you could go into the source editor, wrap a <div> around your entire page, and then put some variable initialization inside an "init" attribute in the <div>.  Those variables will be visible to any DekiScript (entered in any manner) inside the <div>, which means anywhere on the page.  In Mindtouch 2010, this reason has been eliminated, as variables are now intrinsically global across the page.

Maintaining Sanity in HTML Statments

If you do find yourself hacking DekiScript in HTML statements in the source editor, there are some things you can do to keep sane:

• As mentioned, your code will be completely contained within double-quoted attribute values.  So be careful of your use of quotes!  Inside your code, use single-quotes only, or escaped (with a backslash) single or double-quotes.
• To minimize the chance of disaster, try this trick:
  • Whenever you are ready to switch out of the HTML source editor, first do a "select all" and copy the whole source to the clipboard (ctrl-A ctrl-C).
  • Then go back to the WYSIWYG editor and then immediately back to the source editor.
  • Check if all your code survived.  If so, you're OK to exit as desired.  If not, try to figure out what the problem was, and then recover your code simply by pasting it back from the clipboard.