Developing your first customisation

Summary

A quick walk-through on how to approach developing your first customisation.

I thought it would be fun to base this example on Jan Tielens SmartDock for SharePoint, which is a jQuery extension that he has released as an example for his SmartTools project.

Getting the first part of the script together

Let's start by getting the bits we need to be able to see stuff happening. As we're creating a jqDock customisation we need to go and download jqDock from that project site.

Once we have jqDock, we need to get that onto the page so that we can start our customisation.

I'm going to use the minified version, as it's available and it means that we can avoid having to perform the minification:
DECLARE @injectId [INT];
INSERT INTO [dbo].[P3_ShUIE_INJECT] ([Name], [Active], [Text], [Type], [Minify], [Sequence]) VALUES (N'jqDock', 1, N'
/*jQuery plugin : jqDock v1.2 */
;(function($){if(!$.fn.jqDock){var jqDock=function(){return{version:1...
', N'js', 0, 2);
SELECT @injectId = @@IDENTITY;
Note 1: I've obviously chopped the INSERT there so you don't have to read 10KB of minified JavaScript.
Note 2: Before you paste JavaScript into a SQL insert statement, ensure that you have replaced all ' with '' so that the syntax of the SQL script isn't broken.

I've given jqDock a Sequence of 2, as we want it to run quite early so that the code we will write that depends on it will run afterwards.

Putting it onto the page

So now we have jqDock, to get it onto the page we simply need to create a global context or re-use the one from the Hello World sample:
DECLARE @globalContextId [INT];
SET @globalContextId = 0;

SELECT @globalContextId = ContextId
  FROM P3_ShUIE_CONTEXT
 WHERE Name = 'Global'
   AND Active = 1

IF @globalContextId = 0
BEGIN
	INSERT INTO [dbo].[P3_ShUIE_CONTEXT] ([Name],[Active]) VALUES ('Global',1);
	SELECT @globalContextId = @@IDENTITY;
END

And then glue the context and the script together:
INSERT INTO [dbo].[P3_ShUIE_CONTEXT_INJECT] ([ContextId], [InjectId], [Active]) VALUES (@globalContextId, @injectId, 1);

Quick Test

Let's just make sure we've got the first bit working... does the source HTML of a page now include jqDock?
1.png
View source says yes!

Adding our jqDock code

So now we have our jQuery plugin on the page... what next? Writing some code to make a little menu would be good, and as I don't really want to go and create a whole new menu from scratch, let's just copy the quick links from the left of the SharePoint page and render it as a jqDock menu on the right side... similar to what Jans did.

Here's our JavaScript:
$(document).ready(function(){
  $("div.ms-quickLaunch").before(
    "<div id='jqDockMenu' style='position:absolute; top:100px; right:10px; width:30px;'>"
  );
  
  $(p3context.Lists).each(function () {
    if (!this.Hidden && this.DefaultViewImageUrl && this.DefaultViewUrl)
      $("div#jqDockMenu").append(
        "<a href='" + p3context.Web.Url + this.DefaultViewUrl + "' title='" + this.Title + "'>" +
        "<img src='" + p3context.Web.Url + this.DefaultViewImageUrl + "' alt='' title='" + this.Title + "' />" +
        "</a>"
    );
  });

  $("div#jqDockMenu").jqDock(
    {
      align: "right",
      labels: true,
      size: 48
    }
  );
});

What does that do? Well it creates a new <div>, into which we create anchors for each of the Lists that has an image, url and isn't hidden.

The observant amongst you will have noticed that p3context object. That is documented within the JsonContextHelpers. It's an object that ShUIE gives you to help make your life easier... it tells you basic things about the Site, Web, CurrentList, Lists and Fields (for the CurrentList).

Finally we instantiate the jqDock plugin, and that does all of the magic.

And here's that wrapped up as our SQL update... update and not insert as we had already inserted earlier:
UPDATE [dbo].[P3_ShUIE_INJECT] SET [Text] = N'
$(document).ready(function(){
  $("div.ms-quickLaunch").before(
    "<div id=''jqDockMenu'' style=''position:absolute; top:100px; right:10px; width:30px;''>"
  );
  
  $(p3context.Lists).each(function () {
    if (!this.Hidden && this.DefaultViewImageUrl && this.DefaultViewUrl)
      $("div#jqDockMenu").append(
        "<a href=''" + p3context.Web.Url + this.DefaultViewUrl + "'' title=''" + this.Title + "''>" +
        "<img src=''" + p3context.Web.Url + this.DefaultViewImageUrl + "'' alt='''' title=''" + this.Title + "'' />" +
        "</a>"
    );
  });

  $("div#jqDockMenu").jqDock(
    {
      align: "right",
      labels: true,
      size: 48
    }
  );
});
'
WHERE [Name] = N'jqDockMenu';

Testing

The key question... does it work, well let's take a quick look:
finished.png

Cool... so we have jqDock, in a very small piece of code, and the ability to deploy it simply, and activate it wherever we want over a SharePoint farm.

Bringing it all together

One last thing before we go... package up all of the SQL into a single coherent script that can be used to deploy this.

Note: This is where you turn on minification for your customisation... be sure to check that it still works after you do this, sometimes your syntax cannot be minified nicely and it creates syntax errors... so do check.

The finished version can be found in the source code under /Customisations/jqDock/jqDock.sql

Last edited Dec 8, 2008 at 12:54 PM by DavidK, version 9

Comments

No comments yet.