Introduction
When working with Oracle APEX templates, maintaining clarity and structure is essential for long-term maintainability. APEX supports inline comment syntax using {!<comment-text>/} to help developers add helpful notes or disable parts of the template code during development. These comments are not rendered in the final HTML output, making them ideal for documentation or temporary code exclusion without impacting the UI.
How to Use APEX Comments with Syntax {!<comment-text>/}
Oracle APEX provides a simple and effective way to insert comments directly into template text using the {! ... /} syntax. These comments are processed at the APEX rendering layer and are not passed to the browser or client-side.
Example Use Case
Suppose you're designing a custom card template and want to mark where a new feature will be added later:
<div class="card-header">
<h3>{TITLE}</h3>
{!This is where we may insert an icon later/}
</div>
This comment will be ignored during rendering and will not appear in the page source. It’s useful for leaving developer notes without cluttering the UI or exposing implementation notes to end users.
Commenting Out a Directive Block
You can also comment out portions of APEX directives to temporarily disable them without removing them from the template:
{!{if STATUS = 'NEW'}
<span class="badge">New</span>
{endif}/}
This allows you to preserve logic while disabling it during testing or iterative design.
Best Practices
-
Use
{!.../}comments to document complex logic in template code for better team collaboration. -
Avoid overusing comments in production templates—clean and readable code is better than excessive commentary.
-
Do not use HTML-style comments (
<!-- -->) in APEX template directives, as these may not behave consistently across components. -
Use comments to separate logical blocks inside loops or conditionals for clarity.
Oracle APEX Documentation
You can find official documentation on template directive syntax, including comments, in the Oracle APEX documentation here:
Oracle APEX Template Directives Guide
In Oracle APEX templates, comments are a powerful tool to help organize your code, provide explanations, or temporarily disable sections of your template without affecting the execution of your APEX application. The APEX comment syntax {!<comment-text>/} allows you to embed comments in your template code.
In this tutorial, we'll explore how to create and use comments in Oracle APEX templates using the {!<comment-text>/} syntax.
1. Basic Syntax of APEX Comments
The syntax for adding a comment in APEX is as follows:
{!<comment-text>/}
Where:
{!: Marks the beginning of the comment.
<comment-text>: The text inside the comment, which can be any descriptive content, explanation, or even temporarily disabled code.
/}: Marks the end of the comment.
The content inside {! and /} is not processed or displayed by APEX, making it useful for adding comments without affecting the rendering of the template.
2. Examples of Using APEX Comments
Example 1: Basic Comment
In a template, you can add a simple comment to explain a section of code:
{!This is a comment explaining the next section of the code/}
<h1>Welcome to My APEX Application</h1>
Explanation:
The comment will not appear in the browser output.
The <h1> tag and its content will still be rendered as normal on the page.
Output:
The output on the web page will just display:
<h1>Welcome to My APEX Application</h1>
Example 2: Commenting Out a Section of Code
You can use comments to temporarily disable a section of code without deleting it. For example:
{!<div class="old-feature">This section is no longer used.</div>/}
<h2>Current Feature Section</h2>
<p>New content goes here.</p>
Explanation:
The <div> element will not be rendered, effectively disabling the "old feature" section.
The <h2> and <p> tags will be rendered as normal.
Output:
<h2>Current Feature Section</h2>
<p>New content goes here.</p>
Example 3: Commenting a Complex Template with Multiple Sections
In a more complex APEX template, you can use comments to organize different sections of your code:
{!Header Section - This will be displayed at the top of the page/}
<header>
<h1>Page Title</h1>
<p>Subtitle or description</p>
</header>
{!Content Section - Main body content starts here/}
<div>
<p>Here is the main content of the page.</p>
</div>
{!Footer Section - Footer will be displayed at the bottom/}
<footer>
<p>Footer content goes here.</p>
</footer>
Explanation:
Each section is commented to indicate its purpose, making the code easier to read and maintain.
The browser will render all the HTML elements (header, content, and footer), but the comments are only for developers.
Output:
<header>
<h1>Page Title</h1>
<p>Subtitle or description</p>
</header>
<div>
<p>Here is the main content of the page.</p>
</div>
<footer>
<p>Footer content goes here.</p>
</footer>
The comments are not visible in the browser output, but they help developers understand the structure and purpose of each section.
3. Using Comments for Debugging and Development
Sometimes, during the development process, you might want to disable a specific part of the template for testing or debugging. Here's an example:
Example 4: Disabling Code Temporarily
{!<div class="debug-section">This section is temporarily disabled for debugging purposes.</div>/}
<p>Here is some visible content that will be displayed while the debugging section is disabled.</p>
Explanation:
The <div class="debug-section"> will not be rendered because it is commented out.
The <p> tag with content will be rendered as normal.
Output:
<p>Here is some visible content that will be displayed while the debugging section is disabled.</p>
4. Nested Comments (Not Supported)
It’s important to note that nested comments are not supported in APEX templates. That means you cannot have a comment inside another comment. For example:
{! This is a comment {! Nested comment here /}! /}
This will result in a syntax error and should be avoided. Always ensure your comments are properly closed before starting a new comment.
5. Benefits of Using APEX Comments
Documentation: Adding comments helps document your templates, making it easier for other developers to understand the code structure.
Disabling Code: You can use comments to temporarily disable parts of the template during development or testing, which can speed up troubleshooting.
Code Organization: Using comments to mark sections (e.g., header, content, footer) makes the code easier to navigate and maintain.
No Impact on Rendering: Comments are never rendered in the output, meaning they won’t affect the layout or performance of the application.
6. Best Practices for Using Comments
Be Clear and Concise: Keep comments simple and direct. Avoid over-commenting or adding unnecessary comments that do not add value.
Use Comments for Sections: Group related blocks of code with comments to make it easier to understand the purpose of different sections.
Avoid Commenting Out Large Code Blocks: Instead of commenting out large sections of code, consider using version control systems (e.g., Git) to track changes and roll back when necessary.
Conclusion
Oracle APEX's {!.../} comment syntax is a small but powerful feature that aids in documenting, debugging, and structuring your templates. By using APEX-specific comments, you ensure that notes stay within the developer layer and do not leak into the end-user interface. Incorporating these comments into your workflow leads to cleaner templates and easier collaboration with other developers working on the same application.
