mirror of
https://github.com/kennethreitz-archive/gitx.git
synced 2026-06-05 23:40:18 +00:00
Ben Walding
101 lines
3.9 KiB
Plaintext
101 lines
3.9 KiB
Plaintext
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
|
|
|
|
<img src="GitX://HEAD:Images/new_file.png"> |