Documentation/CallingFromWebKit.txt

   1 Introduction
   2 ============
   3
   4 A lot of the display code in GitX is based on the HTML views that are rendered
   5 by WebKit. As such, it's necessary to access a lot of information from WebKit
   6 that is only available in the Objective-C environment.
   7
   8 Because of this, some convenience methods have been added. Most notably, some
   9 objects can be accessed completely from WebKit, including:
  10
  11         * All webcontrollers
  12         * All PBGitRefs and PBGitCommits
  13
  14 All WebKit views should be controlled by a subclass of PBWebController.
  15
  16
  17 Subclassing PBWebController
  18 ===========================
  19
  20 PBWebController does some magic to make using it easier. First of all, it
  21 automatically loads in the view specified by "startFile". This means that
  22 your views have to conform to a specific structure. For example, if you set
  23 startFile (in your awakeFromNib) to "commit", there should be a file named
  24 html/views/commit/index.html that will get loaded.
  25
  26 Furthermore, the controller keeps a finishedLoading member that indicates
  27 whether or not the webview is ready to be used. If it is ready, and your
  28 subclass has implemented the didLoad method, that method will be called.
  29
  30 After the document has successfully loaded, the controller inserts itself into
  31 the Javascript environment under the "Controller" variable.
  32
  33 Useful PBWebController functions
  34 ================================
  35
  36 There are some functions that might be useful in any context. These are put in
  37 the PBWebController class for easy access. To access these, replace the colons
  38 with underscores in the JS call. for example,
  39
  40         - (void) log:(NSString) logMessage
  41
  42 would be called in JS by:
  43
  44         Controller.log_("Hello from javascript!");
  45
  46 ## - (void) log:(NSString) logMessage
  47
  48 This method simply relays a JS message to the program, which outputs it using
  49 NSLog. Handy for debugging.
  50
  51 ## - (BOOL) isReachable:(NSString *)hostname
  52
  53 Will return true if the hostname is reachable from Javascript without creating
  54 an internet connection (for example, dialup). This is useful for optional
  55 features that depend on a working internet connection.
  56
  57 ** NOTE ** The GitX JS environment is _NOT_ secure, which means that external
  58 HTTP calls should only be made to trusted sites. For example, DON'T open any
  59 link in a commit message, as this could potentially allow any site to run any
  60 command on your mac.
  61
  62 ## - (void) runCommand:(WebScriptObject *)arguments
  63           inRepository:(PBGitRepository *)repository
  64               callBack:(WebScriptObject *)callBack
  65
  66 This somewhat specific function allows you to call any git command and have
  67 its output returned to a callback function. For example, the following:
  68
  69 Controller.runCommand_inRepository_callBack_(["--version"], obj.repository,
  70              function(v) { notify("Git Version: " + v, 1); });
  71
  72 will show a notification displaying the current git version. This method is
  73 async, which means that it doesn't matter if it takes a long time to run.
  74
  75 ## - (void) callSelector:(NSString *)selectorString
  76                 onObject:(id)object
  77                 callBack:(WebScriptObject *)callBack
  78
  79 While you can have direct access to most objects, sometimes it is useful to
  80 have an async task, for example if the operation can take a long time. Use
  81 this function to keep the UI responsive.
  82
  83 Loading files from WebKit
  84 =========================
  85
  86 All views that have a subclass of PBWebController set as ResourceLoadDelegate
  87 (this happens automatically if you assign a view to your controllers) gain
  88 access to the GitX:// protocol. This protocol allows you to load in blobs from
  89 the repository. The format is as follows:
  90
  91         GitX://REVISION/path/to/file
  92
  93 Which means that revision can't have a path separator in it (so HEAD is valid,
  94 but pu/pb/fix_it is not). You also can't just pass on a blob oid. These things
  95 will probably be fixed in future revisions of the protocol.
  96
  97 What this allows you to do, for instance, is to display images that have
  98 changed. For example, if you want to show the new file from a diff, you can
  99 use something like
 100
 101         <img src="GitX://HEAD:Images/new_file.png">