Content presentation for the web layer.
The Chrome module deals with delivering and shaping content to the end user, mostly targeting (X)HTML generation but not exclusively, RSS or other forms of web content are also using facilities provided here.
Extension point interface for components that contribute items to the navigation.
See also trac.web.chrome.INavigationContributor extension point
This method is only called for the IRequestHandler processing the request.
It should return the name of the navigation item that should be highlighted as active/current.
Should return an iterable object over the list of navigation items to add, each being a tuple in the form (category, name, text).
Extension point interface for components that provide their own Genshi templates and accompanying static resources.
See also trac.web.chrome.ITemplateProvider extension point
Return a list of directories with static resources (such as style sheets, images, etc.)
Each item in the list must be a (prefix, abspath) tuple. The prefix part defines the path in the URL that requests to these resources are prefixed with.
The abspath is the absolute path to the directory containing the resources on the local file system.
Return a list of directories containing the provided template files.
Web site chrome assembly manager.
Chrome is everything that is not actual page content.
Setup auto-preview for <textarea> fields.
Add a reference to the jQuery UI script and link the stylesheet.
Make <textarea class="trac-resizable"> fields resizable if enabled by configuration.
Add wiki toolbars to <textarea class="wikitext"> fields.
Inactivity timeout in seconds after which the automatic wiki preview triggers an update. This option can contain floating-point values. The lower the setting, the more requests will be made to the server. Set this to 0 to disable automatic preview. The default is 2.0 seconds. (‘’since 0.12’‘)
Automatically reload template files after modification.
Split a CC: value in a list of addresses.
The date information format. Valid options are ‘relative’ for displaying relative format and ‘absolute’ for displaying absolute format. (‘’since 1.0’‘)
Create the environment templates directory.
Normalize a list of e-mails and obfuscate them if needed.
| Parameters: |
|
|---|
The maximum number of templates that the template loader will cache in memory. The default value is 128. You may want to choose a higher value if your site uses a larger number of templates, and you have enough memory to spare, or you can reduce it if you are short on memory.
Return a list of the names of all known templates directories.
Get the email addresses of all known users.
Returns a dictionary containing the lists of files present in the site and shared templates and htdocs directories.
Base URL for serving the core static resources below /chrome/common/.
It can be left empty, and Trac will simply serve those resources itself.
Advanced users can use this together with [TracAdmin trac-admin ... deploy <deploydir>] to allow serving the static resources for Trac directly from the web server. Note however that this only applies to the <deploydir>/htdocs/common directory, the other deployed resources (i.e. those from plugins) will not be made available this way and additional rewrite rules will be needed in the web server.
Generate an iterable object which iterates str instances from the given stream instance.
| Parameters: | method – the serialization method; can be either “xml”, “xhtml”, “html”, “text”, or a custom serializer class |
|---|
Location of the jQuery !JavaScript library (version 1.7.2).
An empty value loads jQuery from the copy bundled with Trac.
Alternatively, jQuery could be loaded from a CDN, for example: http://code.jquery.com/jquery-1.7.2.min.js, http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js or https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js.
(‘’since 1.0’‘)
Location of the jQuery UI !JavaScript library (version 1.8.21).
An empty value loads jQuery UI from the copy bundled with Trac.
Alternatively, jQuery UI could be loaded from a CDN, for example: https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.21/jquery-ui.min.js or http://ajax.aspnetcdn.com/ajax/jquery.ui/1.8.21/jquery-ui.min.js.
(‘’since 1.0’‘)
Location of the theme to be used with the jQuery UI !JavaScript library (version 1.8.21).
An empty value loads the custom Trac jQuery UI theme from the copy bundled with Trac.
Alternatively, a jQuery UI theme could be loaded from a CDN, for example: https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.21/themes/start/jquery-ui.css or http://ajax.aspnetcdn.com/ajax/jquery.ui/1.8.21/themes/start/jquery-ui.css.
(‘’since 1.0’‘)
Retrieve a Template and optionally preset the template data.
Also, if the optional method argument is set to 'text', a NewTextTemplate instance will be created instead of a MarkupTemplate.
Alternative text for the header logo.
Height of the header logo image in pixels.
URL to link to, from the header logo.
URL of the image to use as header logo. It can be absolute, server relative or relative.
If relative, it is relative to one of the /chrome locations: site/your-logo.png if your-logo.png is located in the htdocs folder within your TracEnvironment; common/your-logo.png if your-logo.png is located in the folder mapped to the [#trac-section htdocs_location] URL. Only specifying your-logo.png is equivalent to the latter.
Width of the header logo image in pixels.
Order of the items to display in the mainnav navigation bar, listed by IDs. See also TracNavigation.
Order of the items to display in the metanav navigation bar, listed by IDs. See also TracNavigation.
List of components that implement INavigationContributor
Never obfuscate mailto: links explicitly written in the wiki, even if show_email_addresses is false or the user doesn’t have EMAIL_VIEW permission (‘’since 0.11.6’‘).
Prepare the basic chrome data for the request.
| Parameters: |
|
|---|
Render the filename using the data for the context.
The content_type argument is used to choose the kind of template used (NewTextTemplate if 'text/plain', MarkupTemplate otherwise), and tweak the rendering process. Doctype for 'text/html' can be specified by setting the html_doctype attribute (default is XHTML_STRICT)
When fragment is specified, the (filtered) Genshi stream is returned.
When iterable is specified, the content as an iterable instance which is generated from filtered Genshi stream is returned.
Make <textarea> fields resizable. Requires !JavaScript. (‘’since 0.12’‘)
Path to the //shared htdocs directory//.
Static resources in that directory are mapped to /chrome/shared under the environment URL, in addition to common and site locations.
This can be useful in site.html for common interface customization of multiple Trac environments.
(‘’since 1.0’‘)
Path to the //shared templates directory//.
Templates in that directory are loaded in addition to those in the environments templates directory, but the latter take precedence.
(‘’since 0.11’‘)
Show email addresses instead of usernames. If false, email addresses are obfuscated for users that don’t have EMAIL_VIEW permission. (‘’since 0.11’‘)
Show IP addresses for resource edits (e.g. wiki). Since 1.0.5 this option is deprecated and will be removed in 1.3.1. (‘’since 0.11.3’‘)
List of components that implement ITemplateStreamFilter
List of components that implement ITemplateProvider
If enabled, send contents as chunked encoding in HTTP/1.1. Otherwise, send contents with Content-Length header after entire of the contents are rendered. (‘’since 1.0.6’‘)
Most of the helper functions are related to content generation, and in particular, (X)HTML content generation, in one way or another.
Create a rendering context from a request.
The perm and href properties of the context will be initialized from the corresponding properties of the request object.
>>> from trac.test import Mock, MockPerm
>>> req = Mock(href=Mock(), perm=MockPerm())
>>> context = web_context(req)
>>> context.href is req.href
True
>>> context.perm is req.perm
True
| Parameters: |
|
|---|---|
| Returns: | a new rendering context |
| Return type: | RenderingContext |
| Since: | version 1.0 |
Add a <meta> tag into the <head> of the generated HTML.
Add a link to a style sheet to the chrome info so that it gets included in the generated HTML page.
If filename is a network-path reference (i.e. starts with a protocol or //), the return value will not be modified. If filename is absolute (i.e. starts with /), the generated link will be based off the application root path. If it is relative, the link will be based off the /chrome/ path.
| Deprecated: | since 0.10, use add_script instead. |
|---|
Add a reference to an external javascript file to the template.
If filename is a network-path reference (i.e. starts with a protocol or //), the return value will not be modified. If filename is absolute (i.e. starts with /), the generated link will be based off the application root path. If it is relative, the link will be based off the /chrome/ path.
Add data to be made available in javascript scripts as global variables.
The keys in data and the keyword argument names provide the names of the global variables. The values are converted to JSON and assigned to the corresponding variables.
Add a non-fatal warning to the request object.
When rendering pages, all warnings will be rendered to the user. Note that the message is escaped (and therefore converted to Markup) before it is stored in the request object.
Add an informational notice to the request object.
When rendering pages, all notices will be rendered to the user. Note that the message is escaped (and therefore converted to Markup) before it is stored in the request object.