Understanding the Salsa Developer Toolkit: Projects

When you sign up for a Salsa Developer Account, what you're really getting is a basic Salsa organization account, with an important difference - the Developer Tools package. Here we discuss the concept of Projects and how it affects the way you code in Salsascript.

What is myapp? (aka Understanding Package Structure)

When you create a project via the Salsa Developer Tools package, you will be given a repository path, for example:

Repository path: git@git.salsalabs.com:project2/project2.git

First, get yourself set up to use git locally:
  1. create your SSH key
  2. tell gitorious about your SSH key
  3. set your .gitconfig filler in $HOME
More details on the process can be found in our Using GIT documentation.

You can then clone your new project locally by running:
home-computer:~ local-git-directory$git clone git@git.salsalabs.com:project2/project2.git
This will create a local repository in the local-git-dir directory of your local computer called project2.

Inside project2 you will find a skeleton code base you can work off of, based in the myapp directory.

You can rename myapp to whatever make sense for your package, just remember that it will influence the URI to your package in the Salsa HQ. So if you want to rename mmyapp to killerapp, using bash this would look like:
home-computer:~ local-git-directory$ cd project2
home-computer:~ project2$ mv myapp killerapp
home-computer:~ project2$ git status
# On branch master
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# killerapp/
home-computer:~ project2$git add killerapp/
home-computer:~ project2$ git status
# On branch master
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# new file: killerapp/WEB-INF/package.xml
# new file: killerapp/index.sjs
# new file: killerapp/public/WEB-INF/package.xml
# new file: killerapp/public/index.sjs
#
home-computer:~ project2$git commit -a -m "renaming myapp to killerapp"
home-computer:~ project2$git push origin master
Then path to your package in Salsa would be:
https://sandbox.salsalabs.com/salsa/hq/p/d/project2/killerapp/
instead of:
https://sandbox.salsalabs.com/salsa/hq/p/d/project2/myapp/
this also change what you will use for your final production packageId:
d.project2.killerapp
instead of:
d.project2.myapp
Using subdirectories within your project will allow you to do different release versions and/or separately installable components of an overall package.

Understanding WEB-INF

You will notice that in your originally-named myapp directory, a sub directory named WEB-INF. You will need a WEB-INF directory for any directory where you want to make pages available to either a) campaign managers or b)the general public. In WEB-INF you will want a file called package.xml. This will define important elements of the parent (in this example killerapp) directory. These rules will be inherited by the subdirectories of killerapp if the subdirectory does not have a WEB-INF and corresponding package.xml of its own.

Understanding package.xml

We'll start with a directory of code to be used by campaign managers in Salsa's HQ (Headquarters). Campaign Managers are the administrators of the organization's account. By logging into the Salsa HQ, a campaign manager can create and configure the different components of Salsa such as an Email Blast, Fundraising Campaign, or Event. Here is an example of a package.xml page that defines a directory of code that is to be available to campaign managers via the Salsa HQ.
<?xml version="1.0" encoding="utf-8"?>
<package permissionType="hq" name="Sample Package">
<tabs>
<tab name="project2<BR/><span>package</span>" colorscheme="7">
<links>
<link name="Home" href="index.sjs"/>
<link name="Sample Links">
<sublink name="Ali's Test" href="http://dev.salsacommons.org" target="_blank"/>
<sublink name="Salsa Commons" href="http://salsacommons.org/"/>
</link>
</links>
</tab>
<tab parentId="salsa.event.common.hq">
<links>
<link href='/salsa/hq/p/d/project2/myapp/dosomestuff.sjs' name="Ali Event Link 2"/>
</links>
</tab>
</tabs>
</package>

Components of package.xml:

  • package permissionType: "hq" or "public"
    • 'hq': Available to only those logged into the Salsa Headquarters as a campaign manager for an organization that has d.project2.killerapp installed.
    • 'public': Available to anyone who has an internet connection
    For more discussion on permissionTypes, check out Part II - Creating a Packageof this Tutorial.
  • Tab element
    • tab name: this is the title which will be displayed in the new tab you are defining
    • tab colorscheme: color schemes are currently defined from 0 to 9, change this to change the background/font color/etc for your package
    • tab parentId: if you don't want to create an entire new tab, but do want to create navigation links in existing package tabs, specify the packageId of the tab in which to add the nav links. You can determine the packageId by the URI, for example, when a campaign manager clicks the Events tab, the resulting URL is:
      https://sandbox.salsalabs.com/salsa/hq/p/salsa/event/common/hq/
      hence the packageId for the parentId parameter of tab is salsa.event.common.hq (everything after .../p/)
  • Link element
    • links: lists the nav/subnav links within the package you would like to define
    • link/sublink name: String of the nav/subnav
    • link/sublink href: location of page for the link/sublink