Introduction ============ A lot of the display code in GitX is based on the HTML views that are rendered by WebKit. As such, it's necessary to access a lot of information from WebKit that is only available in the Objective-C environment. Because of this, some convenience methods have been added. Most notably, some objects can be accessed completely from WebKit, including: * All webcontrollers * All PBGitRefs and PBGitCommits All WebKit views should be controlled by a subclass of PBWebController. Subclassing PBWebController =========================== PBWebController does some magic to make using it easier. First of all, it automatically loads in the view specified by "startFile". This means that your views have to conform to a specific structure. For example, if you set startFile (in your awakeFromNib) to "commit", there should be a file named html/views/commit/index.html that will get loaded. Furthermore, the controller keeps a finishedLoading member that indicates whether or not the webview is ready to be used. If it is ready, and your subclass has implemented the didLoad method, that method will be called. After the document has successfully loaded, the controller inserts itself into the Javascript environment under the "Controller" variable. Useful PBWebController functions ================================ There are some functions that might be useful in any context. These are put in the PBWebController class for easy access. To access these, replace the colons with underscores in the JS call. for example, - (void) log:(NSString) logMessage would be called in JS by: Controller.log_("Hello from javascript!"); ## - (void) log:(NSString) logMessage This method simply relays a JS message to the program, which outputs it using NSLog. Handy for debugging. ## - (BOOL) isReachable:(NSString *)hostname Will return true if the hostname is reachable from Javascript without creating an internet connection (for example, dialup). This is useful for optional features that depend on a working internet connection. ** NOTE ** The GitX JS environment is _NOT_ secure, which means that external HTTP calls should only be made to trusted sites. For example, DON'T open any link in a commit message, as this could potentially allow any site to run any command on your mac. ## - (void) runCommand:(WebScriptObject *)arguments inRepository:(PBGitRepository *)repository callBack:(WebScriptObject *)callBack This somewhat specific function allows you to call any git command and have its output returned to a callback function. For example, the following: Controller.runCommand_inRepository_callBack_(["--version"], obj.repository, function(v) { notify("Git Version: " + v, 1); }); will show a notification displaying the current git version. This method is async, which means that it doesn't matter if it takes a long time to run. ## - (void) callSelector:(NSString *)selectorString onObject:(id)object callBack:(WebScriptObject *)callBack While you can have direct access to most objects, sometimes it is useful to have an async task, for example if the operation can take a long time. Use this function to keep the UI responsive. Loading files from WebKit ========================= All views that have a subclass of PBWebController set as ResourceLoadDelegate (this happens automatically if you assign a view to your controllers) gain access to the GitX:// protocol. This protocol allows you to load in blobs from the repository. The format is as follows: GitX://REVISION/path/to/file Which means that revision can't have a path separator in it (so HEAD is valid, but pu/pb/fix_it is not). You also can't just pass on a blob oid. These things will probably be fixed in future revisions of the protocol. What this allows you to do, for instance, is to display images that have changed. For example, if you want to show the new file from a diff, you can use something like