h1. JavaScript Project Generator

h1. &#x2192; 'newjs'


h2. What

A simple command-line tool to create the folders and helper files
for a new JavaScript project/library. As a bonus, you can quickly
create a website to promote your project.

When you start a new JavaScript library, how do you layout the source files,
the tests, the distribution files? Do you have support scripts to
generate distributions from source files? Run your JavaScript unit tests?
Generators to create new unit test HTML files?

*No? Me neither*, so I created the JavaScript Project Generator. 

Once <code>newjs</code> has finished helping you write your source libraries,
write test HTML files, providing autotesting scripts to make TDD a piece of cake,
it finally helps you bundle all your source files into a single JavaScript file
for distribution.

What a nice helpful tool it is!

h2. Installing

Installation and maintenance of generated JavaScript projects
requires the installation of "Ruby":http://www.ruby-lang.org/ and "RubyGems":http://rubygems.org/.

The command-line application <code>newjs</code> is installed as below, 
for any operating system (except the 'sudo' part - use as necessary):

<pre>sudo gem install newjs</pre>

h2. Getting started

To kick-off your new project/library, run the command-line app <code>newjs</code>:

<pre>$ newjs mylib -a "Dr Nic" -e "drnicwilliams@gmail.com" -u "http://mylib.rubyforge.org"
      create  config
      create  lib
      create  src
      create  script
      create  tasks
      create  test/assets
      create  test/assets/unittest.css
      create  test/assets/unittest.js
      create  test/assets/prototype.js
      create  tasks/javascript_test_autotest_tasks.rake
      create  tasks/environment.rake
      create  tasks/deploy.rake
      create  config/javascript_test_autotest.yml.sample
      create  lib/protodoc.rb
      create  lib/jstest.rb
      create  Rakefile
      create  README.txt
      create  History.txt
      create  License.txt
      create  src/HEADER
      create  src/mylib.js
      create  script/rstakeout
      create  script/js_autotest
  dependency  install_rubigen_scripts
      exists    script
      create    script/generate
      create    script/destroy
</pre>

Look at all that!

Unit testing uses the <code>unittest.js</code> library 
developed within "prototypejs":http://www.prototypejs.org/. It should
also support JavaScript development using any non-prototype.js libraries.

Your raw, unconcatenated library/source files go in <code>src/</code>

Your unit test HTML files, go in <code>test/unit/</code> (see test generator below).

Your functional test HTML files, go in <code>test/functional/</code> (see test generator below).

When you've got a new version to release, edit <code>Rakefile</code> and modify the
<code>APP_VERSION</code> string (see Distribution section below).

To merge your <code>src/</code> files into a distribution file, see below.

h2. Unit testing

If you are going to have a <code>src/some_lib.js</code> file, then you'll want a unit
test file(s). By default you'd call it <code>test/some_lib_test.html</code>.

h3. Generating test HTML files

And then what? Personally, I can never remember what basic HTML + JavaScript
goes in the test HTML files. I quite like the "javascript_test plugin":http://drnicwilliams.com/2008/01/04/autotesting-javascript-in-rails/ for "Ruby 
on Rails":http://www.rubyonrails.org/, which allows you to generate a
test HTML stub. So I've included a version of it
here. That is, your JavaScript project comes with a generator to create new
test HTML files, ready to rock and roll.

<pre>$ script/generate unit_test some_lib
  create  test/unit
  create  test/unit/some_lib_test.html</pre>
  
Now edit <code>test/unit/some_lib_test.html</code> and follow the comments
that tell you what to do to write your unit tests.

Want to name your test file something different? Specify the target
library as an additional parameter.

<pre>$ script/generate unit_test my_library_tests some_lib
  exists  test/unit
  create  test/unit/my_library_tests_test.html</pre>

h3. Running unit tests

Each test HTML file should be self-executable: just open it in a target
browser. That is, to run the <code>test/some_lib_test.html</code> tests
in Firefox, open the file in Firefox. 

It will print out a beautiful log success/error messages for each test.

<img src="images/example-unittest-log.jpg" width="647" height="427" alt="Example Unittest Log">

h2. Functional tests

End-to-end functional tests will test the final distribution file(s), rather than
the <code>src/</code> files.

As shown below, your <code>src/</code> files will be merged into (commonly) one 
distribution file - a merging of your source files.

h3. Generating test HTML files

To create functional tests, there is another generator:

<pre>$ script/generate functional_test basic_usage
  create  test/functional
  create  test/functional/basic_usage_test.html</pre>

h3. Running functional tests

<pre>rake test_functionals</pre>

The generated HTML file uses the <code>dist/mylib.js</code> file. So, if
you are running these tests it is best to use the <code>rake test_functionals</code>
as it pre-builds the distribution files first.

h2. Distribution of library

Your project comes with the ability to concatenate all your <code>src/*.js</code>
files into a single file for distribution, as <code>dist/project_name.js</code>.

First, edit <code>src/HEADER</code> with information that will be included
at the top of the generated distribution file.

Second, edit <code>src/project_name.js</code> to include the names of
all the <code>src/</code> files that will be concatenated together
in your required order.

Finally, run the command:

<pre>rake dist</pre>

Two files are added into the <code>dist/</code> folder:

<pre>$ ls dist/
drnic_js_test_helpers-0.5.0.js  drnic_js_test_helpers.js</pre>

One with a version number, and one without.

h3. Upload library to rubyforge

Assuming you don't really care where your package/library is uploaded
and made available for downloading, <code>newjs</code> projects comes
pre-built ready to upload them to <code>rubyforge</code>.

First, you'll need a rubyforge account.

Second, create a rubyforge project. It can take 12-48hrs for confirmation
to come back.

Third, use the <code>rubyforge</code> command-line app to 
store your rubyforge project information locally.

<pre>$ rubyforge setup  # first time only
$ rubyforge login
$ rubyforge config
$ rubyforge create_package project_name project_name
</pre>

Note, if you are placing your JavaScript project within an existing
rubyforge project, then the two <code>project_name</code> values
are different:

# The rubyforge project name (e.g. drnicutilities) 
# The JavaScript project/library name (e.g. drnic_js_test_helpers)

Finally, each time you want to release a new version of your library you do 
two things:

# Update Rakefile's <code>APP_VERSION</code> value to the new version number
# Run <code>rake release VERSION=X.Y.Z</code>

Your files are now available for download via rubyforge.org. 

If you use the generated website (below), it comes with a link to these
files when you click the large version number (e.g. "Get Version X.Y.Z").

h2. Create a website for your project

You can quickly create a clean, readable website for your project
that prominently displays the current version number (which is a 
clickable link through to the download page), just like this page.

<pre>script/generate install_website</pre>

Now edit the generated <code>website/index.txt</code> file ("Textile":http://www.textism.com/tools/textile/ format).

To convert it to HTML, run:

<pre>rake website_generate</pre>

And open <code>website/index.html</code> in your browser to preview.
The project's version number is automatically inserted into the page
(change version numbers via <code>APP_VERSION</code> in <code>Rakefile</code>).

h3. Configuration of website upload

It is assumed you will upload your website files to rubyforge.org server.
To push files to an alternate server, modify the <code>tasks/website.rake</code> file.

To configure which rubyforge project to upload to, create <code>config/website.yml</code>.
There is an example in <code>code/website.yml.sample</code>.

An example might be:

<pre>host: nicwilliams@rubyforge.org
remote_dir: /var/www/gforge-projects/drnicutilities/drnic_js_test_helpers
</pre>

Here, the files will be uploaded into the <code>drnicutilities</code> rubyforge
project, under a sub-directory <code>drnic_js_test_helpers</code>. This site
would be visible at "http://drnicutilities.rubyforge.org/drnic_js_test_helpers":http://drnicutilities.rubyforge.org/drnic_js_test_helpers
  
If your website lives in its own rubyforge project, then just specify the project
name, and the website will be uploaded into the root folder.

For example, the website would be available at "http://drnicutilities.rubyforge.org/":http://drnicutilities.rubyforge.org/ if your
configuration was:

<pre>host: nicwilliams@rubyforge.org
remote_dir: /var/www/gforge-projects/drnicutilities
</pre>

h3. Uploading website to server

To upload the website (and its CSS etc) run:

<pre>rake website_upload</pre>

More commonly, to generate and upload the website:

<pre>rake website</pre>

h2. Screencast coming soon

A hard-core, "how to do JavaScript unit testing" screencast will
soon be published by "PeepCode":http://peepcode.com/. It will cost $9
and you'll love every minute of it.

Subscribe to PeepCode's blog for announcement details.

h2. Examples

The development of <code>newjs</code> was done in parallel with
"Dr Nic's JavaScript Test Helpers":http://drnicutilities.rubyforge.org/drnic_js_test_helpers/
(source: "git":http://github.com/drnic/drnic_js_test_helpers/tree/master).

Checkout this project to see examples of unit tests, configuration etc.

h2. Forum

"http://groups.google.com/group/javascript-project-generator":http://groups.google.com/group/javascript-project-generator


h2. How to submit patches

Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section "8b: Submit patch to Google Groups":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups, use the Google Group above.

The source project is a "Git":http://git.or.cz/ repository. See Dr Nic's "master branch":http://github.com/drnic/newjs/tree/master for clone/checkout details.

h2. License

This code is free to use under the terms of the MIT license. 

h2. Contact

Comments are welcome. Send an email to "Dr Nic Williams":mailto:drnicwilliams@gmail.com via the "forum":http://groups.google.com/group/javascript-project-generator

