11 Replies Latest reply on Dec 5, 2006 10:24 PM by 500753

    Self-documenting applications!


      If you have a primarily "readonly" application with lots of report regions, I found it useful to add a report region on Page 0 (Before Footer) with a Show/Hide region template with the following source
      from apex_application_page_regions
      WHERE application_id=:APP_ID
      and   page_id=:APP_PAGE_ID
      AND source_type='Report'
      order by display_sequence
      This way, whenever any page is run, it will show the "source code" for the report regions on that page.

      I find this to be incredibly useful when an application is being tested for correctness of the data by a separate QA department who is familiar with the underlying tables/views and would like to independently verify the data using other query tools.

      Needless to say, the approach can be extended to include other relevant metadata about the application at appropriate locations, sort of as a "self-documenting" system.

      Using the APEX_DICTIONARY views in our applications leads to some very interesting possibilities indeed!

      Hope this helps.
        • 1. Re: Self-documenting applications!
          Phil UK

          Great idea and brings me back to a question I probably asked a year or so ago...

          Can I determine if I am running a page "normally" or with the developer toolbar visible, ie as a developer? If this were the case, I'd add in a condition on this to ensure it was always available to me when developing but not to end users.


          • 2. Re: Self-documenting applications!
            Phil: I don't think there is a way to determine that but I don't think it is necessary. You need a way to clearly define "a developer", either by looking up APP_USER in a pre-determined list (hardcoded or in a table you maintain) or by IP addresses or whatever. Then you can condition the "Source Code" report region using this condition.
            • 3. Re: Self-documenting applications!
              Phil UK
              Vikas - you're right as far as I know. I'd always opt for a more simple way of doing thimgs so adding a column or table for developers is something I'd avoid if possible. I'm just being awkward!

              • 4. Re: Self-documenting applications!
                Another idea: Assuming you don't do development on your Production instance i.e. your Production and development run on two separate environments, you could condition the region to show only on the Development environment. This could be identified either by the CGI variables (host name, server name and the like) or by some other server-side data (v$instance.host_name or something).
                • 5. Re: Self-documenting applications!
                  Hi Phil,


                  APEX_Application.g_edit_cookie_session_id (WWV_Flow if you are on 2.0).

                  If it is NOT NULL your application is called from the APEX Builder (=> the developers toolbar is visible), if it's NULL you called your application the normal way.

                  Maybe I should blog about that... :-)

                  Hope this helps
                  Check out my APEX-blog: http://inside-apex.blogspot.com/
                  • 6. Re: Self-documenting applications!
                    Thanks, Vikas a very good idea.

                    But as an extension – is it possible to compare 2 pages from 2 applications?
                    For me the most complicated thing during team development with Apex is to find out why the page that worked yesterday doesn’t work today. If it was possible to compare pages, I could export application from development environment every evening and import it to backup environment and if necessary – compare. It would be almost like cvs which I think is the most important thing that Apex doesn’t have.

                    • 7. Re: Self-documenting applications!
                      An APEX application/page/component export is a plain text file, so you can easily compare files, use your SCM tool of choice to checkin/out files, version them, revert back to earlier version, etc.

                      I use the command-line export utilities available on the APEX Studio (http://apex.oracle.com/studio) to generate full application export so that everything can be scripted, automated, scheduled, whatever.
                      • 8. Re: Self-documenting applications!
                        We too export application and save all stable versions in cvs.

                        It is possible to use export file to compare versions - but it is not convenient.
                        And by the way if developer drops a page item and later creates exactly the same -
                        will the statement for this item:



                        be at the same place it export file? Usually it is- but if not, it will not be possible to compare export files.

                        As far as I know structure of export file is not documented and could change even with minor version changes.
                        With documented views we could make much better tool to compare versions of page/application.

                        • 9. Re: Self-documenting applications!
                          I'm afraid this is probably a silly question, but that has never stopped me before.

                          In our APEX 2.0 installation I do not find a table or view named apex_application_page_regions.

                          Is this a 2.2 thing? If so, is there an equivalent 2.0 table/view?
                          • 10. Re: Self-documenting applications!
                            Yes, all the APEX_DICTIONARY views http://htmldb.oracle.com/pls/otn/f?p=24317:11 were added in Version 2.2.

                            There is no supported equivalent 2.0 table/view, although you could always peek at the source code behind the views and create your own views on the underlying tables.

                            Or, better yet, just upgrade to 2.2!
                            • 11. Re: Self-documenting applications!
                              Thank you Vikas. Onward to 2.2!