sampjs

sampjs is a small JavaScript library for using the SAMP Web Profile from within web pages. The project is hosted on github at http://github.com/astrojs/sampjs/.

What is SAMP?

SAMP is the Simple Application Messaging Protocol, a platform- and language-neutral protocol used for communicating between applications. It was developed within the IVOA for use with astronomy tools, but the protocol is not specific to astronomy. See the SAMP Standard and additional material.

SAMP is defined in layers, and the Profile layer defines how tools perform the actual communications. Two profiles are currently defined: the Standard Profile, which is suitable for desktop clients, and the Web Profile, which is suitable for web clients running within a browser sandbox. The Web Profile is defined as part of version 1.3 of SAMP; see Section 5 of the standard for the details.

For a view of what the protocol looks like in action at the byte level you can see an HTTP log of a short example session (generated using "-web:log http" option of the JSAMP hub).

A talk on SAMP and the Web Profile was presented at ADASS XXI (Paris, 2011). This will be published as M.B.Taylor, T.Boch, J.Fay, M.Fitzpatrick and L.Paioro, "SAMP: Application Messaging for Desktop and Web Applications", ASP Conf. Ser. 461, ADASS XXI, ed. Pascal Ballester, 279 (2012ASPC..461..279T.). You can see the submitted paper or presentation.

What is it good for?

Putting these things together allows you to write a web page which can communicate with other desktop applications running on the same machine as the browser displaying it (or even with other unrelated web pages in the same browser). A simple example is a web page with a button you can click to send an image or table (perhaps generated dynamically by the server) to a desktop image or table viewer application. But more complicated scenarios, including two-way communication, are possible too.

The technical details of how that can happen and the associated security implications are discussed in exhaustive detail in the SAMP standard reference above.

All SAMP communications (Standard and Web) are via a Hub, a daemon process that brokers messages between clients. So for SAMP tools to be able to communicate, a Hub must be running. For web clients, this must be a Web Profile-capable hub, which currently means either JSAMP version >=1.3-1 (Java) or SAMPy version >=1.2.1 (Python). There are (at least?) three ways to make this happen:

• Some SAMP-aware applications, such as TOPCAT and Aladin, start a hub automatically when they start up, if one is not already present.
• You can download and run a JSAMP or SAMPy hub
• You can use Java WebStart to start a JSAMP hub by just clicking here: start hub.

How can I write a SAMP-capable web page?

Use the samp.js library and write your own code around it. You can write a minimal SAMP application (often, all that is required) with very little work. Usually you will start by importing samp.js (and flXHR.js? see the section on flXHR):

   <script src="samp.js"/>
   <script src="flXHR.js"/>

You can either supply a full path to the js libs or copy them into the same directory as the web page.

Alternatively, you can include sampjs in your project with npm. Install it with

    npm install sampjs

Then import it into your scripts with

    import { samp } from "sampjs";

If you want a more compact version of the samp javascript, you can use a minifying tool. One possibility is Google's closure-compiler. Here is an example invocation using curl:

   curl -dcompilation_level=SIMPLE_OPTIMIZATIONS \
        -doutput_format=text \
        -doutput_info=compiled_code \
        --data-urlencode js_code@/foo/bar/samp.js \
        http://closure-compiler.appspot.com/compile

• Pinger: really really minimal SAMP web page
• Sender: very simple script to send a table
• Navigator: steers (e.g.) Aladin all-sky view using sliders
• Link Broadcaster: sends links with only HTML broadcaster.js helper script
• Pingee: receives a ping message and then unregisters
• Client Monitor: monitors registered clients with their metadata and subscriptions
• Table Viewer: receives a table from another client and does 2-way communications

Don't forget you need to be running a hub for these to work. Running other SAMP clients will make it more interesting too - here is a WebStart link for, e.g., TOPCAT.

• VizieR search (Thomas Boch)
• Xamin from HEASARC
• GAVO Data Center
• WSA Coverage maps from ROE

Note some of these may be experimental. Feel free to add your own site if you are using sampjs.

flXHR is a clever external library for faking a JavaScript XmlHttpRequest Level 2 object by use of Flash.

The SAMP Web Profile has to play some tricks to communicate outside of the browser sandbox. By preference it uses a W3C standard called Cross-Origin Resource Sharing (CORS) to do this. However, some browsers do not support CORS, and in these cases it is (usually) possible to fall back to using a Flash-based workaround. Since Flash is installed very widely in browsers, that makes sampjs work almost everywhere (see the compatibility section).

Sampjs does not implement the Flash magic on its own, that's done by an external library called flXHR. This contains both JavaScript and Flash components. To get it working you need to put all the relevant flXHR files in the same directory as the web client page (or something like that) and import the flXHR script:

   <script src="flXHR.js"/>

flXHR is hosted at http://flxhr.flensed.com/, which now redirects to a github site; the project is no longer actively maintained, since the recommendation is to use javascript instead. You can grab the library files from there; for convenience you can find what you need on this site under in the lib/flxhr directory.

You don't need to use flXHR with samp.js, but if you don't, your SAMP client will not run in browsers which lack support for CORS (see the compatibility section). Does that matter? IE6 and Firefox 3.0 are probably pretty unusual by now, so maybe it's not worth the effort. You decide.

Please do! The sampjs project was originally contributed by Mark Taylor, but I'm not a very competent or enthusiastic JavaScript programmer (or git user), so please improve it (javascript, documentation, examples, whatever). The project is hosted on github at http://github.com/astrojs/sampjs/ If you want write privileges, let me or somebody else know. If somebody else wants to take over looking after the project, that suits me too.

Note that these documentation pages are part of the github project, on the gh-pages branch (that's the way that github hosts web pages).

There is no mailing list specifically for sampjs, but the IVOA apps-samp@ivoa.net list may be suitable, or you could try asking Mark (m.b.taylor@bristol.ac.uk).

This library was originally written by Mark Taylor as a proof of concept when defining the SAMP Web Profile; it was not intended for public use. As is the way of these things, some people used and adapted it anyway.

It was moved onto the www.astrojs.org site in October 2012.

The original work was supported by Microsoft Research, GAVO and STFC.