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.
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.
The API documentation is extracted automatically by Doxygen.
See the class hierarchy for details on the classes available.
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.
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.
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.
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();
Depending on your configuration, you may need to implement parts or all of the opera:about document.
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:
OperaAbout class and implement the abstract
methods.
These methods are used to return platform-specific information.
OperaAbout::Create() method so that
it creates an instance of your inherited class.
The mobile version of the about document
(TWEAK_ABOUT_MOBILE_ABOUT set to YES)
is completely implemented in the about module.
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.
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 */
}
OpString to convert from ASCII too UTF-16
when creating strings. Try to avoid storing static markup as UTF-16.
OpGeneratedDocument
has some utilities for working with locale strings.
Reserve()
to pre-allocate a buffer to avoid successive allocations.
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.
See also the API documentation.
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.
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.
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.
There are no global objects.
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.
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.