Gear configuration pages enable the gear developer, portal administrator, community leader, or portal user to customize various aspects of the way the gear works.
There are four types of gear configuration, each of which has a corresponding gear mode:
Install Configuration | High-level administrative customization; default values of gear parameters (for example, determining whether a gear will be configurable at lower levels or specifying a source for a content feed). Install configuration is available only to Portal Administrators and is displayed in the Portal Administration. |
Initial Configuration | Options that are set when the gear is first created in a community. Typically, these are set by the community leader. The initial configuration page for a gear is displayed in the Community Administration. |
Instance Configuration | Administrative customization options, which configure a gear for a particular community. Often these are gear appearance or community membership settings. Typically, these are set by a community leader. The instance configuration page for a gear is displayed in the Community Administration. |
User Configuration | Gear personalization options (for example, selecting stock ticker symbols in a stock ticker or ZIP Codes in a weather gear). These are always set by portal end users The user configuration page for a gear is displayed in the portal community page. |
All four configuration types are used for setting gear parameters and can be used for any additional configurations you need in your gear. All types are optional; if you do not create a configuration page for one of the types, then no link will be created to go to that mode.
Gear parameters are defined in the gear manifest XML file as in the example below. (For information on the gear manifest XML file format, refer to the Gear Packaging and Deployment chapter of this manual.) Gear parameters all must have String names and String values but the String values can be parsed into whatever type you want at the time you use them. In the following example, the value is parsed into an int when it is needed.
<parameter name="maxFileSize"> <default-value> 1 </default-value> </parameter>
Note that in some cases, different configuration modes can reuse similar configuration files. In many situations, you can use the same code when a gear is created (Initial Configuration) as when changing configuration parameters thereafter (Instance Configuration).
ATG Portal includes a form handler class named atg.portal.framework.GearConfigFormHandler that is useful in making many configuration pages for gears. The GearConfigFormHandler can set user gear parameters and instance gear parameters, and it can set default values or override values. You can subclass GearConfigFormHandler to provide other configuration functionality. See the ATG Platform API Reference for atg.portal.framework.GearConfigFormHandler for more information about using this class. See also the examples that use GearConfigFormHandler in the next few sections.
