Inline scripts

The following attributes are used with a HTML script-tag to embed Python:

• type: defines the mime-type the script code should map to; the following prefixes are allowed: application/, text/, and application/x-. The actual language name will be passed to the DLR hosting API, so the above example could have used application/ironpython and it would still work:

  <script type="application/python">
    window.Alert("Python inline script-tag")
  </script>
  <script type="text/python">
    window.Alert("Also a Python inline script-tag")
  </script>
  

• (Optional) defer: if this attribute is not present, its value is false. Otherwise, the value is true (even if it's explicitly set to defer="false"; this is how all modern browsers behave). If set to true the code is not run; but it can be used to evaluate later:

  <script type="application/python" defer="true" id="for_later">
    print 2 + 2
  </script>
  <script type="application/python">
    eval(document.for_later.innerHTML)
  </script>
  

External scripts

The following attributes are used with a HTML script-tag to reference Python:

• src: specify the path to a Python file. If it's a relative URI, it will be considered relative to the HTML file. The src URI is downloaded and cached in memory, building a virtual file-system of external script code. Then this file is executed in its own DLR ScriptScope, which properly isolates execution between scripts, and most closely matches what Python's import statement does.

  # foo.py
  window.Alert("Hello from a python file")
  
  <!-- foo.html -->
  <script type="application/python" src="foo.py"></script>
  

• type: specifies the mime-type of the script-tag, which is used to figure out the language; see Inline Scripts type attribute.

  Technically this is not required, as the extension of the file will be used to detect the language if type is omitted, but most browsers will then attempt to run the code with it's built-in JavaScript engine, and most likely throw a JavaScript syntax exception. So, it's recommended to always using the type attribute.

• (Optional) defer: See Inline Scripts defer attribute for symantics. If this is true, the src URI is just downloaded and cached, but is not run. This allows full control over when the script gets run, as another script can get the first shot at importing it:

  <script type="application/python" src="foo.py" defer="true"></script>
  <script type="application/python">import foo</script>
  

Execution order

Script-tags will be executed in the order they are defined, but before the start script is executed (if one is provided). All inline code is to be executed in the same scope, basically as if they all one Python file. This allow methods defined in one script-tag to be called from another:

<script type="application/python">
  window.Alert("in first script-tag")
  def foo():
    return "In Foo"
</script>
...
<script type="application/python">
  window.Alert("in second script-tag")
  window.Alert(foo())
</script>

File-system operations

Silverlight runs in a sand-box, not allowing programs access to the machine's file system, as well as forbidding native user-code from being loaded. However, IronPython's implementation abstracts file-system operations, allowing it to provide different behavior when running in Silverlight. External script tags are used to define the file system entries.

<script type="application/x-zip-compressed" src="my-archive.zip"></script>
<script type="application/python">
  import clr
  clr.AddReferenceToFile("my-archive.zip/Foo.dll")
  txt = open("my-archive.zip/foo.txt").read()
</script>

XAML

XAML markup can be embedded into a script-tag, either inline or as an external file:

<!-- inline XAML file -->
<script type="application/xml+xaml" id="inlineXAML" width="200" height="75">
  <Canvas Background="Wheat">
    <TextBlock Canvas.Left="20" FontSize="24" />
  </Canvas>
</script>

<!-- external XAML file -->
<script type="application/xml+xaml" id="externalXAML" src="foo.xaml">
</script>

The following attributes are used with a HTML script-tag to embed XAML content:

• width: the width of Silverlight control surface.

• height: the height of Silverlight control surface.

• type: should be set to application/xml+xaml (application/xaml+xml is also supported in the current sources, and will be available in the redistributable package and from dlr-latest.js in all future releases after version 20100305).

• src: URI to a XAML file. It behaves like external scripts src attribute with regard to downloading and caching. If it is not set, the XAML content is expected to be provided in the script-tag's innerText.

• id: DOM ID the generated Silverlight control will have; this is needed to tell Python code to run against a specific Silverlight control.

• (Optional) defer: By default either the external or inline XAML causes dlr.js to inject a Silverlight control, and set the RootVisual of that Silverlight instance to the XAML provided by the script-tag. However, if this is true, the Silverlight control is still injected into the DOM, but the XAML content is not set as the RootVisual of that control. If the XAML content was provided by the src attribute, then the file is still downloaded and cached. Setting the RootVisual can be done manually, however:

  <script type="application/xml+xaml" id="xamlContent" defer="true">
    <Canvas Background="Wheat">
      <TextBlock Canvas.Left="20" FontSize="24" />
    </Canvas>
  </script>
  
  <script type="application/python" class="xamlContent">
    from Microsoft.Scripting.Silverlight import DynamicApplication
    DynamicApplication.Current.LoadRootVisualFromString(document.xamlContent.innerHTML)
  </script>
  

  If you do not want to even have the control added, then you'll have to disable dlr.js's auto-adding:

  <script type="text/javascript">
    window.DLR = {autoAdd: false}
  </script>
  <script type="text/javascript" src="dlr.js"></script>
  
  <script type="application/xml+xaml" id="xamlContent" defer="true">
    <Canvas Background="Wheat">
      <TextBlock Canvas.Left="20" FontSize="24" />
    </Canvas>
  </script>
  

  Then you can add a control at any time:

  <script type="text/javascript">
    DLR.createObject({width: 200, height: 200});
  </script>
  

This is similar to the way that Silverlight 1.0 allowed XAML to be embedded.

From Python

XAML is simply a markup language for creating objects, so the same thing can be done directly from Python. Given this XAML:

<script type="application/xml+xaml" id="xamlContent">
  <Canvas Background="Wheat">
    <TextBlock Canvas.Left="20" FontSize="24" />
  </Canvas>
</script>

The equivalent in Python would be:

from System.Windows import Application
from System.Windows.Media import SolidColorBrush, Colors
from System.Windows.Controls import Canvas, TextBlock
c = Canvas(Background = SolidColorBrush(Colors.Wheat))
t = TextBlock(FontSize = 24)
c.Children.Add(t)
Canvas.SetLeft(t, 20)
Application.Curren.RootVisual = c

Multiple controls

Browsers allow for multiple object-controls to be on a single page, so you could have multiple Silverlight controls on the same page. This introduces an unexpected side-effect to having Silverlight run code inside script-tags; every Silverlight would run run every script-tag. Consider the following:

<div id="message"></div>
<script src="dlr.js"></script>
<script type="text/javascript">
  DLR.createObject({width: '100', height: '100'})
</script>
<script type="application/ruby">
  root_visual = UserControl.new
</script>

Both Silverlight controls will get their root_visual set, since the Ruby script-tag is executed twice, once for each Silverlight control. To avoid this, script-tags must be scoped to a specific Silverlight control. dlr.js instructs dlr.xap to only run "un-scoped" script-tags on the first control added to a page, and only run "scoped" script-tags with subsequent added controls. To "scope" a script-tag, the class attribute contains the same value as its corresponding Silverlight control's xamlid initParam:

<script type="text/javascript">
  DLR.createObject({xamlid: 'control1'})
</script>
<script type="application/python" class="control1">
  # will only run in the "control1" object
</script>

An un-scoped script-tag is simply a script-tag without a class attribute. These will run in a Silverlight control that does not have the "xamlid" initParam set; dlr.js does this for only the first control it injects.

If you intend to not use Silverlight graphics through script-tags, or only use them in one control, then you don't need to worry about scoping; scoping only comes into play when you have multiple controls. If you want to use Silverlight graphics, you can use this same strategy on script-tags containing XAML to make sure the proper RootVisual is set.

A script-tag having a "*" class attribute will cause it to run in every script-tag, so the first-example's behavior is still possible.

Changes to existing behavior

Though there are no major breaking changes to any existing behavior of existing applications, there needs to be some changes to existing features to make this new activation-model work properly.

Previously, the "start" initParam (entry-point/start-script to the DLR Silverlight app) is required if there is no app.* file in the XAP file. If the "start" initParam is omitted in this condition, an error would have been raised, complaining about not finding an app.* file.

This requirement is now completely relaxed; neither an app.* file or a "start" initParam is required. If no "start" script or defer=false script-tags exist on the page; then nothing runs and no error is raised. This is relaxed because a Silverlight application can be only inline XAML.

<script type="application/python">
  ...
</script>
<object ...>
  <params name="source" value="app.xap" />
  <params name="initParams" value="" /> <!-- no initParams value needed -->
</object>

Though these changes are being introduced to remove the need for Chiron, it is still a useful tool for generating XAP files on the fly. Chiron now serves files out of the "externalUrlPrefix" path if it is a relative path, so extensions can be developed locally and Chiron instantly picks them up. Also, Chiron's XAP building features will build an appropriate XAP file depending on whether you're using slvx files or not.

Interacting with markup

To make accessing the HTML and XAML easier and more like how JavaScript works, variables pointing to them are added to the scope in which script-tags are executed in.

document.a_div_id
# same as ...
document.GetElementById("a_div_id")

document.doesnotexist # None

document.a_div_id.innerHTML
# same as ...
document.a_div_id.GetProperty("innerHTML")

document.a_div_id.innerHTML = "Hi"
# same as ...
document.a_div_id.SetProperty("innerHTML", "Hi")

document.link_id['href']
# same as ...
document.link_id.GetAttribute('href')

document.link_id['href'] = 'http://foo.com'
# same as ...
document.a_div_id.SetAttribute('href', 'http://foo.com')

root_visual.Message.Text = "New Message"

load_root_visual(document.xamlContent)
# same as ...
DynamicApplication.LoadRootVisual = XamlReader.Load(document.xamlContent.innerHTML)

<a id="cm">Click Me</a>

<script type="application/python">
  def do_c(link):
    link.innerHTML = "Clicked!"
  document.cm.events.onclick += do_c
</script>

<script type="application/xml+xaml">
  ...
  <TextBox x:Name="xcm" Text="Click Me" />
  ...
</script>

<script type="application/python">
  def click(s, e):
      s.text = "Clicked!"
  root_visual.xcm.MouseLeftButtonDown += click
</script>

Debugging

Silverlight XAP file structure

With both user scripts and larger libraries outside the main XAP file, the main XAP only serves as a container for the AppManifest.xaml and any dynamic language assemblies required by the application. Silverlight 3 introduced "Transparent Silverlight Extensions", a way to package your own libraries into a .slvx (Silverlight versioned extension) file (really just zip file) which applications can depend on by referencing it from their AppManifest.xaml. Using this feature all the assemblies can be removed from the XAP file, put in a slvx file, and hosted on an internet location so other applications can depend on it. Instead of IronPython and IronRuby releases containing the assemblies built for Silverlight, they will just contain a dlr.xap file. This xap file will be shared between all applications; only advanced scenarios will need to modify the xap file. It will only containing just two files:

<Deployment
 xmlns="http://schemas.microsoft.com/client/2007/deployment"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 RuntimeVersion="3.0.40624.0"
 EntryPointAssembly="Microsoft.Scripting.Silverlight"
 EntryPointType="Microsoft.Scripting.Silverlight.DynamicApplication">
 <Deployment.ExternalParts>
   <ExtensionPart Source="http://ironpython.net/2.6/Microsoft.Scripting.slvx"/>
 </Deployment.ExternalParts>
</Deployment>

<Languages>
    <Language names="IronPython;Python;py"
              extensions=".py"
              languageContext="IronPython.Runtime.PythonContext"
              assemblies="IronPython.dll;IronPython.Modules.dll"
              external="http://ironpython.net/2.6/IronPython.slvx" />

    <Language names="IronRuby;Ruby;rb"
              extensions=".rb"
              languageContext="IronRuby.Runtime.RubyContext"
              assemblies="IronRuby.dll;IronRuby.Libraries.dll"
              external="http://ironpython.net/2.6/IronRuby.slvx" />
</Languages>

Microsoft.Scripting.Debugging

Implement a lightweight debugger in the HTML page

Event handling from markup

HTML events can be hooked both through markup and/or code (for HTML/JavaScript reference: http://www.w3.org/TR/html4/interact/scripts.html#h-18.2.3). Events can be hooked directly from HTML by providing the name of the event as an attribute on an HTML element, whose value is a string of code in the default scripting language. The code is executed when the event fires in the context of the current HTML element:

<meta http-equiv="Content-Script-Type" content="application/ruby" />
<a href="javascript:void(0)" onclick="self.innerHTML = 'Clicked!'">Click Me</a>

This is accomplished by scanning all HTML elements on the page for attributes which are valid event names (see the HTML4 reference above). For each one found, the event is hooked with a handler which evaluates the attribute's value in the default scripting language in the context of the current HTML element. Not all events will be supported, as some have already fired by the time Silverlight gets control (e.g. onload).

Events can be hooked directly from XAML by providing the name of the event as an attribute on a XAML tag, its value being the method name to use as a callback when the event fires. The method should take two arguments: the sender and the event_args:

<script type="application/xml+xaml">
  ...
  <TextBox Click="do_click" Text="Click Me" />
  ...
</script>
<script type="application/python">
  def do_click(sender, event_args):
    sender.Text = "Clicked!"
</script>

This is accomplished by scanning all XAML files embedded in script tags, parsing the XML and looking for elements with attributes matching a set of supported events (to be determined). When the event fires, the method name is looked up and called if found, otherwise raises a runtime exception indicating the method does not exist. Event hooking will not be supported in XAML files provided in the XAP or another ZIP file, since Silverlight does not have a way to enumerate zips.

jQuery-influenced selectors

Though the idea of having a jQuery-like selector API for DLR languages is attractive, it is less feasible since each language will want a different way to specify the syntax. Also, libraries in those languages may exist (eg. Ruby's Hpricot), so it'd be best to use those directly. This might be addressed in a future change, or another library, but is out of scope for this change.