PluginCreation

Introduction

You may want to create your own function to add new features to Hello IT or replace existing features.

Functions are identified by a unique string like "public.open.application". The associated implementation is looked for in:

• The PlugIns folder of the application itself;
• /Library/Application Support/com.github.ygini.Hello-IT/PlugIns;
• ~/Library/Application Support/com.github.ygini.Hello-IT/PlugIns; and loaded in the same order.

If you place your own implementation of public.open.application in your own Library folder, it will be used instead of the default one.

HITDevKit framework

A framework is built-in the application to allow easy development of new plugins.

It contains basic classes for easy implementation of all kind of scenarios. Original plugins use the DevKit, so you can look at existing plugins to understand how to use it.

Classes to subclasses

Some interesting base classes to subclass are in the DevKit.

HITBasicPlugin

Do nothing except initializing the class with the right API required by HITPluginProtocol and calling the -prepareNewMenuItem method on itself at the first menuItem usage (lazzy loading).

You've to implement -prepareNewMenuItem in your own subclass of HITBasicPlugin.

HITSimplePlugin

Subclass of HITBasicPlugin. It make a default implementation of prepareNewMenuItem which creates a NSMenuItem using the title key of plugin settings and links the action to -mainAction:(id)sender.

You must implement -mainAction:(id)sender in your own subclass to catch user actions.

HITAdvancedPlugin

Subclass of HITSimplePlugin. It add to HITSimplePlugin the management of testState value with automatic update of GUI.

If you've to indicate a state (none, OK, warning, error, unavailable) you just have to update self.testState from your subclass.

HITPeriodicPlugin

Subclass of HITAdvancedPlugin. It add two a method -periodicAction:(NSTimer *)timer in addition to -mainAction:(id)sender.

mainAction: will still be used to manual action by user.

periodicAction: will be called by the plugin timer.

The timer is set via the repeat key from the plugin settings. The repeat value must be > 0.

Create a new plugin

To create a new plugin, you need to create a new Cocoa bundle for OS X in Xcode (as a new project). When you setup the project, you must set hitp as bundle extension.

Then, in project build phases you need to add the HITDevKit framework as a library to link with. The framework is located inside the Hello IT application bundle and you don't need to copy it in your own plugin.

In Build Settings you must update the Installation Directory to be /Library/Application Support/com.github.ygini.Hello-IT/PlugIns or ~/Library/Application Support/com.github.ygini.Hello-IT/PlugIns.

Then, you must create a new Cocoa class. It's recommended to subclass one base class from HITDevKit framework instead of working directly with NSObject.

When you new class is created, you need to edit the target info and specify the name of your new class as Principal Class.

In the same info pane for your target, you need to add a new value called HITPFunctionIdentifier, the associated value will be the function identifier for your new feature.

To simplify your development, it's recommended to unfold the Installation Directory settings and set /Library/Application Support/com.github.ygini.Hello-IT/PlugIns for Release and ~/Library/Application Support/com.github.ygini.Hello-IT/PlugIns for Debug. Then you've to set the Skip Install settings to NO for debug.

Like that, you will be able to install your plugins for debug purpose in your own session by bulling the plugin in Xcode.

To allow you to run and debug your plugins, you need to edit your building scheme. Go in Product menu > Scheme > Edit Scheme. Then, select the Run task on the left side and the in the Info panel in the center of the window, change the Executable value and set it to your Hello IT.app copy (no need of special version for that, the published one is OK).

Now you can build your plugins, set some breakpoints and run the app with your plugins inside.

Don't forget to update your applications settings according to your needs to use your new plugins.

Network related plugin

If your plugin check something related to the network, you may want to make a difference between a test failure and a computer without any network connection.

To handle that, the HITDevKit framework offer a global network state management. To use this system you must implement two methods. One to indicate that your plugin need general network informations and an other to actually get network updates.

- (BOOL)isNetworkRelated {
    return YES;
}

- (void)generalNetworkStateUpdate:(BOOL)state {
    // Do anything you want with the network state.
    // YES means local network connectivity
}

You might want to set your status indicator to HITPluginTestStateUnavailable when the network state update say NO.

A complete example can be found in HITPTestHTTP source code.