In our previous article, we briefly introduced custom attributes, but you might be wondering—what exactly are they and why do they matter? Custom attributes in Oracle APEX plugins are user-defined settings that empower developers to significantly extend and customize a plugin’s behavior, appearance, and functionality. Defined explicitly when creating the plugin, these attributes become part of the plugin’s metadata, enabling flexible, reusable, and dynamic configurations tailored specifically to your application’s needs. In this article, we’ll dive deeper into how custom attributes work, how to define and implement them, and explore practical examples to enhance your Oracle APEX plugins.

Configuration screen in Oracle APEX showing custom attributes such as 'Short text (3 characters)' and 'Label' with details like type, sequence, and required status

Custom attributes like ‘Short text’ and ‘Label’ in Oracle APEX enable developers to add dynamic settings to plugins, enhancing flexibility and usability

Defining Custom Attributes

Custom attributes are defined in the Attributes section of the plugin editor within Oracle APEX. These attributes are essentially placeholders for values or configurations that can be set at runtime. For example, you might define an attribute to control a CSS class, a JavaScript function name, or a specific validation rule.

When creating these attributes:

  1. Assign a name and description to each attribute, which will help developers understand its purpose.

  2. Define the attribute type, such as text, number, or select list, depending on how you intend to use it.

  3. Consider whether the attribute is optional or mandatory.

How They Appear in the User Interface

Once defined, these attributes appear in the Property Editor of the APEX Builder when the plugin is used in an application. The developer using the plugin can configure these attributes by providing values or selecting options based on the attribute’s type and configuration.

Using the Attributes in Code

When implementing the plugin, you’ll reference these attributes in your PL/SQL, JavaScript, or HTML code using their designated identifiers. Each attribute is assigned an internal identifier by APEX, such as P_PLUGIN_ATTRIBUTE_01, P_PLUGIN_ATTRIBUTE_02, and so on. These identifiers correspond to the order in which you create the attributes.

PL/SQL code example in Oracle APEX defining custom plugin attributes such as 'attr_short_text' and 'attr_label' with corresponding attribute types

Oracle APEX PL/SQL code demonstrating the use of custom attributes ‘attr_short_text’ and ‘attr_label’ to define plugin-specific behaviors

For example:

  • If you define a custom attribute for a CSS class, it might be referred to in the rendering code as P_PLUGIN_ATTRIBUTE_01.

  • If you add a second attribute for a JavaScript function name, it will be P_PLUGIN_ATTRIBUTE_02.

It’s essential to keep track of these identifiers to ensure you’re referencing the correct attribute in your plugin logic.

Oracle APEX Page Designer showing a custom plugin setup with an item named P30_TEXT_CUSTOM_VALIDATOR and custom attribute settings for text validation

Configuring the P30_TEXT_CUSTOM_VALIDATOR plugin in Oracle APEX Page Designer, demonstrating the use of custom attributes for dynamic text validation

Best Practices for Using Custom Attributes

  1. Organize and Document: Clearly name and describe each attribute so developers understand their purpose.

  2. Minimize Dependencies: Avoid overloading attributes with complex logic; instead, keep them focused on specific tasks.

  3. Test Thoroughly: Verify that attributes behave as expected when used in the APEX Builder interface and when rendered in the application.

Custom attributes provide a powerful way to make your Oracle APEX plugins flexible and reusable. By carefully designing and leveraging these attributes, you can create highly configurable components that integrate seamlessly into your applications.

This is how we can see, in our example, the custom attributes appearing in the code:

Copy to Clipboard

Explanation of the Code

  1. p_item.attribute_01 and p_item.attribute_02: These are placeholders for the custom attributes defined in the plugin. Oracle APEX automatically assigns these identifiers to attributes in the order they are created during plugin configuration.

  2. attr_short_text and attr_label: These are local variables within the plugin code that map directly to the plugin attributes. By assigning p_item.attribute_01 and p_item.attribute_02 to these variables, the developer ensures they can be referenced easily throughout the plugin logic.

  3. Use Cases:

    • attr_short_text: Could be used for custom messages, short validation text, or placeholder descriptions in an input field.

    • attr_label: Could be used as the label for the input field, dynamically set based on the attribute value.

Now, with a deeper understanding of custom attributes, we can return to the main focus of our article and continue expanding our knowledge of Oracle APEX plugins. This foundational insight positions us perfectly for the upcoming final article in our series, where we’ll integrate advanced client-side JavaScript validation and robust server-side logic, ensuring plugins provide seamless, real-time feedback and a rich user experience. By mastering these essential techniques, you’ll be fully equipped to build dynamic, flexible, and reliable plugins that elevate your Oracle APEX applications to new heights.

For more information, please visit our company website, explore the plugin on APEX World, or check out the source code and documentation on our GitHub repository. Stay updated and feel free to reach out for support or contributions!