XMod Pro Documentation

Appearance

<ScriptBlock> ​

<ScriptBlock> registers a JavaScript block (or an external script file) with the hosting page so it ends up in the head, body-top, or body-bottom of the rendered HTML. The block is identified by ScriptId, which lets the same script appear in multiple forms or templates without rendering twice when RegisterOnce="True".

The actual <script> tag goes between the opening and closing <ScriptBlock> tags — wrap it in a CDATA section if your script contains characters that confuse the XML parser.

Example ​

html
<AddForm>
  <ScriptBlock ScriptId="AlertScripts" RegisterOnce="True">
    <script type="text/javascript">
      function helloWorld() {
        alert('Hello World');
      }
      function goodbyeWorld() {
        alert('Goodbye Cruel World');
      }
      function showMessage(sMessage) {
        alert(sMessage);
      }
    </script>
  </ScriptBlock>
  <table>
    <tr>
      <td>
        <a href="#" onclick="helloWorld();">Hello World</a><br />
        <a href="#" onclick="goodbyeWorld();">Goodbye</a><br />
        <a href="#" onclick="showMessage('Hello and Goodbye');">Show Message</a>
      </td>
    </tr>
  </table>
</AddForm>

Properties ​

PropertyValuesDefaultDescription
ScriptId *stringUnique identifier used to deduplicate the script across the page
BlockTypeClientScript StartupScript HeadScript ClientScriptIncludeClientScriptWhere in the page the script is rendered
RegisterOnceTrue FalseFalseWhen True, skip registration if the same ScriptId is already on the page
UrlURLUsed only with BlockType="ClientScriptInclude" — the path to the external .js file
IfexpressionWhen set and the expression is false, the script is not registered (since v5.0)

* Required property

Property Details ​

  • ScriptId: A page-wide unique identifier. When RegisterOnce="True", XMP checks whether a script with this ID has already been registered (by another <ScriptBlock>, another module, or DNN itself) and skips this block if so. Choose names specific enough to avoid collisions — "AcmeXmpFormHelpers" is safer than "helpers".

  • BlockType: Where the script lands in the rendered HTML.

    ValueLocation
    ClientScript (default)Near the top of the page body
    StartupScriptNear the bottom of the page body — runs after most of the DOM is in place
    HeadScriptInside the page's <head>
    ClientScriptIncludeRenders a <script src="..."> reference to the file at Url

  • RegisterOnce: When True, the script is registered only if no other script with the same ScriptId is already on the page. Use this when the same form (or several forms sharing a helper) might be rendered more than once on a single page. RegisterOnce applies to ClientScript, StartupScript, and ClientScriptInclude block types.

  • Url: When BlockType="ClientScriptInclude", the path to the external .js file. Tilde (~) is supported for site-root-relative paths. Ignored for other block types.

    html
    <ScriptBlock ScriptId="AcmeUtils"
             BlockType="ClientScriptInclude"
             Url="~/scripts/acme-utils.js"
             RegisterOnce="True" />

  • If: A simple equality expression evaluated when the form renders. When the expression is false (or resolves to false or 0), the script is not registered. When the property is omitted, the script is always registered (the v4.x behavior). Use = for equality and <> for inequality.

    html
    <ScriptBlock ScriptId="DebugHelpers" If="[[User:IsHost]] = True">
  <script>console.log('XMP debug helpers loaded');</script>
</ScriptBlock>