# About module

## 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:

- Inherit the `OperaAbout` class and implement the abstract methods. These methods are used to return platform-specific information.
- Implement the (static) `OperaAbout::Create()` method so that it creates an instance of your inherited class.

#### 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

- Don't use HTML named entities or numerical character references in your documents. Since all the documents are UTF-16, use the Unicode code-point directly, this both saves footprints and processing time.
- Use the support in `OpString` to convert from ASCII too UTF-16 when creating strings. Try to avoid storing static markup as UTF-16.
- Your class inherits functionality to generate common HTML constructs. Use it.
- `OpGeneratedDocument` has some utilities for working with locale strings.
- When using OpString's as buffers and building strings in turns (for instance adding markup and locale strings), use `Reserve()` to pre-allocate a buffer to avoid successive allocations.

## 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

- URL module