Introduction

Are you diving into Oracle APEX development and wondering how to effectively organise your project on GitHub? Proper repository structure not only streamlines collaboration but also enhances maintainability and scalability.

Oracle APEX on GitHub

If you're seeking inspiration for structuring your Oracle APEX project on GitHub, exploring the Oracle APEX on GitHub repository can offer valuable insights. Here's a glimpse of the basic directory structure for Sample Apps:

• readme.md: Provides a concise description of the application along with installation steps.

• <app-name>.sql: Contains the SQL script for setting up the database objects required by the APEX application.

• <app-name>.zip: Includes the exported APEX application file, allowing for easy deployment and import into an APEX workspace.

While this structure may seem minimalistic compared to more elaborate setups, it serves as a straightforward starting point for sharing Oracle APEX applications on GitHub. The focus remains on simplicity and ease of use, making it accessible for both developers and users interested in trying out the application.

Export your application

You might be wondering, "Okay, but how do I actually export my Oracle APEX application?" Fear not, as exporting your application is a straightforward process. Follow these steps to export your Oracle APEX application:

• Access Your Oracle APEX Workspace: Log in to your Oracle APEX workspace where the application is hosted.

• Navigate to the Application Builder: Once logged in, navigate to the App Builder section from the workspace home page. Now you have two options:

  

  OPTION 1 - Select Export Applications from the Tasks menu on the left. Then select the application you want to export. This option is more direct.

  

  OPTION 2 - Select Your Application from the list of applications, locate and select the application you want to export. Within the Application Builder, locate the Export/Import option, typically found next to Utilities option. Then, select Export.

  

  

Choose Export Format: Select the desired Readable Format.

Specify whether the export file should contain a human-readable version of the application meta-data. Use it to identify and review differences between versions of an application when checked into a Version Control System.

1. Default option is None, which generates a SQL script containing the application definition and metadata. The downloaded script file is named f<app_ID>.sql.

2. YAML option is the most interesting, since it generates all the application content in multiple YAML files, which are human readable and facilitates comparing differences between versions of the application in GitHub. The downloaded script file is named f<app_ID>.zip.

   

• Specify Export Settings: Depending on the chosen export format, you may need to specify additional settings such as whether to include data or only the application definition. Check Exporting an Application document for more details.

• Download Exported File: After the export process completes, Oracle APEX typically prompts you to save the exported file to your local system.

• Review Exported Content: Before proceeding, review the exported file to ensure that it contains all necessary components of your Oracle APEX application.

Review exported content

Before proceeding, review the exported file to ensure that it contains all necessary components of your Oracle APEX application. See below an example of an application exported with Readable Format option is set to YAML. Please note that the content is the unzipped f<app_ID>.zip file.

• f<app_ID>.sql: a SQL script containing the application definition and metadata. This is the same export file generated when Readable Format option is set to None.

• readable: a human-readable version of the application metadata. It contains all components in YAML format (application, pages, page groups, shared components and supporting objects).

PokeAPEX on GitHub

Some months ago, I created PokéAPEX, a fun and innovative web application to learn Oracle APEX in a unique way. This is the result of combining my passion for Pokémon with my goal of achieving the Oracle APEX Cloud Developer Certified Professional certification.

Recently, I decided to upload the project to GitHub, but I wasn't sure about what was the best way to share the application. By following the steps above, I could effortlessly export my Oracle APEX application, preparing it for sharing, deployment, or version control on platforms like GitHub. Setting the Readable Format export option to YAML provides the necessary content to my GitHub repository, so contributors can identify better changes between versions.

🔗 PokéAPEX on GitHub

On top of that, I added some directories to cover missing files from the application export:

• application: content from application export (this directory is located under readable directory).

• docs/imgs: stores application images for documentation purposes. These images are referenced in the README.md file.

• src/plsql: stores custom PL/SQL packages created for the application.

• static_application_files: all static application files previously downloaded in a Zip. Check Downloading Static Application Files

  

• CODEOWNERS: Check About code owners for more details.

• LICENSE: Check Licensing a repository

• README.md: Check this LinkedIn post about how to create README.md files in a fast way.

Now that you've mastered the export process, you're ready to showcase your Oracle APEX application to the world!

References

• Exporting an Application

• Managing Static Application Files - Downloading Static Application Files

• GitHub docs - About code owners

• GitHub docs - Licensing a repository