How Do I...Write my First DekiScript XML Extension?
Table of contents
MindTouch Deki includes a robust API and intuitive interface for integrating with web services, applications, and data silos. The best way to get started with MindTouch Deki's framework is to make an XML extension. You may have added a custom extension before as they are featured on the MindTouch blog. In this tutorial I'll walk you through the steps for creating your own XML extension and show you how to add it in MindTouch Deki.
Getting started
In order to create the extension XML file, we'll need a text editor. For Windows users, Notepad will work well. For Linux users, VI will work.
Create a new document and paste the following code into it:
<extension> <title>Sample DekiScript Extension</title> <namespace>sample</namespace> <function> <name>extension</name> <description>Add a description for the extension</description> <return> <html xmlns:eval="http://mindtouch.com/2007/dekiscript"> <head></head> <body> </body> <tail></tail> </html> </return> </function> </extension>
Now that we have a base template for the XML extension we can do our test. We are going to create a Hello World Extension, because that is always the best place to start with tutorials :)
We want the Hello World text to show up on the screen when we add the extension, because of this we will put the text in between the body tags of the XML file. If you are familiar with HTML rules as far as where content needs to be placed, then this will be familiar. The following shows the Hello World text correctly placed in the XML file along with changes to the title, namespace, name, and description so that when we activate the extension it will include this documentation.
<extension> <title>Hello World Extension</title> <namespace>hello</namespace> <function> <name>world</name> <description>This is my test Hello World extension</description> <return> <html xmlns:eval="http://mindtouch.com/2007/dekiscript"> <head></head> <body> Hello World </body> <tail></tail> </html> </return> </function> </extension>
- Attach the Hello World extension XML to your My Page on Deki
- Once it is attached, right click on the file name and save the link location (on some browsers this is the Address found in Properties)
- Now go into the Control Panel -> System Settings -> Add Script
- Give the Extension a name like Hello World Extension
- Then paste the url of the xml file that you copied in step 2 into the Manifest field
- You can choose to check the debug box which will refresh the extension on each call, this is helpful when you are testing out your extension
- Once you have everything setup click Add Script
- Now return to a sample page on your Deki and Edit the page
- Click on the Extensions button and scroll through the selection of Extensions until you see the Hello World Extension
- Click on it and then click on the hello.world option
- This will insert the following DekiScript onto your Deki page:
{{ hello.world{} }} - Then click Save and you should see Hello World on your Deki page
Embedding Javascript using MindTouch Deki Extension
A common use for the Custom extensions in MindTouch Deki is the ability to add unsafe script that you wouldn't want your users adding on their own but that you'd still like to make available to them. In this example we'll take some javascript and create an XML file for it so that we can call the javascript through the extension dialog.
Here is our sample javascript that we are going to embed. It is a DuckHunt game to embed courtesy of WidgetBox.
<script type="text/javascript" src="http://widgetserver.com/syndication/subscriber/InsertWidget.js?appId=b50f7c7f-ca7a-4747-8120-881b16afadf4"></script>
Now that we have the script, let's apply it to the XML file so that we can easily invoke the game on a Deki page.
Taking the template above, I've included the script so that when we add the Extension to Deki, it will display the game. Note: As you can see the layout of the XML file is very similar to an HTML page, likewise when you are creating an XML file for an Extension content that would go in the body area of an HTML page would go in the body area of the XML document, this goes the same for the header too.
<extension> <title>DuckHunt</title> <namespace>duck</namespace> <function> <name>hunt</name> <description>This will add the DuckHunt Video game to a Deki Page</description> <return> <html xmlns:eval="http://mindtouch.com/2007/dekiscript"> <head></head> <body> <script type="text/javascript" src="http://widgetserver.com/syndication/subscriber/InsertWidget.js?appId=b50f7c7f-ca7a-4747-8120-881b16afadf4"></script> </body> <tail></tail> </html> </return> </function> </extension>
- Attach the Duck Hunt extension XML to your My Page on Deki
- Once it is attached, right click on the file and save the link location
- Now go into the Control Panel -> System Settings -> Add Script
- Give the Extension a title like DuckHunt
- Then paste the url of the xml file that you copied in step 2 into the Manifest field
- You can choose to check the debug box which will refresh the extension on each call, this is helpful when you are testing out your extension
- Once you have everything setup click Add Script
- Now return to a sample page on your Deki and Edit the page
- Click on the Extension link and scroll through the selection of Extensions until you see the DuckHunt
- Click on it and then click on the option
- This will insert the following DekiScript onto your Deki page:
{{ duck.hunt{} }} - Then click save and you should see the DuckHunt game on your Deki page
XML syntax tips
Along with any language, there are certain syntax checks that need to be heeded when editing an XML document. First I'd recommend getting an XML editor that will validate your XML and will let you know if there is anything wrong with your syntax. Here are a couple of options:
- Microsoft Expression Web
- oXygen
- Any HTML editor that will validate XML
If you can't get your hands on an XML editor, or prefer to go hard core with notepad, then here are some tips on validating your XML:
- Once you have created your XML, open it in a browser like FireFox or Internet Explorer, if there are issues the browser should kick out a warning
- Make sure that your document is properly formatted. Like any programming language, errors with missing close tags or misplaced tags can cause issues
- If you do receive errors make sure you check out the following characters that need to be reformatted in order to not cause problems:
- & (& or "ampersand")
- < (< or "less than")
- > (> or "greater than")
- ' (' or "apostrophe")
- " (" or "quotation mark")
The formatting above occurs within tags, so you don't need to worry about replacing the < > arround tags with the equivalent above. One example I can give is when a src link within a tag includes the & like the following example:
www.mindtouch.com/home&key=2
In this case the XML will cause errors because the & isn't properly formatted. Here is the correct way to format it so that it will work:
www.mindtouch.com/home&key=2
Add parameters into XML Extension
When you are adding extensions to Deki, you want to be able to also add variables to affect the extension like height, width, color, and more. These are called parameters and can be added into the XML extension so that when you add the extension, you can control the variables through the editor as opposed to changing the actual embed code. This is beneficial for many reasons including: Ease of use of end users, security of ensuring wrong code isn't added/changed which could cause problems on the site, and accessibility to code that would otherwise be restricted because of fear of mis-use. A perfect example of an extension with Parameters is the FeVote extension. First let's take a look at the default embed code for FeVote for the MindTouch Deki Board:
<script type="text/javascript"> fevote_embed_category="deki_wiki"; fevote_embed_width="100%"; fevote_embed_height="100%"; </script> <script type="text/javascript" src="http://www.fevote.com/embed/embed.js"></script>
In the above code, the following parameters can be customized: fevote_embed_category, fevote_embed_width, fevote_embed_height. Now that we have identified the parameters that we want to be able to be defined, let's look at how to change the XML so that these can then be customized by the end user. To get started let's look at the XML for the Extension without the parameters defined:
<extension> <title>FeVote</title> <namespace>fevote</namespace> <function> <name>widget</name> <description>This allows you to embed the MindTouch Deki FeVote voting board</description> <return> <html xmlns:eval="http://mindtouch.com/2007/dekiscript"> <head></head> <body> <script type="text/javascript">
fevote_embed_category="deki_wiki";
fevote_embed_width="100%";
fevote_embed_height="100%";
</script>
<script type="text/javascript" src="http://www.fevote.com/embed/embed.js"></script> </body> <tail></tail> </html> </return> </function> </extension>
Now we want to add the parameters to make the extension flexible so that if the end users want to add other boards or change the dimensions of the extension, they can. To do this we first identify the parameters in between the <description> and <return> tags by using the parameter code:
<param name="Name" type="identify_type">Description</param>
Let's apply the first parameter for the fevote_embed_category so you can see what it looks like. For the param name we want to use something short but that will be easy to tie to the parameter. For fevote_embed_category I'm going to use the name "category". Next you need to identify the type, here are the options for Type:
| Data Type | Description |
| nil | The empty value, represented by _, nil, and null. |
| bool | A logical value, represented by true and false. |
| num | A 64-bit floating point value. |
| str | A character string. |
| magic identifier | An automatically generated string that is guaranteed to be unique across scopes. |
| map | An associative array that assigns a key to an expression. |
| list | An indexed array of expressions. |
For the category type I'm going to use str as the type as it is just characters. For a majority of basic XML extensions your type will be probably be num and str. Now that we have identified the type all we need to do is add a Description like: "FeVote board name for embedding". The code will then look like the following:
<param name="category" type="str">FeVote board name for embedding.</param>
We also need to create the params for the fevote_embed_width and the fevote_embed_height. These will be the same as far as type which will be num. Here is their param code:
<param name="width" type="num" optional="true">Panel width. (default: 100%)</param> <param name="height" type="num" optional="true">Panel height. (default: 1800px)</param>
With the height and width we introduce a new option in the param code called optional. Optional="true" can be added when the params have a default so that it isn't a required value in order for the extension to be invoked. In the case of the width and height we specify in the lower XML code the defaults and then add notes in the Description area of the param code so that the end users are aware of the default values. Now that we have all of the param codes, let see what they look like in the XML:
<extension> <title>FeVote</title> <namespace>fevote</namespace> <function> <name>widget</name> <description>This allows you to embed the MindTouch Deki FeVote voting board</description> <param name="category" type="str">FeVote board name for embedding.</param> <param name="width" type="num" optional="true">Panel width. (default: 100%)</param>
<param name="height" type="num" optional="true">Panel height. (default: 1800px)</param> <return> <html xmlns:eval="http://mindtouch.com/2007/dekiscript"> <head></head> <body> <script type="text/javascript">
fevote_embed_category="deki_wiki";
fevote_embed_width="100%";
fevote_embed_height="100%";
</script>
<script type="text/javascript" src="http://www.fevote.com/embed/embed.js"></script> </body> <tail></tail> </html> </return> </function> </extension>
We aren't done yet though. Now we need to change the javascript that is in the <body> part of the XML to dynamically recognize and insert the parameters. In order for the DekiScript engine to pickup that params need to be inserted, we need to use eval statements. You can check out the full list of eval statements, but for this example we only need <eval:js> as we are evaluating the javascript. To start we'll evaluate the fevote_embed_category to reference the category param that we added higher up in the XML. To do so we need to change this line:
fevote_embed_category="deki_wiki";
to
fevote_embed_category=<eval:js>args.category</eval:js>;
When evaluating any params, the params have an args.(parameter name) In this case it is args.category. This way the DekiScript engine is evaluating the args.category which knows to check if there is a parameter argument called category.
Next we need to evaluate the width and height which have a little bit different configuration as we are going to specify the defaults for the width and height as they are optional parameters. Here is the code as it is currently setup:
fevote_embed_width="100%";
fevote_embed_height="100%";
This is how what we need to change it:
fevote_embed_width=<eval:js>web.size(args.width ?? .999)</eval:js>; fevote_embed_height=<eval:js>web.size(args.height ?? 1800)</eval:js>;
First we introduce a new dekiscript variable into the mix called web.size. web.size allows easier formatting of dimensions by allowing to specify any decimal under 1 is considered percent for size and anything 1 or higher is pixels. You can read more about web.size on the documentation page. Next we have the args.width and args.height as we have above but then we have ?? and a number. The ?? specifies that if a value isn't given then default to .999 in case of width and 1800 in case of height. This is how we specify the default. Also make sure after specifying this default that you update the description of the parameter to explain. Now that we have all of the parameters named and the javascript updated we have the final XML:
<extension> <title>FeVote</title> <namespace>fevote</namespace> <function> <name>widget</name> <description>This allows you to embed the MindTouch Deki FeVote voting board</description> <param name="category" type="str">FeVote board name for embedding.</param> <param name="width" type="num" optional="true">Panel width. (default: 100%)</param>
<param name="height" type="num" optional="true">Panel height. (default: 1800px)</param> <return> <html xmlns:eval="http://mindtouch.com/2007/dekiscript"> <head></head> <body> <script type="text/javascript">
fevote_embed_category=<eval:js>args.category</eval:js>; fevote_embed_width=<eval:js>web.size(args.width ?? .999)</eval:js>;
fevote_embed_height=<eval:js>web.size(args.height ?? 1800)</eval:js>;
</script>
<script type="text/javascript" src="http://www.fevote.com/embed/embed.js"></script> </body> <tail></tail> </html> </return> </function> </extension>
Now that we have the final XML, save it and attach it to a Deki Page. Once attached copy the link location of the XML file and go into the Control Panel -> System Settings -> Add Script. Give the Extension a name like FeVote and then paste the XML link location into the Manifest field like so:
Then click Add Script
Once it is added go to a page that you want to add the Extension on and click the Extensions button in the editor. This will load up the Extension Dialog, navigate to the Extension and click on it and then click on fevote.widget. You will then see the parameters that you specified in the XML file listed on the right as follows:
Now you can add the category and width and height as you would like and click insert and it will then add the following code to the Deki page:
{{ fevote.widget{category: "dekiwiki", width: ".85", height: "1500"} }}
- Tag page
-
- What links here
Images 2
