Click here to Skip to main content
15,861,367 members
Articles / Programming Languages / Javascript

Starting a Basic JavaScript SDK

Rate me:
Please Sign up or sign in to vote.
4.40/5 (4 votes)
30 Aug 2008BSD5 min read 24.4K   14  
The beginning layout for a JavaScript SDK

Contents

Introduction

JavaScript (JS) has become one of the most used languages on the internet with the explosion of AJAX and Web 2.0 technologies. Just in the past few years, we have seen the usage of JS go from large methods in the head of a web page to large complex APIs that span multiple files and consist of thousands of lines of code. With this mass explosion, most IDEs have just started to encompass intellisense and tools that help developers keep these larger APIs and projects somewhat under control, however there is still room for improvement.

This article brings to the spotlight two great open source projects and consolidates them into a basic SDK style format for developers to use within their projects. It’s a basic starting point for developers who are starting a new project or need to enhance one that already exists. The purpose is to start the framework for a JS based SDK, it in no way is going to encompass a full blown SDK, but it is a good starting point for the beginnings of one.

Overview

The examples used in this article derive from practices applied to the open source project jmorph, and have helped to make it a much more useable project. Having any type of good API requires good documentation and this is where JSDOC comes into play. The other key to large JS projects is to keep the code base light and tight, and this is where the Dojo ShrinkSafe compressor comes in. In the rest of this article, I will explain how I integrated both of these open source projects into the jmorph project and automated them and how you can do the same into your own project.

Setup

Before you begin any integration, you will need to make sure your box is setup with the following programs.

So let’s get started with your basic SDK…

INSTALL PROGRAMS

  1. PERL - Used by JSDOC
    • For Windows users, use ActiveState
    • For Linux users, this is already installed
  2. JAVA - Used by DOJO

TOOL DOWNLOADS

  1. JSDOC – The JS documentation generator
  2. DOJO ShrinkSafe -- The JS compressor (Download Jar)

DEVELOPER AREA

  1. I suggest using Visual Studio or Eclipse
  2. Inside your IDE project, create a directory called SDK
  3. Then, create the following sub structure (The docs_* are used for the JSDOCS program which we will highlight later.)

sdk_dir.JPG

DOJO ShrinkSafe Integration

Because we want to keep our bandwidth tight, especially on heavy traffic sites, it is always a good practice to make sure your project, and especially an API is tight and compact for those developers and users who consume them. That is exactly Dojo’s ShrinkSafe claim to fame. Dojo takes long lengthy JS and turns it into a much more compact style. Here is an example:

BEFORE

C#
/**
* Display this Menu as a SubContext Menu of a MenuItems bound menu property.
* @param {Menu} contextMenu A valid Menu object
* @param {MenuItem} menuItem A valid MenuItem object
* @returns {boolean} Returns false always in accordance with 
* how the contextmenu item receives input.
*/
jmorph.UI.Menu.prototype.ShowAsSubContext = function(contextMenu, menuItem) {
this.Container.style.top = 
	(contextMenu.Container.offsetTop + menuItem.Container.offsetTop) + 'px';
this.Container.style.left = 
	(contextMenu.Container.offLeft + contextMenu.Container.offsetWidth) + 'px';
this.Show();
return false;
};

AFTER

C#
jmorph.UI.Menu.prototype.ShowAsSubContext=function(_f,_10){
this.Container.style.top=(_f.Container.offsetTop+_10.Container.offsetTop)+"px";
this.Container.style.left=(_f.Container.offLeft+_f.Container.offsetWidth)+"px";
this.Show();
return false;
};

To integrate ShrinkSafe into our library, follow these steps.

STEP 1 – Create Directory

Create two directories, one from which you plan to develop from called debug and another in which you plan to execute Dojo against called release. The release directory will be a mirror of the debug directory, but will contain all the *.js files compressed.

build_dir.JPG

STEP 2 – Automate Dojo

Dojo is a command line based tool, so in order to get the most out of it, you need to write a batch/shell script around your project. The example provided below is a .bat file, but can easily be written as a shell script.

@echo off
REM ********************************************************
REM * Used for compressing a JS library using dojo 
REM * Rhino Valid arguments are:
REM * -w
REM * -version 100|110|120|130|140|150
REM * -opt [-1|0-9] -f script-filename
REM * -e script-source -o output-filename
REM * -c script-filename
REM * java -jar custom_rhino.jar -c infile.js > outfile.js 2>&1
REM ********************************************************
echo running compression...
REM BASE
set dBase=C:\path_to_files\builds\debug\base
set rBase=C:\ path_to_files builds\release\base
FOR %%l in (%dBase%\*.js) DO java -jar custom_rhino.jar -c "%dBase%\%%~nl.js" > 
	"%rBase%\%%~nl.js" 2>&1
REM MISC
set dMisc=C:\ path_to_files \builds\debug\misc
set rMisc=C:\ path_to_files \builds\release\misc
FOR %%l in (%dMisc%\*.js) DO java -jar custom_rhino.jar -c "%dMisc%\%%~nl.js" > 
	"%rMisc%\%%~nl.js" 2>&1
echo done with compression!

Note: This script has every directory that we want to run the dojo compressor against listed. Remember this is only an example script and can be written to recursively loop through the directories you want or you can do it file by file if you want. This script is just a sample of automating the dojo process against a directory, which then compresses every JS file in that directory.

Caution: Be sure that you don’t run this against code in the debug (or your original code base) directory or else you won’t be able to get the original format back unless you have a copy lying around somewhere else. So be sure to test the script against a copy of the code that you really don’t care to be formatted.

JSDOC Integration

Because we want to write good code and not just cowboy up our projects with mountains of code that doesn’t benefit anyone when we get hit by a truck, we need to create good documentation. This is where JSDOC comes into play. This is one of the nicest JS documentation tools out there, and it’s totally free.

I’m not going to go into the ins and outs of how JSDOC generates its output; you can get all that information on the JSDOC website. However I will outline a quick set of steps to use to get JSDOC running quickly. The steps below assume you have already installed Perl.

The picture below is an example of JSDOCs output.

doc_example.jpg

Step 1 – Setup Directory

Create a directory called docs. A good place would be in the same directory you created the builds directory.

Step 2 - Automate

Automate the JSDOC with a batch/shell script. Below is an example of a batch script.

@echo on
REM PACKAGE DISPLAY
jsdoc-1.10.2\jsdoc.pl 
-r \path_to_files\ 
-d \path_to_output\ 
--page-footer "Copyright © 2007 by Author Name" 
--project-name "my project" 
--project-summary "docs_summary.html" 
--extensions helper,js 
--package-naming

Step 3 – Click to Run

Now that we have the dojo compressor automated across our JS project/library, and we have the JSDOC automated, all we need to do is double click the batch files (or combine them if you want) and then let dojo and JSDOC do its magic and our release directory is ready to ship tightly compressed with documentation. Remember with JS, we only need to run this compression script once we are ready to ship, because we do all of our testing out of our debug directory.

Note: There is also another open source package available that gives the same document generation output that JSDOC does. It is called JSDOC toolkit and is written in Java. So if you’re not up to using the JSDOC Perl version, try the JSDOC toolkit Java version.

Conclusion

In the era of writing large JavaScript APIs/projects, it’s important for developers to have the tools that help them automate the tasks of compression and documentation. Integrating the two tools mentioned in this article can help developers do just that. To see an example of how these two tools have been used in a larger JS project, visit the following open source project jmorph.

History

  • 30th August, 2008: Initial post

License

This article, along with any associated source code and files, is licensed under The BSD License



Comments and Discussions

 
-- There are no messages in this forum --