PixelScript

PixelScript allows any web developer to run arbitrary scripts on their site - coding in a very familiar language - JavaScript!

This allows dynamically generated content that is rendered before it even reaches a client's computer. This results in increased perceived performance on a website, as the client does not have to wait for JavaScript to run on his own computer, and it allows search engines to see all of that nice dynamic content!

Enabling PixelScript

PixelScript is in beta, and may not be available on your website yet.

The PixelScript plugin must be enabled before it can be used. See Enabling Plugins for more information.

Usage

All PixelScript usage is centered around the PixelScriptRunner control type. To create a new PixelScriptRunner control, see Creating New Controls.

The PixelScriptRunner control can be used in one of two ways:

  • Code can be added to the Content skin of the PixelScriptRunner control. This code will be executed whenever this code has been rendered.
  • The control can be used to render any system file (such as .js or .ps files) in Pixelsilk. In this case, the [[Token]] used to render this control should contain a format parameter, of the form [[Token:SystemFileName]], for example, [[PixelScript:myScript.js]].

Scripting Reference

If you need syntax highlighting in the Content token for a PixelScriptRunner, add //<script type="text/javascript"> to the beginning of your script. This will not affect your script. This is a temporary workaround.

The main idea behind scripts is that they should do work, and then return a string containing the content that they should render. For example,

return "foo";

will render the string foo as the result of rendering the PixelScriptRunner token. Multiple returns are not allowed, obviously. If you need to output at multiple points during the script, simply append to an output variable and return that at the end of the script.

Tokens are allowed inside of PixelScript. Note that tokens are rendered before the javascript is processed. This allows PixelScript to be modularized and rendered inside of other PixelScript. Remember that rendering tokens inside of PixelScript is for other PixelScript.

Interactions with Pixelsilk are handled through the pixelsilk object built-in to PixelScript. The main ways to use this object are listed below:

pixelsilk object property Description
pixelsilk.render(text) Used for advanced rendering routines. pixelsilk.render will pass a javascript string through the Pixelsilk rendering system, and return the result as a string. This is different from rendering [[Tokens]] directly in PixelScript, as it will contain, for example, quote marks within a string, instead of breaking the javascript. If you want to render a literal token and have its contents accessible inside of a javascript string, use the escaped token format, [[[[Token]]]].
pixelsilk.getFile(fileName) Gets file info for the file fileName, such as its last date it was updated. Returns an object with three properties: id (a GUID as a string), name (a string), and lastVersionDate (a formatted string of the date).
pixelsilk.getFileContents(fileName) Retrieves the contents of the file fileName, and returns them as a string in javascript.
pixelsilk.runFile(fileName) Runs the contents of the file fileName as PixelScript, and returns the value that the script returns. This can be used for common libraries. Note that this only can process primitive values as of now (i.e. no javascript functions or complex objects).
pixelsilk.getURL(url)

Retrieves the contents of url after performing an HTTP GET to the URL. This can be used to read a page externally to pixelsilk and display some contents of that page. For example, the contents could be parsed through jQuery, and then a certain element extracted to be displayed in a Pixelsilk site.

A warning about XSS (Cross-Site Scripting). Note that retrieving content this way circumvents the Same-origin policy present in all browsers, and makes your site much more vulnerable to cross-site scripting attacks. More details on how to protect against this coming soon.

pixelsilk.postURL(url [,parameters]) The same as pixelsilk.postURL, but makes an HTTP POST instead of an HTTP GET. parameters may be optionally specified to send x-form-urlencoded parameters along with the request. If so, parameters should be simple key-value pairs in an object.
pixelsilk.redirect(url) When called, this will issue a redirect to another URL (absolute or relative) for the current request. For example, this can be used to redirect if a query string value is a certain trigger.
pixelsilk.setCookie(name, value) Sets a cookie in the response to the current page.

pixelsilk.request

pixelsilk.request allows you to access variables associated with the request that is coming in from the client viewing the page. Valid parameters are:

Property Description
pixelsilk.request.fullUrl Gets the absolute path of the current page. For example, http://www.pixelsilk.com/my-page/.
pixelsilk.request.path Gets the path part of the current page. For example, /my-page/.
pixelsilk.request.queryString An object containing key/value pairs for the query string of the current request. For example, ?myString=myValue&foo=bar would be an object of the format { "myString": "myValue", "foo": "bar" }
pixelsilk.request.headers An object containing key/value pairs for the headers that have been sent from the client. For example, pixelsilk.request.headers["accept-encoding"].
pixelsilk.request.post An object containing key/value pairs for the POST variables that have been sent from the client. Empty for non-POST requests. Assumes the keys and values have been sent in x-form-urlencoded format.
pixelsilk.request.cookies An object containing key/value pairs for the cookies that have been sent with the client.

Timeout

PixelScripts are limited by default to 2 seconds of running time before timing out. This means that if you have slow running code, or a slow network call to another service, the script may time out before it is finished. Keep this in mind when writing your code.

Example Scripts

If you have any useful scripts you have used, let us know so that we can put them here.

Back to Plug-ins »