Episerver Script Block

Deane Barker edited this page Jun 8, 2018 · 4 revisions

Denina script can be executed inside of an EPiServer installation by means of the Text Include Block. This block is available via Nuget (it bundles DeninaSharp as a dependency):

PM> Install-Package EPiServerDeninaBlock

The block provides the following functionality:

  • Two new commands for acquiring text: EPiServer.ReadLocalMedia and EPiServer.ReadParentMedia for reading the contents of files attached to the block, or to the page on which the block is embedded, respectively.
  • A property for CSS which is injected and scoped to the block container (browser support is thin; see HTML Style Scoped Attribute)
  • A property for extended template code (or any other use, really), the contents of which are provided to the script via a $__template variable value.
  • The ability to cache the results for a period of X minutes. This cache is invalidated whenever any of the properties of the block change.
  • The ability to control error handling. Exceptions can thrown, suppressed, written to HTML comments, replaced with provided text, etc.

Screencap

Below is a screencap of the block editing interface, populated with a sample script. All fields are explained under the screencap.

Commands
The Denina script itself. The output of the final command will be output to the page.

Template
An optional editing area for template content -- or, really, any content. The contents of this textbox are simply injected into the pipeline as a variable called $__template (that's with two underscores). It's often easier to put template-ish code here than inline as an argument parameter (as depicted in the screencap above).

Scoped CSS
CSS to be injected into a STYLE element in the HEAD of the page via Episerver's ClientResources framework. (TODO: this should be renamed "Supporting CSS." It was previously injected via a scoped CSS element, but that has been removed from the spec and is no longer supported.)

Error Content
The content to display if Display Error Content is selected from the "Error Behavior" dropdown. (TODO: this should be moved below "Error Behavior" in the interface.)

Error Behavior
What to do if the script throws an exception. The options are:

  1. Display Error Content: Displays the content from the "Error Content" editor.
  2. Hide Block: Suppresses the exception and displays nothing.
  3. Throw Exception: Throws the exception raw. Recommended only for testing or development.
  4. Output Debug Info: Outputs all ExecutionLog entries as HTML (see Debug Data).
  5. Output Hidden Error Message: Suppresses, hides the block, and outputs the e.Message string as an HTML comment.

Cache Timeout
Number of minutes to cache the output of the block. The key is a hash of:

  1. The block ID
  2. The cache timeout
  3. The script commands
  4. The template value

If any of those values change, this will change the cache key and effectively invalidate the cache.

Video

The image below links to a two-minute, narrated video of how to use the Episerver block to embed an RSS feed. (Yes, it's a link not an embedded player. GitHub does not allow embedded players.)

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.