---

Editing Plug-ins

This chapter describes how to edit and configure a plug-in.

First create a new document by launching iSync Plug-in Maker; an Untitled document window appears as show in Figure 2-1. If iSync Plug-in Maker is already running, choose New from the File menu. The File menu contains the typical menu items used to manipulate a document. For example, choose File > Save to save an iSync Plug-in Maker document.

By default the edit mode is selected. If not, click the Edit button on the toolbar to begin modifying the plug-in. You can return to the edit mode at any time during the process of developing a plug-in. For example, return to this mode after discovering bugs while testing.

Edit a plug-in by first selecting a category from the Settings outline view that appears on the left. The pane on the right displays the settings for the selected category. Fill in the form on the right to configure the group of settings. The following sections describe these settings in detail.

In this section:

General Settings
Connection Settings
Sync Settings
JavaScript
Modem Script
Advanced Options

General Settings

The settings in this category apply to all types of devices.

Vendor

The Vendor pane contains settings pertaining to vendor information and versioning, as shown in Figure 2-2. The tables following the figure describe the Vendor settings and contain examples.

Device

The Device pane contains settings that are specific to the device, as shown in Figure 2-3.

Connect a USB device to your computer or turn on a Bluetooth device and click the Get Device Info button at the bottom of this pane to automatically fill in some fields with information stored on the device. If you select a Bluetooth device that is not paired, iSync Plug-in Maker pairs the device to access the information. You may be prompted to enter a passkey on the phone and the computer to complete the paring process.

Typically, the GMM string in the AT Identification pane identifies the model and the GMI string identifies the manufacturer, but the device can return any string for these values. For example, the GMI string on Motorola phones might be “Motorola CE, Copyright 2000.“

The tables following the figure describe the Device settings.

Icon

The Icon pane allows you to set icons that represent the device in the iSync user interface, as shown in Figure 2-4. Drop the image files with the corresponding resolution on the image views shown in Figure 2-4 to replace the generic device representations. Your icons should have transparent backgroundd and to support HiDPI screens, be available in all the resolutions that appear on this pane.

Notes

The Notes pane provides a text box for you to insert notes about the plug-in, as shown in Figure 2-5. These notes are visible only in iSync Plug-in Maker—they are not included when exporting the plug-in.

Connection Settings

The USB and Bluetooth options in this section are appear if you specify that the device supports them in the Device pane.

USB

The USB pane covers USB-specific connection settings, as shown in Figure 2-6. The tables following the figure describe the USB settings and discuss options.

Bluetooth

The Bluetooth pane covers Bluetooth-specific connection settings, as shown in Figure 2-7. The tables following the figure describe the Bluetooth settings and discuss options.

SyncML

This pane covers SyncML-specific settings, as shown in Figure 2-8. The tables following the figure describe the SyncML settings and discuss options.

Sync Settings

The Sync Settings category covers settings pertaining to iSync and syncing behavior such as the database, vCal/vCard support, and iSync user interface settings.

Read “Supported Properties” for how to edit the supported field settings on the Contacts, Events, and Tasks panes.

General

The General pane covers settings common to all syncing devices as shown in Figure 2-9. The options in this pane are discussed in the following tables.

Contacts

The Contacts pane covers settings specific to the Contacts database, as shown in Figure 2-10. The options in the Contacts pane are discussed in the tables following the figure. Read “Supported Properties” for how to edit the Supported Properties section.

Events

The Events pane covers settings specific to the Events database, as shown in Figure 2-11. The options in this pane are discussed in the tables following the figure. Read “Supported Properties” for how to configure supported properties.

If the device supports recurrent events then select the "Device supports vCal recurrences" option in the Recurrence Support section of this pane. Then click the Configure button to set the recurrence options. A sheet appears as shown in Figure 2-12. Use this sheet to configure the details of what recurrence rules the device supports.

The table and layout on the recurrence sheet is similar to the Advanced Options pane. Select a row in the table to display a description of the option in the view at the bottom of this sheet. If a value is one of several options, select the appropriate option from the corresponding pop-up menu. Otherwise, double-click in a cell in the Value column and type in the value.

Tasks

The Tasks pane covers settings specific to the Tasks database, as shown in Figure 2-13. The options in these panes are discussed in the tables following the figure. Read “Supported Properties” for how to configure supported properties.

Supported Properties

Each of the schema panes—the Contacts, Events, and Tasks panes—contains a Supported Properties section at the bottom of the pane that allows you to turn on or off properties of records that you want to sync. You can also configure the length of string values and configure other property-specific options. Some of the options pertain to reformatting records that are pushed to the device. In summary, you can use the Supported Properties section to specify a subset of the standard Apple schemas that the device supports. Only the properties and values you specify in the Supported Properties section are synced to the device.

The Supported Properties section contains a table like the one shown in Figure 2-13. The Property Name column contains the names of the properties of each corresponding entity defined in an Apple schema. For example, “First name” and “Last name” are properties of the Contact entity in the Contacts schema. When you create a new iSync Plug-in Maker document, all of the properties are enabled representing a full-featured device. Deselect the properties you want to disable. Some properties are mandatory and therefore, cannot be disabled.

Some properties are relationships to other entities. For example, the “Street addresses” and “Related name” properties are to-many relationships from the Contact entity to the “Street Address” and “Related Name” entities respectively. Click the triangle to the left of an option to view the properties of a relationship. For example, click the “Street addresses” property in the Contacts pane to reveal and configure the City, State, and “Postal code” properties as shown in Figure 2-14.

The Type column in the Supported Properties table displays the property type for each attribute—relationships do not have an attribute type. For example, an attribute type might be String, Date, or Image. If the type is Label, the attribute is one of several values, as in an Address Book label, such as “work”, “home”, or “other.“

The Max Length column displays the maximum length of a string field—specifically the maximum number of characters in a String value. Double-click the cell in this column to change the maximum number of characters supported by the device. iSync reformats records pushed to the device to fit in the specified string size.

Click the More button in the Options column to configure more details about a field. For example, click the More button for an attribute of type Label to select the possible labels the device supports. A More button is disabled if an attribute has no options or is not enabled. Relationships do not have a More button. The following sections describe the type-specific sheets that appear when you click the More button.

String Types

Figure 2-15 shows more details about a String attribute type. This sheet allows you to control the format of string attributes that are pushed to a device.

Select the “Allow all characters” option if there are no restrictions on the content of a string attribute.

Select “Remove forbidden characters” if you want selected characters removed from a string pushed to the device. If you select this option, enter the forbidden characters, without any separators, in the adjacent text field. For example, enter ;., to remove semicolons, periods, and commas from the string.

Select “Accept only allowed characters” if you want to limit the characters in a string to those entered in the adjacent text field.

Select “Use default value for empty attribute” if you want to specify an alternate string for an empty attribute. If this option is selected, enter the alternate string in the adjacent text field.

Click Done to apply your changes or Cancel to revert to the previous settings.

Label Types

Figure 2-16 shows the labels of an attribute of type Label for the “Email address type” attribute of an Email Address entity. The table at the top of this sheet contains the supported Mac labels and corresponding vCard values.

You use this sheet to specify the supported labels and may limit the number of email addresses or phone numbers allowed on the device. Click a checkbox in the “Sync this type” column to disable or enable a label displayed in the “Mac value” column. Only records with enabled labels are synced to the device.

You can also use this sheet to change the mapping of Mac labels to vCard types—for example, vCard phone types such as HOME, WORK, CELL, and FAX. Change a mapping by double-clicking a cell in the “vCard value” column and typing in a vCard type. You can leave a vCard value blank if the device doesn’t support the Mac value and you want to sync the record without syncing the vCard type.

You can map multiple labels to a single vCard type as shown in Figure 2-16 where both the work and other labels are mapped to the WORK vCard type. When multiple labels are mapped to the same type, the order of the rows in this sheet determines the value that is used when transforming device records to computer records. For example, if a phone number is created on the device with a vCard value of WORK, it will be mapped to the computer label work because it appears before other in the table on the Label More button sheet. Drag and drop the rows in this table to change the order.

Use the controls below the table to limit the number of records in the corresponding to-many relationship—for example, limit the number of targets of the to-many relationships from Contact to Phone Number or Contact to Email Address. In other words, you can limit the number of phone numbers or email addresses per contact that are synced to the device. Select the Unlimited option if the device as no limits. Select the “Limit to” option and enter the number of records the device supports for the corresponding to-many relationship. Select the “One per type” option if the device only supports one record per vCard type.

Click Done to apply your changes or Cancel to revert to the previous settings.

Enumerated Types

Figure 2-17 shows an Enumerated attribute type details sheet for the Tasks database Status field. The table at the top of this sheet behaves similar to the table at the top of the Label More button sheet, except that you can not disable Mac values.

Change a mapping from a Mac value to a vCal value by double-clicking a cell in the “vCard value” column and typing in a vCard value. You can leave a vCard value blank if the device doesn’t support the Mac value and you want to sync the record without syncing the vCard value. You can map multiple Mac values to the same vCal value. Drag and drop a row to change the search order for a Mac value when transforming vCal records to computer records.

Click Done to apply your changes or Cancel to revert to the previous settings.

iSync UI

The iSync UI pane, shown in Figure 2-18, allow you to configure the user interface in iSync based on what the device supports. The user interface features are organized by schema. Currently, there are only Contacts and Events user interface options. Each of these settings corresponds to a control in the iSync user interface.

Use these settings to set whether an option is visible to the user in iSync and set its default value. All of the Contacts and Events controls on this pane correspond to a control on the More Options pane in iSync. A preview of all the options is provided at the bottom of this pane so you can see what the iSync user interface looks like. If an option is not visible, then iSync uses the default value for all records sent to the device. If an option is visible, the associated control displays the default value in the More Options pane in iSync.

Use the settings on this pane cautiously. The iSync user experience should not change too much from device to device. New plug-ins should show the same user interface controls as those shipped by Apple. Therefore, seriously consider removing or adding controls to iSync before doing so. If you remove a control, carefully choose a default value because the user can not change it after the plug-in ships.

The options in the Events section, described in Table 2-22, let you configure how events are synced to a device. The checkbox and pop-up menu settings allow you to filter events by a time interval. For example, if the device has limited capacity, you can filter the number of events synced to the device by a time interval. Set the default value of the "Don't synchronize events prior to" and the "Don't synchronize events after" checkboxes to On. Also, deselect Visible in iSync (located at the right side of the pane) for these options so the user can’t sync all events. Select the appropriate default interval values for the corresponding pop-up menus that range from one day to one month. Optionally, select Visible in iSync for the pop-up menu options if the user is allowed to change these settings.

JavaScript

Click JavaScript in the outline view to optionally edit any of the JavaScript functions used to communicate with the device. The JavaScript pane is shown in Figure 2-19. These are the same JavaScript functions that you can access from the Connection > USB and Connection > Bluetooth panes. The table in the upper-left corner of the JavaScript pane contains groups of JavaScript functions. Use this table to navigate to the JavaScript function you want to edit. For example, reveal the contents of “USB functions” and select On OBEX Connection. The Run column in this table displays Yes if the JavaScript function is enabled, and No if it is disabled.

The Description table in the upper-right corner of the JavaScript pane displays a brief description of the JavaScript function. The description states what the JavaScript function does and when it is executed.

The text box at the bottom of the JavaScript pane displays the selected JavaScript function. Use this text box to edit the JavaScript function. The behavior of this editor is similar to that of the TextEdit application. Just click anywhere in the text box to begin typing. Read iSync JavaScript Reference for how to write iSync JavaScript functions.

Click the Revert to Default button at the bottom of the pane if you want to revert to the system default settings—this action deletes your changes. Click the Check Syntax button to correct any syntactical errors in your JavaScript code.

Modem Script

A modem script is used to communicate with and control the device as a modem for the purpose of connecting to the Internet. Modem scripts are written using the Communication Command Language (CCL) scripting language. Use the Modem Script pane shown in Figure 2-20 to configure modem options and write a CCL script. Table 2-23 and Table 2-24 describe the various settings on this pane to configure the connection and carrier. Table 2-25 describes how to import and edit a modem script.

Read CCL Modem Scripting Guide for details on CCL.

Advanced Options

The Advanced Options pane, shown in Figure 2-21, contains additional options that are infrequently used. Use this pane to configure device-specific options. For example, use this pane to specify how a record is reformatted from an Apple record to a vCard or vCal property field used by the device. Use this pane if your device uses different vCard or vCal properties than the defaults.

The options in this pane are displayed in a table and organized in a way that is similar to key-value pairs in a property list. The property/option is listed in the Options column and the value is listed in the Value column. Use the Filter pop-up menu located above the table to filter the options by category. Use the search field to the right of the Filter menu to search for a specific option by name.

Select a row in the table to display a description of the option in the view at the bottom of this pane, as shown in Figure 2-22.

If a value is one of several options, select the appropriate option from the corresponding pop-up menu. Otherwise, double-click in a cell in the Value column and type in the value.

Some Value cells contain an Edit button. Click the Edit button to specify key-value pairs that map iSync property names to device property names. A sheet appears as shown in Figure 2-23. Click the plus button in the lower-left corner of sheet to add a key-value pair. Click in the “iSync property” column to enter the iSync property name that you are mapping. Click in the “Phone mapped property” column to enter the corresponding device property name.

---