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. I've recently expanded it to compile directly to the API, but still use the Migration Tool for getting projects and compiling entire projects. All of the "old" build paths are there, but I generally use Quick Compile 99% of the time at home.

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

You may also wish to check out MavensMate, a ForceDotCom bundle for TextMate created by Mavens Software. It has some extremely pretty interfaces and some great functionality: https://github.com/joeferraro/MavensMate

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, download "ForceDotBundle_beta.zip". Double click "ForceDotBundle.tmBundle" after unarchiving.

Installation from Finder

Fork/download/clone the project. Rename the parent folder "ForceDotBundle.tmBundle" and double click it.

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
     • Quick Compile: Compiles the current file against the API, bypassing the Migration Tool. Much faster. Only gives a tool tip in response, so sometimes still go back to Build File for better error reading.
     • 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".
  9. Run Apex: Takes the highlighted code and runs it against the API. Opens a new file to display the results.

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".