XMod Pro Documentation

Appearance

<xmod:ScriptBlock> ​

<xmod:ScriptBlock> registers a JavaScript or CSS 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 views without rendering twice when RegisterOnce="True".

The actual <script> (or <style>) tag goes between the opening and closing <xmod:ScriptBlock> tags.

Example ​

html
<div>
  <xmod:ScriptBlock ScriptId="AlertScripts" RegisterOnce="True" BlockType="StartupScript">
    <script>
      function helloWorld() {
        alert('Hello World');
      }
      function goodbyeWorld() {
        alert('Goodbye Cruel World');
      }
      function showMessage(sMessage) {
        alert(sMessage);
      }
    </script>
  </xmod:ScriptBlock>

  <xmod:ScriptBlock ScriptId="MyStyling" RegisterOnce="True" BlockType="HeadScript">
    <style>
      table td a { color: red; }
    </style>
  </xmod:ScriptBlock>

  <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>
</div>

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 <xmod:ScriptBlock>, another module, or DNN itself) and skips this block if so. Choose names specific enough to avoid collisions — "AcmeXmpViewHelpers" 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 view (or several views sharing a helper) might be rendered more than once on a single page. RegisterOnce applies to ClientScript, StartupScript, and ClientScriptInclude.

  • 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
    <xmod:ScriptBlock ScriptId="AcmeUtils"
                  BlockType="ClientScriptInclude"
                  Url="~/scripts/acme-utils.js"
                  RegisterOnce="True" />

  • If: A simple equality expression evaluated when the view 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
    <xmod:ScriptBlock ScriptId="DebugHelpers" If="[[User:IsHost]] = True">
  <script>console.log('XMP debug helpers loaded');</script>
</xmod:ScriptBlock>