Table of Contents

Troubleshooting Developing Modules

Overview

This guide offers troubleshooting steps for common issues encountered when developing, modifying, or debugging modules in the Oqtane Framework. Modules are key components that enable the functionality of your site, and problems with modules can impact the user experience and site performance. The troubleshooting steps outlined below address the most common challenges faced by module developers.

1. Module Not Loading

Symptoms: The module does not appear on the page, or it loads as a blank space.

Solution:

  • Check Module Registration: Ensure that your module is correctly registered in the Oqtane system. Verify that the module is listed in the admin dashboard under the module management section.
  • Inspect Controller: If your module has a controller, ensure it is correctly implemented and the routes are set up properly. Missing or incorrect routes can prevent the module from loading.
  • Review Logs: Check the application logs for errors related to module loading or initialization. Look for errors in the Oqtane logs that might provide hints about why the module isn't loading.
  • Module Permissions: Make sure the user has the necessary permissions to view the module. Modules may be hidden if the current user role lacks the required permissions.

2. Module Layout Not Displaying Correctly

Symptoms: The module displays but its layout is incorrect, or it appears with broken elements.

Solution:

  • Check Layout Files: Review the .cshtml or .razor layout files for the module. Ensure they are correctly structured, with proper references to CSS, JavaScript, and component elements.
  • Check Styles and Scripts: Verify that the module’s required stylesheets and scripts are included and properly referenced. Missing or incorrect references may result in layout issues.
  • Responsive Design: Ensure that the module is responsive, especially if it uses a grid layout. Verify that CSS media queries are in place to adapt the module's layout for different screen sizes.

3. JavaScript Not Working in the Module

Symptoms: JavaScript functionality (such as interactivity) doesn't work or fails to trigger in the module.

Solution:

  • Inspect Browser Console: Open the browser’s developer console and check for JavaScript errors. Missing files, syntax errors, or issues with dependencies could prevent the script from running.
  • Check Script References: Make sure JavaScript files are correctly linked in the module’s layout file. Verify that the JavaScript files are loaded in the right order, as some modules may require specific libraries (e.g., jQuery or Bootstrap).
  • Check for jQuery Conflicts: If using jQuery, ensure no conflicts with other JavaScript libraries. For instance, ensure jQuery is loaded before any jQuery-dependent scripts.
  • Debug JavaScript Code: Use debugging tools to step through the JavaScript code and confirm if all functions are being executed as expected.

4. Module Not Updating Changes

Symptoms: Changes made to the module's source code are not reflected when the page is refreshed.

Solution:

  • Clear Browser Cache: Sometimes, changes may not appear due to cached files. Clear the browser cache and refresh the page.
  • Clear Oqtane Cache: In Oqtane, cached components and modules might delay updates. Clear Oqtane's internal cache from the control panel to ensure the latest changes are applied.
  • Rebuild the Module: If the module is being built from source, ensure that the build process has completed successfully. Rebuild the module to confirm that the compiled version is up to date.

5. Module Throws Errors or Exceptions

Symptoms: The module fails to load, and exceptions or errors are thrown during its operation.

Solution:

  • Check Logs for Exceptions: Review the server logs for exceptions that are being thrown. The logs can provide detailed information about the specific error and the module’s behavior at runtime.
  • Verify Database Connections: If your module interacts with a database, ensure that database connections are correctly configured. Incorrect connection strings or missing database tables can cause runtime errors.
  • Check for Missing Dependencies: Ensure all dependencies required by the module are properly included. Missing DLLs or dependencies can cause the module to fail.
  • Debug in Development Mode: Enable detailed error messages in the development environment to get a more granular view of the issues and track down the root cause.

6. Module Not Performing as Expected

Symptoms: The module functions incorrectly, or some features do not work as intended.

Solution:

  • Check Business Logic: Review the module’s business logic to ensure it performs the intended actions. Validate that all the necessary conditions are being met within the code.
  • Test Module Inputs: Verify that the inputs (e.g., user input or data from the database) are being processed correctly by the module.
  • Check Configuration Settings: Ensure the module’s settings and configuration are correct. Misconfigured settings can lead to unexpected behavior.
  • Use Debugging: If needed, debug the module step-by-step to observe the internal state and pinpoint where the behavior diverges from expectations.

7. Module Permissions Not Working

Symptoms: The module is not visible or accessible based on the user’s permissions.

Solution:

  • Verify Permission Settings: Check the permissions set for the module in the Oqtane control panel. Ensure that the user role has the correct permissions for viewing or interacting with the module.
  • Check Role Assignment: Make sure the user’s role is properly assigned and that the permissions for the module are aligned with the role’s capabilities.
  • Review Module Visibility Logic: Some modules may have additional logic in place that controls visibility based on user roles. Verify that the logic is functioning as intended.

8. Module Dependencies Not Working

Symptoms: The module relies on other modules, but the dependent modules are not functioning correctly, leading to errors or missing features.

Solution:

  • Check Module Dependencies: Verify that all the required dependencies for the module are correctly installed and activated. Some modules may rely on other modules or services, and those dependencies need to be configured correctly.
  • Review Documentation: Review the documentation of the dependent modules to ensure compatibility. Sometimes, module dependencies may require specific versions or configurations.
  • Ensure Dependency Registration: Ensure that any required modules are registered in the Oqtane system and correctly linked to your module.

9. Module Compatibility with Oqtane Updates

Symptoms: After updating Oqtane, the module behaves incorrectly or fails to load.

Solution:

  • Review Release Notes: Check the Oqtane release notes for any breaking changes or updates to the module system that may affect your module. Pay attention to any updates in the API or core framework that may impact your module’s functionality.
  • Update Module Code: If necessary, modify your module to ensure compatibility with the latest version of Oqtane. This could involve changing APIs, adjusting for new features, or removing deprecated functionality.
  • Test in Development: Test the updated module in a development environment before deploying it to production to ensure it behaves as expected with the latest Oqtane version.

Conclusion

By following these troubleshooting steps, developers should be able to resolve the majority of common issues encountered when developing modules for the Oqtane Framework. If issues persist, further assistance may be required from the Oqtane community or support channels.

Edit this page