API

This part of the documentation covers all the interfaces of Mara Page. For parts where the package depends on external libraries, we document the most important right here and provide links to the canonical documentation.

ACL

class mara_page.acl.AclResource(name: str, rank: int = 1, children: Optional[List[mara_page.acl.AclResource]] = None)
__init__(name: str, rank: int = 1, children: Optional[List[mara_page.acl.AclResource]] = None)

A resource that is protected by an acl

Parameters

  • name – An identifier of the resource, must be unique among its parents

  • rank – How to sort entries within siblings

  • description – An optional help text

  • children – A list of sub-entries

set_parent(parent: mara_page.acl.AclResource)

Sets the parent of the entry

mara_page.acl.current_user_has_permission(resource: mara_page.acl.AclResource) → bool

Whether the current user is allowed to access a specific resource.

mara_page.acl.current_user_has_permissions(resources: [<class 'mara_page.acl.AclResource'>]) → [[<class 'mara_page.acl.AclResource'>, <class 'bool'>]]

Determines whether the currently logged in user has permissions for a list of resources. Implement actual behavior by patching the function.

mara_page.acl.current_user_email()

Returns the email address of the currently logged in user. Implement actual behavior by patching the function.

mara_page.acl.user_has_permission(email: str, resource: mara_page.acl.AclResource) → bool

Whether a user is allowed to access a specific resource.

mara_page.acl.user_has_permissions(email: str, resources: [<class 'mara_page.acl.AclResource'>]) → [[<class 'mara_page.acl.AclResource'>, <class 'bool'>]]

Determines whether a user has permissions for a list of resources. Implement actual behavior by patching the function.

mara_page.acl.require_permission(resource: mara_page.acl.AclResource, do_abort: bool = True, abort_message="Sorry, but you don't have enough permissions to view this page.", return_message='Not enough permissions.') → Callable

A decorator for protecting a resource by acl

Parameters

  • resource – The resource for which user permissions are required

  • do_abort – When true, a http exception is raised if the the user does not have permission (useful when protecting whole pages). When false, a small error message is returned (useful for ajax handlers).

  • abort_message – The text of the “permission denied” http exception

  • return_message – The text of the returned “permission denied” inline content

Returns

The wrapped function

mara_page.acl.inline_permission_denied_message(message='Not enough permissions')

Returns a an inline html element that signals insufficient permissions

Bootstrap

class mara_page.bootstrap.ActionButton(action: str, label: str, title: str, icon: str)
__init__(action: str, label: str, title: str, icon: str)

A button that is displayed at the top of a page

Parameters

  • action – An url or javascript:foo() function call

  • label – The label of the button

  • title – A help text

  • icon – The icon of the button (from http://fontawesome.io/)

mara_page.bootstrap.card(header_left='', header_right='', fixed_header_height: bool = True, body=[], sections=[], id: str = None, action_buttons: [<class 'str'>] = None)

Renders a bootstrap card bootstrap_card

Parameters

  • header_left – A header that is displayed at the top left of the card

  • header_right – A header that is displayed at the top right of the card

  • fixed_header_height – When true, then the header is restricted to 1 line

  • body – Elements to be shown on the card

  • sections – Parts of the card that are separated by an horizontal line

  • id – An optional id for the outer dom element of the card

Returns

The rendered card

mara_page.bootstrap.table(headers: [<class 'str'>], rows: [], id: typing.Optional[str] = None)

Renders a bootstrap table with some defaults applied

Parameters

  • headers – The column headers (list of strings)

  • rows – All table rows (rendered trs)

  • id – An optional id for the table

Returns

The rendered table

mara_page.bootstrap.button(url: str, label: str, title: str, icon: str, id: Optional[str] = None)

Renders a bootstrap button :param url: The action to perform :param label: The button label :param title: A help message :param icon: An icon from the fontawesome collection :param id: An id that is added to the element

Returns

The rendered button

HTML

mara_page.html.highlight_syntax(code: str, language: str) → [<class 'str'>]

Renders a code snipped into a syntax-highlighted html fragment

Parameters
Returns

html markup

mara_page.html.spinner() → [<class 'str'>]

Returns markup for an animated load spinner.

The default version requires font-awesome to be installed

Returns

html markup

mara_page.html.spinner_js_function() → [<class 'str'>]

Creates a javascript function that returns the markup of spinner

mara_page.html.asynchronous_content(url: str, div_id: Optional[str] = None) → [<class 'str'>]

Creates a div whose content will be asynchronously replaced with the content retrieved from url.

Requires the implementation of the javascript function loadContentAsynchronously that takes four arguments - the container div - the url to load - a localStorage key for storing the final height of the div - an optional javascript snippet that is called once the content is loaded

Parameters

  • url – The url from which to retrieve the content

  • div_id – The id of the container div

Returns

Html markup of the container div

Navigation

class mara_page.navigation.NavigationEntry(label: str, uri_fn: typing.Callable = <function NavigationEntry.<lambda>>, icon: typing.Optional[str] = None, rank: int = 1, description: typing.Optional[str] = None, visible: bool = True, children: typing.Optional[typing.List[mara_page.navigation.NavigationEntry]] = None)
__init__(label: str, uri_fn: typing.Callable = <function NavigationEntry.<lambda>>, icon: typing.Optional[str] = None, rank: int = 1, description: typing.Optional[str] = None, visible: bool = True, children: typing.Optional[typing.List[mara_page.navigation.NavigationEntry]] = None)

A single entry of the navigation sidebar.

Parameters

  • label – The text that is displayed on the entry

  • uri – A function that returns the uri of the linked page (not used when entry has children) This needs to a callable because the app context for url creation is not known yet

  • icon – An optional icon of the link (from http://fontawesome.io/)

  • rank – How to sort entries within siblings

  • description – An optional help text

  • visible – When False, then the entry is not shown

  • children – A list of sub-entries

set_parent(parent: mara_page.navigation.NavigationEntry)

Sets the parent of the entry

Response

class mara_page.response.Response(html, title: str, action_buttons: Optional[List[mara_page.bootstrap.ActionButton]] = None, js_files: Optional[List[str]] = None, css_files: Optional[List[str]] = None, status: int = 200)
__init__(html, title: str, action_buttons: Optional[List[mara_page.bootstrap.ActionButton]] = None, js_files: Optional[List[str]] = None, css_files: Optional[List[str]] = None, status: int = 200)

A rich html response with additional information for applying a page layout

Parameters

  • html – The content of the page

  • title – The title to be displayed in the page header

  • action_buttons – Global actions for the page

  • js_files – URL paths of js files to include

  • css_files – URL paths of css files to include

  • status_code – The http status code

XML

class mara_page.xml.XMLElement(tag_name)

Representation of a html / xml element with attributes and children

__call__(**kwargs)

Adds attributes to the element. When the desired attribute name is a reserved python keyword, then postfix it with ‘_’

__getitem__(*children)

Adds children to the element

__init__(tag_name)
__str__()

Renders the element and it’s children

mara_page.xml.render(x) → [<class 'str'>]

Streams an expression into a list of strings

class mara_page.xml.XMLElementFactory

Creates XML elements using the ‘.’ operator

A singletone factory is available at mara_page._

__getattribute__(name) → mara_page.xml.XMLElement

Return getattr(self, name).

__init__()