Creating a Package

wagenet edited this page Sep 21, 2011 · 5 revisions

Half the fun of BPM is that you can create and share packages for others to use in their projects. Creating a package is quite simple so let's get started.

Step 1: Create Your Package

Since we don't yet have a package generator, you can clone the template from git:

git clone git://github.com/bpm/package_template.git my_package
cd my_package

Next you'll want to open up the package.json and update the values to fit your package. For now don't mess with the directories and bpm:build options.

Step 2: Add Some Code

By default the package code is stored in the lib directory with main.js being the primary file. Lets open that up and add some code.

lib/main.js
===========
alert("hello from my_package");

To see our code, run bpm preview --package. The --package flag tells BPM that we're working inside of a package, not a project, as is normally expected. Then open up http://localhost:4020/assets/bpm_libs.js in your browser and you'll see the code that you just added. When you add this package to a project, the code in bpm_libs.js will be integrated into your project's bpm_libs.js.

Step 3: See the Code in Action

So you just built a package, but it's not much fun unless you can actually see it running. To do that, lets create a test.html file in the package root. This won't be included in the final package build, but it's good enough for us to play around with. In test.html put the following code:

<html>
  <head>
    <title>Testing My Package</title>
  </head>
  <body>
    <h1>Testing My Package</h1>
    <script src="assets/bpm_libs.js"></script>
  </body>
</html>

Now open up http://localhost:4020/test.html and you'll see your alert.

Step 4: Add a Package Dependency

While some packages will have no dependencies, in many cases your package will be dependent on other packages. Lets add a dependency to jQuery in our package:

bpm add jquery --package

Again, we have to use --package so that BPM will know to add it to our package instead of looking for a project. I think you'll see a pattern here.

If you look in your package.json now you'll see that jQuery has been added.

Next, lets update our main.js to make use of jQuery:

packages/my_package/lib/main.js
===============================
$('h1').html('Updating from My Package');

Opening up in bpm preview we should see that "Testing My Package" has been replaced with "Updating from My Package".


To learn about testing your package, see Testing Your Package.