ForceDotBundle

This project is the end result of cleaning up some shell scripts I had been tinkering with for using with the Force.com Migration Tool and the OS X editor TextMate. It has templates for Apex and Visualforce and offers a few options for building and testing code, easy HTML links into things like the Apex System Log (to execute anonymous code), along with access to a couple of REST API features to run SOQL and get object definitions.

I've got videos on using the bundle on YouTube: http://www.youtube.com/joshuabirk

This is unofficial software and unsupported as well. I've been able to keep up with updates and bug fixes so far, but make no promises.

Requirements

You will need to download and setup the Force.com Migration Tool, which is fairly straightforward in OS X. Just go to "Setup -> Develop -> Tools" in your org and download the zip and follow the instructions. You might need to run "ant -diagnostics" to find your ant lib directory.

Installation from Downloads Page

If you go to the Downloads page, there is a zip file. Downloading and unarchiving that should result in a folder with this file, an "install.command" file and a folder named "ForceDotBundle". If you have the CLI command for TextMate installed, you should just be able to double click "install.command". Otherwise, after running "install.command", you will need to double click the now renamed parent directory.

Installation from Finder

Fork/download/clone the project. Make sure the resulting folder is named "ForceDotBundle" and rename it if needed. Go into that folder and double click "move_tools.command" (icon looks like a document with a black box). If you have the CLI command for TextMate installed, you should just see the bundle loaded up. Otherwise double click the now renamed parent directory.

Installation from Shell

There is a shell script "move_tools.sh" now. Make sure the resulting folder is named "ForceDotBundle". Run that script and it should move the Tools directory into TextMate, rename the parent directory to have ".tmBundle" and if you have the mate CLI command installed, install it into TextMate. Otherwise, double click on the now renamed directory.

Manual Installation

If the move_tools.sh file won't run for some reason, you can replicate the steps by:

1. Downloading or forking the project to a local folder.
2. Go into the folder, copy the "Tools" directory.
3. Go back to the parent folder. Rename "ForceDotBundle" (or whatever the result parent dir was) to "ForceDotBundle.tmBundle".
4. Double click the renamed directory. TextMate should run and confirm it was installed.
5. Go to "~/Library/Application Support/TextMate/Bundles" (note this is off your user directory).
6. Right click on "ForceDotBundle.tmBundle" and select "Show Package Contents".
7. Paste "Tools" into the now opened package.
8. Now to Terminal and run the following:

   	chmod -R 775 ~/Library/Application\ Support/TextMate/Bundles/ForceDotBundle.tmbundle/Tools
   	

Quick Start

1. Once you've installed the bundle, create a new project.
2. Create a new directory in Finder, name it something reasonable for your project.
3. Drag the folder to the project pane in TextMate.
4. Create some kind of scratch file.
5. Open the empty file. Now use "Create New Project" from the ForceDotBundle bundle. A popup will give the overview of the changes. These changes may not appear right away in the project pane. They will be in Finder.
6. Update "build.properties" with your username, password and if needed, the login URL (for sandboxes).
7. If you want to pull down existing files, run "Get Latest". These changes may not appear right away in the project pane. They will be in Finder.
8. Or if you just want to be additive, right click on say, classes, and use one of the templates.
9. Enjoy.
10. You may need to whitelist your IP for some of the features.

Enabling Keychain Support

ForceDotBundle will swap out the password in build.properties with secured text in OS X's keychain if you have set:

usekeychainaccess=enabled

in build.properties. The next step is swap out your password with "password:accountname", highlight that text and then run "Add Password" under the Keychain menu in the bundle. There will be some keychain prompts and then your password will be replaced with just "accountname".

From there on out, the bash will swap out your password in build.properties when it runs a build, and then swap it back when it is done. I highly recommend this for everyone concerned with having passwords in a text file on your laptop. Which should be everyone. The only downside is with multiple builds that execute against build.properties at the same time may wipe the file out. Working on it.

Using the REST functions (SOQL, Object Describe)

Since these use the password grant type, you will likely need to either append your security token to the password, or whitelist your IP.

Enabling OAuth login for REST

Not sure if this should be the only source of login or not - but if you want to try using the OAuth endpoints to login instead of SOAP, add "consumerkey" and "privatekey" to build.properties with your Consumer Public and Consumer Secret from a Remote Settings entry.

Features

The bundle provides the following:

• Languages
  1. Apex
  2. Visualforce
• Templates
  1. Apex Class
  2. Apex Trigger
  3. Visualforce Page
  4. Visualforce Trigger
• Commands
  1. Create Project
     • Start New Project: this command will generate a skeleton directory structure, a tmp directory and dummy build files (build.properties, package.xml, build.xml). Update build.properties to associate the project with your org.
     • Get Latest: this will bring down all the code and components from the org
  2. Build Files
     • Build File: this will build the current file being edited
     • Build All: this will build all the files in the project
     • Build Sequential: You can have multiple manifest files named "1.manifest", "2.manifest", "3.manifest", etc. The command will go through them in order and build the corresponding files, allowing you to perform builds in steps. The format for the manifest file must be:

       					apex=AccountList,RESTCaseController
       					pages=AccountTest,SomePage
       					components=AComponent,BComponent
       					triggers=
       				

       
       And they should be in the project folder root.
     • Build Latest: This will build all the files which have been modified in the last 24 hours.
  3. Run Tests
     • Run Tests: this will run all tests against the org
     • Run Current Tests: this will run the tests on the currently open file
  4. REST Operations
     • Get Object: Opens an HTML window describing the fields and child relationships of an object defined by the currently highlighted text.
     • Run SOQL: Opens an HTML window with the results of the SOQL query in the currently highlighted text.
     • Note: you need the pod variable defined in build.properties for this to work
  5. Bookmarks
     • Go To Visualforce Page: Opens the VF page of either the currently open document or highlighted text
     • Go To Record: Opens the page corresponding to the ID of the currently highlighted text
     • Execute/Debug Apex: Opens the system log
     • New Custom Object: Opens the Custom Object wizard
     • Custom Labels: Opens the Custom Labels page
     • New Debug Log: Opens the page to add a new debug log/user
     • Debug Logs: Opens the Debug Logs page
     • Apex Reference: Opens the Apex reference documentation
     • Visualforce Reference: Opens the VF component reference documentation
     • Logout: Logs out the current web session
     • Note: you need the pod variable defined in build.properties for this to work
  6. Deploy To Production
     • Production Test: This will do a check only, run all tests, deploy against the production org
     • Production Deploy: This will run all tests and deploy against the production org
  7. Keychain
     • Add Password: Highlighted text in the format "password:accountname" will add a new password to Keychain under accountname and replace the text with accountname.
     • Lock Keychain: Locks keychain and requires a password for later use.
  8. Delete Except: This command will delete all the classes, pages, components and triggers from the local project folder unless they include the highlighted text in their filenames. This is case sensitive, and obviously suggested to save and build before latest ... there is no undo. Only for the brave but handy for people with large orgs looking only for projects which started with "something".

Using Keychain

For better production, you can now store your passwords in OS X Keychain and refer only to the Keychain account name in build.properties.

1. Make sure "usekeychainaccess" is set to "enabled" in build.properties.
2. Set "{realpassword}:{keychainaccountname}" as the password.
3. Go to Bundles->ForceDotCom->Keychain Access->Add Password.
4. If successful, the text will be replaced with just the {keychainaccountname}.

Using REST and HTML bookmarks

Set "pod=" in build.properties to match the beginning of the URL in your Salesforce org domain. For instance, if after you login you see "https://na8.salesforce.com" - set it to be "pod=na8".