Customizing Components

In this Topic

Using the Code Editor Text Box
Changing a Customized Component

You can customize many aspects of a component to make the user interface display information in a way that is more useful to your agency. Features you can customize include which fields are visible or hidden in the component, field types, drop-down menu options, and where on the component different fields are located. You can also add customized agency Help to a component or create an entirely new version of the component.

To customize a component, you must change its presentation metadata. Metadata is essentially data that describes other data. Metadata in the system is presented in XML format.

Note: Future software updates will overwrite the base presentation metadata with the new version. Once you have customized the presentation metadata for a component, future system updates will not overwrite the custom presentation metadata. However, customizations should be evaluated after each software update to ensure that they have not been impacted by deprecated controls and that users have access to any newly added features.

The Component Overview provides access to the presentation metadata for all components in the system. Access the overview by clicking the Components link in the System Administration component. The Component Overview contains two components:

Components, which lists all the base components in the system. This list provides access to the presentation metadata for each component as it was shipped with the application, along with the presentation metadata for components that have agency-wide customizations.
Role Components, which lists all the components in the system that your agency has customized for various user roles, and provides access to the presentation metadata for each customized component. Components in this list are role-specific customizations.

There are two types of component customizations that an agency can create:

Agency component customization — If the change you need to make to a component should be used by all users, you can create an agency-wide component customization by editing the Custom Metadata tab of the base component. All roles in the system will automatically use this custom version of the component.
Role component customization — If you need to make a change to a component that will only be used by certain user roles, you can create a role component by copying the base component and modifying it as needed. You must then assign this custom role component to the user roles that need to use it.

Follow these steps to create an agency-wide component customization:

In the Components component, locate the component you want to customize by typing criteria in the Quick Find search box or click Show first 10.

The system displays a list of rows for all the components in the system that match your search criteria. Each row represents one component and displays an Action button, the component Name, and Agency Help.
When you locate the component you want to customize, click the Name of the component or select Open from the Actions menu on the component row.

The system takes you to the Component Summary, which displays metadata for the component.
Click the Base Metadata tab, and copy all the XML information in the Metadata field.
Click the Custom Metadata tab, and paste the base XML copied in the previous step into the Metadata field.
Edit the text you copied into the Metadata text box on the Custom tab to make the custom changes you want to appear in the component. For more information about using the code editor text box, see Using the Code Editor Text Box.
Click the Save button to save the new agency-wide customization.

All roles in the system will now automatically use this custom version of the component.

Follow these steps to create a role-specific component customization:

In the Components component, locate the component you want to customize by typing criteria in the Quick Find search box or by clicking Show first 10.

The system displays a list of rows for all the components in the system that match your search criteria. Each row represents one component and displays an Action button, the component Name, and Agency Help.
When you locate the component you want to customize, select Copy to Role Component from the Actions menu on the component row.

The system takes you to Metadata tab of the Copy to Role Component component, which displays the base presentation metadata for the component you are copying.
Enter identifying text into the Agency ID field to identify this component. This identifier is used to assign role access to the component after you save the customizations.
Edit the text you copied into the Metadata text box on the Custom tab to make the custom changes you want to appear in the component. For more information about using the code editor text box, see Using the Code Editor Text Box.
Click the Save button to save the new custom role component.

To make this custom role component available to users, it will next need to be associated to the user roles that will use it. For more information, see Assigning Component Access Rights to a Role.

Using the Code Editor Text Box

Code Editor text boxes are available on components where you customize system metadata. Clicking the magnifying glass button on the right side of the text box opens a secondary window that displays XML or IronPython code in numbered rows. This window provides basic code editing features, such as syntax color coding and indentation, in-line error and warning syntax validations, and the ability to expand and collapse elements.

While this window is open, pressing the tab key advances the cursor only within the text window; it will not advance the cursor to other areas of the page. Also, using your browser's search function (CTRL+F) will only search text that is currently visible on the component. To search the entire contents of the text window, click anywhere inside the window and press CTRL+F. A search field for use only in searching the contents of the window appears in the upper right corner of the window.

Changing a Customized Component

Follow these steps to modify an agency-wide component customization:

In the Components component, locate the component you want to change by typing criteria in the Quick Find search box, or by clicking Show first 10.

The system displays a list of components that match your search criteria. Each row represents one component and displays an Action button, the component Name, and Agency Help.
When you locate the component you want to change, select Open from the Actions menu on the component's row or click on the component Name link.

The system takes you to the Component Summary, which displays the current and base presentation metadata for the component.
Edit the metadata in the Custom Metadata tab to make the changes you want in the component. For more information about using the code editor text box, see Using the Code Editor Text Box.
Click the Save button to save your changes in the database.

Follow these steps to modify a role-specific component customization:

In the Role Components component, locate the component you want to change by typing criteria in the Quick Find search box or click Show first 10.

The system displays a rolling list of rows for all the components in the system that match your search criteria. Each row represents one component and displays an Action button, the component Name, and Agency Help.
When you locate the component you want to change, select Open from the Actions menu on the component row or click on the component Name link.

The system takes you to the Role Component Summary, which displays the current presentation metadata for the component.
Edit the metadata to make the changes you want in the component. Edit the text you copied into the Metadata text box on the Custom tab to make the custom changes you want to appear in the component. For more information about using the code editor text box, see Using the Code Editor Text Box.
Click the Save button to save your changes in the database.

To delete a custom role component, locate the component in the Role Components component, and select Delete from the Actions menu on the component row.

For more information and sample exercises, see the System Administration Customization Guide, included in the web-based AASHTOWare Project installation package.