Trees       Indices       Help   
Trac
Package trac :: Package web :: Module chrome :: Class Chrome

Class Chrome

source code

    object --+    
             |    
core.Component --+
                 |
                Chrome

Web site chrome assembly manager.

Chrome is everything that is not actual page content.

Nested Classes

Inherited from core.Component: __metaclass__

Instance Methods
 
mainnav(...)
Configures the main navigation bar, which by default contains //Wiki//, //Timeline//, //Roadmap//, //Browse Source//, //View Tickets//, //New Ticket//, //Search// and //Admin//.		 source code
 
metanav(...)
Configures the meta navigation entries, which by default are //Login//, //Logout//, //Preferences//, ''!Help/Guide'' and //About Trac//.		 source code
 
__init__(self)
x.__init__(...) initializes x; see help(type(x)) for signature		 source code
 
get_system_info(self) source code
 
environment_created(self)
Add the sample templates to the environment templates dir.		 source code
 
environment_needs_upgrade(self) source code
 
upgrade_environment(self) source code
 
match_request(self, req) source code
 
process_request(self, req) source code
 
get_permission_actions(self)
EMAIL_VIEW permission allows for showing email addresses even if [trac] show_email_addresses is false.		 source code
 
get_htdocs_dirs(self) source code
 
get_templates_dirs(self) source code
 
get_wiki_syntax(self) source code
 
get_link_resolvers(self) source code
 
get_all_templates_dirs(self)
Return a list of the names of all known templates directories.		 source code
 
prepare_request(self, req, handler=None)
Prepare the basic chrome data for the request.		 source code
 
get_icon_data(self, req) source code
 
get_logo_data(self, href, abs_href=None) source code
 
get_navigation_items(self, req, handler) source code
 
get_interface_customization_files(self)
Returns a dictionary containing the lists of files present in the site and shared templates and htdocs directories.		 source code
 
author_email(self, author, email_map)
Returns the author email from the email_map if author doesn't look like an email address.		 source code
 
authorinfo(self, req, author, email_map=None, resource=None)
Format a username to HTML.		 source code
 
author_class(self, req, author) source code
 
authorinfo_short(self, author) source code
 
cc_list(self, cc_field)
Split a CC: value in a list of addresses.		 source code
 
format_author(self, req, author, resource=None, show_email=None)
Format a username in plain text.		 source code
 
format_emails(self, context, value, sep=', ')
Normalize a list of e-mails and obfuscate them if needed.		 source code
 
get_email_map(self)
Get the email addresses of all known users.		 source code
 
add_textarea_grips(self, req)
Make <textarea class="trac-resizable"> fields resizable if enabled by configuration.		 source code
 
add_wiki_toolbars(self, req)
Add wiki toolbars to <textarea class="wikitext"> fields.		 source code
 
add_auto_preview(self, req)
Setup auto-preview for <textarea> fields.		 source code
 
add_jquery_ui(self, req)
Add a reference to the jQuery UI script and link the stylesheet.		 source code
 
populate_data(self, req=None, data=None, d=None)
Fills a dictionary with the standard set of fields expected by templates.		 source code
 
load_template(self, filename, text=False)
Retrieves a template with the given name.		 source code
 
render_template(self, req, filename, data, metadata=None, fragment=False, iterable=False, method=None)
Renders the filename template using data for the context.		 source code
 
generate_fragment(self, req, filename, data, text=False, domain=None)
Produces content ready to be sent from the given template filename and input data, with minimal overhead.		 source code
the generated output is an unicode string if text is True, or a Markup string otherwise.
render_fragment(self, req, filename, data, text=False, domain=None)
Produces a string from given template filename and input data, with minimal overhead.		 source code
a pair of Jinja2 Template and a dict.
prepare_template(self, req, filename, data, text=False, domain=None)
Prepares the rendering of a Jinja2 template.		 source code
str or an iterable of str, depending on iterable
generate_template_stream(self, template, data, text=False, iterable=None)
Returns the rendered template in a form that can be "sent".		 source code
unicode if text is True, Markup otherwise.
render_template_string(self, template, data, text=False)
Renders the template as an unicode or Markup string.		 source code
 
iterable_content(self, stream, text=False, **kwargs)
Generate an iterable object which iterates str instances from the given stream instance.		 source code

Inherited from core.Component: __repr__

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __str__, __subclasshook__

Static Methods

Inherited from core.Component: implements

Class Variables
  required = True
  is_valid_default_handler = False
  shared_templates_dir = <PathOption [inherit] 'templates_dir'>
  shared_htdocs_dir = <PathOption [inherit] 'htdocs_dir'>
  auto_reload = <BoolOption [trac] 'auto_reload'>
  genshi_cache_size = <IntOption [trac] 'genshi_cache_size'>
  htdocs_location = <Option [trac] 'htdocs_location'>
  jquery_location = <Option [trac] 'jquery_location'>
  jquery_ui_location = <Option [trac] 'jquery_ui_location'>
  jquery_ui_theme_location = <Option [trac] 'jquery_ui_theme_loc...
  logo_link = <Option [header_logo] 'link'>
  logo_src = <Option [header_logo] 'src'>
  logo_alt = <Option [header_logo] 'alt'>
  logo_width = <IntOption [header_logo] 'width'>
  logo_height = <IntOption [header_logo] 'height'>
  show_email_addresses = <BoolOption [trac] 'show_email_addresses'>
  show_full_names = <BoolOption [trac] 'show_full_names'>
  never_obfuscate_mailto = <BoolOption [trac] 'never_obfuscate_m...
  resizable_textareas = <BoolOption [trac] 'resizable_textareas'>
  wiki_toolbars = <BoolOption [trac] 'wiki_toolbars'>
  auto_preview_timeout = <FloatOption [trac] 'auto_preview_timeo...
  default_dateinfo_format = <ChoiceOption [trac] 'default_datein...
  use_chunked_encoding = <BoolOption [trac] 'use_chunked_encoding'>
  templates = None
hash(x)
  jenv = None
hash(x)
  jenv_text = None
hash(x)
  html_doctype = ('html', '-//W3C//DTD XHTML 1.0 Strict//EN', 'h...
Properties
  navigation_contributors
List of components that implement ~trac.web.chrome.INavigationContributor
  template_providers
List of components that implement ~trac.web.chrome.ITemplateProvider
  stream_filters
List of components that implement ~trac.web.api.ITemplateStreamFilter

Inherited from object: __class__

Method Details

mainnav(...)

source code 

Configures the main navigation bar, which by default contains //Wiki//, //Timeline//, //Roadmap//, //Browse Source//, //View Tickets//, //New Ticket//, //Search// and //Admin//.

The label, href, and order attributes can be specified. Entries can be disabled by setting the value of the navigation item to disabled.

The following example renames the link to WikiStart to //Home//, links the //View Tickets// entry to a specific report and disables the //Search// entry. {{{#!ini [mainnav] wiki.label = Home tickets.href = /report/24 search = disabled }}}

See TracNavigation for more details.

metanav(...)

source code 

Configures the meta navigation entries, which by default are //Login//, //Logout//, //Preferences//, ''!Help/Guide'' and //About Trac//. The allowed attributes are the same as for [mainnav]. Additionally, a special entry is supported - logout.redirect is the page the user sees after hitting the logout button. For example:

{{{#!ini [metanav] logout.redirect = wiki/Logout }}}

See TracNavigation for more details.

__init__(self)
(Constructor)

source code 
x.__init__(...) initializes x; see help(type(x)) for signature
Overrides: object.__init__
(inherited documentation)

prepare_request(self, req, handler=None)

source code 
Prepare the basic chrome data for the request.
Parameters:
  • req - the request object
  • handler - the IRequestHandler instance that is processing the request

authorinfo(self, req, author, email_map=None, resource=None)

source code 

Format a username to HTML.

Calls Chrome.format_author to format the username, and wraps the formatted username in a span with class trac-author, trac-author-anonymous or trac-author-none.

Parameters:
  • req - the Request object.
  • author - the author string to be formatted.
  • email_map - dictionary mapping usernames to email addresses.
  • resource - optional Resource object for EMAIL_VIEW fine-grained permissions checks.

format_author(self, req, author, resource=None, show_email=None)

source code 

Format a username in plain text.

If [trac] show_email_addresses is False, email addresses will be obfuscated when the user doesn't have EMAIL_VIEW (for the resource) and the optional parameter show_email is None. Returns translated anonymous or none, when the author string is anonymous or evaluates to False, respectively.

Parameters:
  • req - a Request or RenderingContext object.
  • author - the author string to be formatted.
  • resource - an optional Resource object for performing fine-grained permission checks for EMAIL_VIEW.
  • show_email - an optional parameter that allows explicit control of e-mail obfuscation.

format_emails(self, context, value, sep=', ')

source code 
Normalize a list of e-mails and obfuscate them if needed.
Parameters:
  • context - the context in which the check for obfuscation should be done
  • value - a string containing a comma-separated list of e-mails
  • sep - the separator to use when rendering the list again

populate_data(self, req=None, data=None, d=None)

source code 
Fills a dictionary with the standard set of fields expected by templates.
Parameters:
  • req - a Request object; if None, no request related fields will be set
  • data - user-provided dict, which can be used to override the defaults; if None, the defaults will be returned
  • d - dict which is populated with the defaults; if None, an empty dict will be used

load_template(self, filename, text=False)

source code 

Retrieves a template with the given name.

This simply loads the template. If you want to make use of the "standard" Trac API for templates, also call populate_data, or consider using the shortcut method prepare_template instead.

Note

If the text argument is set to a string instead of a boolean, this corresponds to the legacy API and it will be assumed that you want to load a Genshi template instead of a Jinja2 template. If text is 'text' , a NewTextTemplate instance will be created. If it is set to None or to another string value, a MarkupTemplate instance will be created and returned.

This backward compatibility behavior will be removed in Trac 1.5.1.

Parameters:
  • text - in text mode (True) XML/HTML auto-escape of variable expansion is disabled.

render_template(self, req, filename, data, metadata=None, fragment=False, iterable=False, method=None)

source code 

Renders the filename template using data for the context.

It attempts to load a Jinja2 template, augments the provided data with standard data, and renders it according to the options provided in metadata.

The fragment, iterable and method parameters are deprecated and will be removed in Trac 1.5.1. Instead, use the metadata dictionary with keys with the same name. The method key is itself deprecated, use text=True instead of method='text' to indicate that the template is a plain text one, with no need for HTML/XML escaping to take place.

When fragment is specified, or method is 'text', or text is True, we generate some content which does not need all of the chrome related data, typically HTML fragments, XML or plain text.

If iterable is set, we use generate_template_stream to produce the output (iterable of UTF-8 encoded bytes), otherwise we use render_template_string and UTF-8 encode the result.

Note

If the Jinja2 template is not found, this method will try to load a Genshi template instead.

Also if metadata is not a dictionary, we assume that it is the content_type value from the legacy API (a string or None). As a consequence, we assume the template will be a Genshi template and we'll use the legacy Genshi template engine for the rendering.

This backward compatibility behavior will be removed in Trac 1.5.1.

generate_fragment(self, req, filename, data, text=False, domain=None)

source code 

Produces content ready to be sent from the given template filename and input data, with minimal overhead.

It calls prepare_template to augment the data with the usual helper functions that can be expected in Trac templates, including the translation helper functions adapted to the given domain, except for some of the chrome "late" data.

If you don't need that and don't want the overhead, use load_template and generate_template_stream directly.

The generated output is suitable to pass directly to Request.send, see generate_template_stream for details.

See also render_fragment, which returns a string instead.

render_fragment(self, req, filename, data, text=False, domain=None)

source code 

Produces a string from given template filename and input data, with minimal overhead.

It calls prepare_template to augment the data with the usual helper functions that can be expected in Trac templates, including the translation helper functions adapted to the given domain, except for some of the chrome "late" data.

If you don't need that and don't want the overhead, use load_template and render_template_string directly.

See also generate_fragment, which produces an output suitable to pass directly to Request.send instead.

Returns: the generated output is an unicode string if text is True, or a Markup string otherwise.

prepare_template(self, req, filename, data, text=False, domain=None)

source code 

Prepares the rendering of a Jinja2 template.

This loads the template and prepopulates a data dict with the "standard" Trac API for templates.

Parameters:
  • req - a Request instance (optional)
  • filename - the name of a Jinja2 template, which must be found in one of the template directories (see get_templates_dirs)
  • data - user specified data dictionary, used to override the default context set from the request req (see populate_data)
  • text - in text mode (True) XML/HTML auto-escape of variable expansion is disabled.
Returns: a pair of Jinja2 Template and a dict.

generate_template_stream(self, template, data, text=False, iterable=None)

source code 

Returns the rendered template in a form that can be "sent".

This will be either a single UTF-8 encoded str object, or an iterable made of chunks of the above.

Turning off the XML/HTML auto-escape feature for variable expansions has to be disabled when loading the template (see load_template), so remember to stay consistent with the text parameter.

Parameters:
  • template (jinja2.Template) - the Jinja2 template
  • text - in text mode (True) the generated bytes will not be sanitized (see valid_html_bytes).
  • iterable - determine whether the output should be generated in chunks or as a single str; if None, the use_chunked_encoding property will be used to determine this instead
Returns: str or an iterable of str, depending on iterable

render_template_string(self, template, data, text=False)

source code 

Renders the template as an unicode or Markup string.

Turning off the XML/HTML auto-escape feature for variable expansions has to be disabled when loading the template (see load_template), so remember to stay consistent with the text parameter.

Parameters:
  • template (jinja2.Template) - the Jinja2 template
  • text - in text mode (True) the generated string will not be wrapped in Markup
Returns: unicode if text is True, Markup otherwise.

iterable_content(self, stream, text=False, **kwargs)

source code 

Generate an iterable object which iterates str instances from the given stream instance.

If text is a string, this corresponds to the old API and we assume to have a Genshi stream. This backward compatibility behavior will be removed in Trac 1.5.1.

Parameters:
  • text - in text mode (True) XML/HTML auto-escape of variable expansion is disabled.

Class Variable Details

jquery_ui_theme_location

Value:
<Option [trac] 'jquery_ui_theme_location'>

never_obfuscate_mailto

Value:
<BoolOption [trac] 'never_obfuscate_mailto'>

auto_preview_timeout

Value:
<FloatOption [trac] 'auto_preview_timeout'>

default_dateinfo_format

Value:
<ChoiceOption [trac] 'default_dateinfo_format'>

html_doctype

Value:
('html',
 '-//W3C//DTD XHTML 1.0 Strict//EN',
 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd')

Property Details

navigation_contributors

List of components that implement ~trac.web.chrome.INavigationContributor
Get Method:
unreachable.extensions(component) - Return a list of components that declare to implement the extension point interface.

template_providers

List of components that implement ~trac.web.chrome.ITemplateProvider
Get Method:
unreachable.extensions(component) - Return a list of components that declare to implement the extension point interface.

stream_filters

List of components that implement ~trac.web.api.ITemplateStreamFilter
Get Method:
unreachable.extensions(component) - Return a list of components that declare to implement the extension point interface.

   Trees       Indices       Help   
Trac
Generated by Epydoc 3.0.1 on Fri Aug 11 08:14:34 2023 http://epydoc.sourceforge.net