Adding Unity3D to your Drupal site

Printer-friendly versionSend to friend

A few months back I decided I would write a module that handled the uploading and display of Unity3D players to Drupal based sites. I must admit I haven't spent long on this since I came up against some pretty tricky file upload issues, on top of that I have been attempting to buy a flat for what seems like forever, so development on this has come to a bit of a stand still.

The recent announcement of Unity Indie now being free made me think it would be a good time to revisit this so I have, but I will not be developing a Drupal module for it. There are a few reasons behind this decision but the main one is that I really don't have time to maintain a module, so instead I started thinking about how to make the best use of the modules that are already out there (why re-invent the wheel) and come up with a good, reliable and reasonably future proof method of embedding Unity3D players without the need for custom module development. Here's what I came up with:

What you will need:

• Content Creation Kit (CCK) Module
• FileField CCK Plugin
• UnityObject JavaScript
• A Unity3D Player to test with
• Some basic PHP knowledge

Install the necessary modules

Download the CCK and FileField modules listed above and extract them to the your_drupal_site/sites/all/modules directory

Once you have these extracted, open up a web browser and go to the module admin page, found at 'admin/build/modules', and enable the modules as per the screen shot below:

Creating the content type

Now we have the modules installed we can create our content type. Go to 'admin/content/types' and add a new content type as per the screenshot below. You don't have to follow this naming convention but... what else are you gonna call a Unity node huh?

Save this content type and you will be taken back to the content types admin screen. From here, find your newly created content type in the list and click the manage fields link next to it:

Adding the FileField Upload

Here is where the FileField plugin we installed earlier comes into play. To add a new field to our content type scroll down to the 'Add' section and fill in the required fields. You will need to name the field, I called mine 'Unity3D Player', and select the type of field you want to use, select 'File' from the select list and the same from the 'Select a Widget' list (it will probably be the only option in there if your site is a fresh install). Hit save and you will be taken to the field configuration screen.

Configuring the player field

Here we can set up our upload field to accept the Unity player. Locate the 'Permitted upload file extensions' text field, delete the contents and replace with the file extensions you want to allow, in this case 'unity3d'. Note - make sure you don't include the ' . ' before the file extension, it's not needed.

This step enables us to ensure that only Unity players are accepted by Drupal, meaning that no incorrect file type can be uploaded which could cause problems. The beauty of doing it this way is that if Unity decide to change the extension used by the Unity player in the future, you can simply add it to the list here and it will work. If I had gone ahead with module development it would have meant possibly updating the module code, testing and releasing... this way you can do it yourself!

Creating the node template

We now have our basic content type, with title, body field and a Unity Player upload field, which is nice and all but we ain't done yet!

Go to node/add and create a new Unity3D node, give it a title, some body text if you want and upload your test unity file to the upload field. If all goes well you should be taken to your newly created node where you will see your title, body and a link to the Unity Player file... hmmmm... not really what we want. So, our next step is to create a custom page template.

Open a new finder window (Mac) or explorer window (Win) and navigate to your drupal theme directory. Here you will see a list of files similar to the screenshot below:

Find your node.tpl.php file and duplicate it, renaming it to node-unity.tpl.php. If you called your new content type something other than Unity you will need to substitute it in the file name i.e. node-[content-type-name].tpl.php.

Now we have a copy of the base page template we can begin to customize it to display our player. Essentially what we are looking to do is to grab the url of the uploaded player and embed it, rather than displaying it as a link as is the default behavior for a Drupal file upload.

Open up the node-unity.tpl.php file in your favorite text editor or IDE and find where $content is printed out. $content contains all of the data stored in the fields of the node when its created. Wrapped up in here we have formatted mark up for the body text and any other fields added with CCK - we cannot get the Unity Player path out of this variable but not to worry, we can get it from $node instead.

$node contains the raw data of the node, all wrapped up in a php object so we can access the attributes we need. To see what I mean, throw this into content div and refresh the page:

<?php drupal_set_message('
'.print_r($node->field_unity_player[0]['filepath'],1).'
'); ?>

You should see the path the the player we uploaded when we created the node. To understand more about how the fields are stored in Drupal try just printing $node in the above snippet, you will see the whole node structure and what data you have access to.

Embedding the player

Ok, now we have access to the player, we can embed it. This is where the UnityObject script from unifycommunity.com comes into play. I like unityObject as its very simple to use and basically, does what it says on the tin!

Add the following code to your node template (wrapped in script tags):

var uniObj = new UnityObject("<?php echo $node->field_unity_player[0]['filepath'] ?>", "unity", "640", "480", "2");
uniObj.setAttribute("altHTML", "Install the Unity Web Player");
uniObj.write();

This should be fairly self explanatory to someone looking to embed a unity player into their site but I will breifly explain it. All we are doing is using the example code from the unify community site and inserting the path to the player via php instead of hard coding it. Drupal will use this node template for any content of type Unity in the future, so it needs to be dynamic.

Add the UnityObject script

There is one more step we need to go through to get our player to display, adding the unityObject.js to the page header. Now, there are a couple of ways to do this, we could just add a line of HTML to the page template (page.tpl.php) that pulls in the javascript file, but that would mean that it gets loaded on every page. Its not a huge overhead, but there is a more 'Drupal' way of doing things...

In a text editor create a new file and paste in the unityObject code from the unifycommunity wiki and save it as unityObject.js. This file needs to be saved to your themes root directory, or a sub folder called 'js' (or similar).

In your themes directory locate the file 'template.php'. This is the file that controls a lot of what Drupal outputs to the .tpl.php files. Drupal does this by calling some preprocessing functions, these are normally used to add variables to the site node object before its passed to the tpl file, but they will suit our needs here as well.

Add the following code to your themes 'template.tpl.php' file:

function phptemplate_preprocess(&$vars, $hook) {
    if($vars['node']->type == 'unity'){
        drupal_add_js(path_to_theme().'/js/unityObject.js');
    }
}

This tells drupal that when the page preprocess function is called, check to see what type of content is being loaded and if it is a node of type 'Unity' to add the path to the unityObject javascript to the scripts array, which then gets passed to the page.tpl.php file.

If you save everything now and refresh the page in your browser you should see your player in all its glory... but you will also see the link to the player, we need to get rid of this but never fear, Drupal has a way to do this out of the box!

Go back to 'admin/content/types', find the Unity content type and click 'Display Feilds' - here you can choose which fields should be visible to the user when they view the node, it wont however remove the field from the node object. This allows us to remove the link on the screen without losing the path to the player.

You should now see the embedded player in your node. Now you are set up and ready to go, you can add as many Unity nodes as you like! You will probably need to wrap the embedding code in a div so you can style its appearance and set its position on the page, but thats down to you and your own personal preferences.

Hope this helps some of you Unity devs out there! Feedback / corrections welcome :)