About module

Copyright © 2006-2012 Opera Software ASA. All rights reserved. This file is part of the Opera web browser. It may not be distributed under any circumstances.

Introduction

The About module provides an interface for browser-generated documents, and implements several of the most common documents. The documents are generated in collaboration with the URL module.

It also provides style sheets and scripts for the documents it generates, as well as other style sheets shipped with Opera.

Current information about the About module.

Interface overview and API documentation

API documentation

The API documentation is extracted automatically by Doxygen.

Overview

See the class hierarchy for details on the classes available.

OpGeneratedDocument interface

The OpGeneratedDocument interface is provided to present a uniform appearance of internally generated documents. Code that needs to be able to generate (X)HTML documents internally should inherit this class and make use of its methods.

It interacts with the URL module to actually generated the requested document, by writing data to the URL object. Since the implementations of this class are expected to provide the document body, the implementor should be aware of the URL module APIs.

Provided implementations

This module also provides implementations of several of the internal documents, such as opera:history and others, using the framework. These are implemented in the About module to make it possible to provide uniform markup and appearance of these documents.

Most of the documents need to collaborate with outside code. For the most part, this is already taken care of, but the case of opera:about is special, see Implementing opera:about below for further information.

Use-cases

Packaging necessary auxilliary files

Several of the generated documents reference style sheets to make the display prettier, and some require external scripts. Please read the style sheet and scripts documentation for more information on what files you need to package, and where they should go.

Generating a document provided by the about module

All the classes that inherit from the about module framework implement the GenerateData() API, which is used to write to the document. When it has been called, the document is fully created (exception: the OpFolderListing class).

To generate the opera:blank document, you can use the following:

URL new_url = g_url_api->GetNewOperaURL();
OperaBlank document(new_url);
document.GenerateData();

Implementing opera:about

Depending on your configuration, you may need to implement parts or all of the opera:about document.

The desktop opera:about

The desktop version of the about document (TWEAK_ABOUT_DESKTOP_ABOUT set to YES) has its generic implementation done in the about module. To implement it fully, your platform needs to do the following:

The mobile opera:about

The mobile version of the about document (TWEAK_ABOUT_MOBILE_ABOUT set to YES) is completely implemented in the about module.

Other opera:about implementations

If you disable both the desktop and mobile versions of the opera:about document, you will need to implement it yourself, by creating a body for the OperaAbout::GenerateData() method. See the section on implementing new documents below for more information.

Implementing a new document using the about module APIs

To implement a new document, inherit the OpGeneratedDocument interface and implement the abstract method GenerateData(). This method is what gets called to set up the document.

To your disposal you have the URL object that you are to write to (the m_url variable) and its APIs (WriteDocumentData() etc). To write the parts of the document that is common, the OpGeneratedDocument interface provides several methods, of which the most important ones are OpenDocument(), OpenBody() and CloseDocument().

To create a document that writes Foo in the document body, you can use the following code to get a valid HTML document:

OP_STATUS OpFooDocument::GenerateData()
{
 RETURN_IF_ERROR(OpenDocument()); /* Set up metadata, write a DOCTYPE and open the HEAD element */
 RETURN_IF_ERROR(OpenBody()); /* Close HEAD and open BODY */
 RETURN_IF_ERROR(m_url.WriteDocumentData(URL::KNormal, UNI_L("<p>Foo</p>")); /* Write the custom HTML code */
 return CloseDocument(); /* Close the HTML code and signal that we are done */
}

Tips and tricks

Supported standards

The documents generated by the About module are either HTML 4.01 Strict documents, HTML 5 or XHTML 1.0 Basic. Support for more document formats can be implemented if required.

Implementation and design

See also the API documentation.

Generalisation and re-implementation

See the Use-cases section above for information on how to implement various parts of the generated documents. There is currently no support for disabling the implementations inside the about module for re-implementations. If there is need for such re-implementation, please contact the module owner.

Memory management

Heap usage

The generated documents will allocate any internal data needed on the heap. For the most part, this consist of language strings that are needed to complete the documents, or building markup from the data provided.

Heap allocated data will have a as short lifespan as possible.

Stack usage

There are no recursive calls. The OperaCache class does call back to the cache code to generate the body of the document.

The classes provided by this module are small and can be allocated on the stack.

Static memory usage

There are no global objects.

OOM policies

The About module returns a status code when an out-of-memory problem occurs. It is up to the caller to handle the error, or to raise it with the memory manager.

Performance

The extensive error checking may degrade performance.

Generated documents are usually stored in the cache by the URL module, which means that performance concerns only are valid for the first-time generation of a document.

References