In Oracle APEX, creating and managing templates often involves inserting special syntax that controls how data and elements are rendered dynamically. One helpful feature for organizing and documenting these templates is the use of APEX comment directives. By using the syntax {!<comment-text>/}, developers can insert inline comments that are only visible during development and are completely removed from the rendered HTML. These comments do not appear in the final output, making them ideal for leaving notes, version tags, or reminders within complex template structures without affecting performance or display.
In Oracle APEX, when customizing templates such as Classic Reports, Card Reports, or Interactive Report templates, developers often need to leave behind comments for documentation or clarification without affecting the final HTML output. Oracle APEX supports a special syntax for this purpose: the comment directive {!<comment-text>/}. This syntax allows you to insert comments directly inside the Template Text of a report or region. These comments are removed during rendering and are not visible to end users in the browser, unlike standard HTML comments (<!-- -->) which are still included in the page source.
To use APEX comment directives, you simply wrap your comment text within {! ... /}.
Example of Use:
<div class="card">
<div class="card-header">
{! This section displays the employee name /}
#EMPLOYEE_NAME#
</div>
<div class="card-body">
{! Department and salary details /}
#DEPARTMENT# - #SALARY#
</div>
</div>
In the example above, two APEX comment directives are included. These will be visible to the developer while editing the template but will not appear in the page’s source code or interfere with the layout.
Key Points:
-
Use this directive only in template definitions like region templates, column templates, and report templates.
-
These comments are evaluated server-side and stripped before HTML is generated.
-
They are ideal for annotating logic, explaining sections, or temporarily disabling template content during development.
-
Unlike HTML comments, APEX comments do not impact client-side performance since they are completely removed from the DOM.
By using {! ... /} for comments, you maintain clean and professional output while keeping your template logic well-documented and easier to manage over time.
Example
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.
Using APEX comment syntax is a simple yet powerful way to keep your templates maintainable and easy to understand—especially when working in teams or revisiting projects later. Since these comments are stripped out at runtime, they won’t interfere with the page layout or add unnecessary weight to the output, ensuring that your applications remain clean and efficient while still being well-documented under the hood.
