esparto.design.layout

Info

Layout classes are accessed from the top level module.

import esparto as es

# Create a new Page
page = es.Page()

`Layout`

Class Template for Layout elements.

Layout class hierarchy: Page -> Section -> Row -> Column -> Content

Attributes:

Name	Type	Description
`title`	`str`	Object title. Used as a title within the page and as a key value.
`children`	`list`	Child items defining the page layout and content.
`title_classes`	`list`	Additional CSS classes to apply to title.
`title_styles`	`dict`	Additional CSS styles to apply to title.
`body_classes`	`list`	Additional CSS classes to apply to body.
`body_styles`	`dict`	Additional CSS styles to apply to body.

`display(self)`

Render content in a Notebook environment.

Source code in esparto/design/layout.py

def display(self) -> None:
    """Render content in a Notebook environment."""
    nb_display(self)

`get_identifier(self)`

Get the HTML element ID for the current object.

Source code in esparto/design/layout.py

def get_identifier(self) -> str:
    """Get the HTML element ID for the current object."""
    return clean_attr_name(str(self.title)) if self.title else self._default_id

`get_title_identifier(self)`

Get the HTML element ID for the current object title.

Source code in esparto/design/layout.py

def get_title_identifier(self) -> str:
    """Get the HTML element ID for the current object title."""
    return f"{self.get_identifier()}-title"

`set_children(self, other)`

Set children as other.

Source code in esparto/design/layout.py

def set_children(self, other: Union[List[Child], Child]) -> None:
    """Set children as `other`."""
    other = copy.copy(other)
    self.children = [*self._smart_wrap(other)]
    for child in self.children:
        title = getattr(child, "title", None)
        if title:
            self._add_child_id(title)

`to_html(self, **kwargs)`

Render object as HTML string.

Returns:

Type	Description
`str`	html (str): HTML string.

Source code in esparto/design/layout.py

def to_html(self, **kwargs: bool) -> str:
    """Render object as HTML string.

    Returns:
        html (str): HTML string.

    """
    children_rendered = " ".join([c.to_html(**kwargs) for c in self.children])
    title_rendered = (
        render_html(
            self.title_html_tag,
            self.title_classes,
            self.title_styles,
            self.title,
            self.get_title_identifier(),
        )
        if self.title
        else ""
    )
    html = render_html(
        self.body_html_tag,
        self.body_classes,
        self.body_styles,
        f"{title_rendered}\n{children_rendered}\n",
        self.get_identifier(),
    )
    html = bs4.BeautifulSoup(html, "html.parser").prettify()
    return html

`tree(self)`

Display page tree.

Source code in esparto/design/layout.py

def tree(self) -> None:
    """Display page tree."""
    print(self._tree())

`Page`

Layout class that defines a Page.

Parameters:

Name	Type	Description	Default
`title`	`str`	Used as a title within the page and as a key value.	required
`navbrand`	`str`	Brand name. Displayed in the page navbar if provided.	required
`table_of_contents`	`bool, int`	Add a Table of Contents to the top of page. Passing an `int` will define the maximum depth.	required
`max_width`	`int`	Maximum page width expressed in pixels.	required
`output_options`	`es.OutputOptions`	Page specific rendering and output options.	required
`children`	`list`	Child items defining layout and content.	required
`title_classes`	`list`	Additional CSS classes to apply to title.	required
`title_styles`	`dict`	Additional CSS styles to apply to title.	required
`body_classes`	`list`	Additional CSS classes to apply to body.	required
`body_styles`	`dict`	Additional CSS styles to apply to body.	required

`save(self, filepath='./esparto-doc.html', return_html=False, dependency_source=None)`

Save page to HTML file.

Note

Alias for self.save_html().

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Destination filepath.	`'./esparto-doc.html'`
`return_html`	`bool`	If True, return HTML as a string.	`False`
`dependency_source`	`Optional[str]`	'cdn' or 'inline'.	`None`

Returns:

Type	Description
`Optional[str]`	html (str): Document rendered as HTML. (If `return_html` is True)

Source code in esparto/design/layout.py

def save(
    self,
    filepath: str = "./esparto-doc.html",
    return_html: bool = False,
    dependency_source: Optional[str] = None,
) -> Optional[str]:
    """
    Save page to HTML file.

    Note:
        Alias for `self.save_html()`.

    Args:
        filepath (str): Destination filepath.
        return_html (bool): If True, return HTML as a string.
        dependency_source (str): 'cdn' or 'inline'.

    Returns:
        html (str): Document rendered as HTML. (If `return_html` is True)

    """
    html = self.save_html(
        filepath=filepath,
        return_html=return_html,
        dependency_source=dependency_source,
    )

    if return_html:
        return html
    return None

`save_html(self, filepath='./esparto-doc.html', return_html=False, dependency_source=None)`

Save page to HTML file.

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Destination filepath.	`'./esparto-doc.html'`
`return_html`	`bool`	If True, return HTML as a string.	`False`
`dependency_source`	`Optional[str]`	'cdn' or 'inline'.	`None`

Returns:

Type	Description
`Optional[str]`	html (str): Document rendered as HTML. (If `return_html` is True)

Source code in esparto/design/layout.py

@options_context(output_options)
def save_html(
    self,
    filepath: str = "./esparto-doc.html",
    return_html: bool = False,
    dependency_source: Optional[str] = None,
) -> Optional[str]:
    """
    Save page to HTML file.

    Args:
        filepath (str): Destination filepath.
        return_html (bool): If True, return HTML as a string.
        dependency_source (str): 'cdn' or 'inline'.

    Returns:
        html (str): Document rendered as HTML. (If `return_html` is True)

    """
    html = publish_html(
        self,
        filepath=filepath,
        return_html=return_html,
        dependency_source=dependency_source,
    )
    if return_html:
        return html
    return None

`save_pdf(self, filepath='./esparto-doc.pdf', return_html=False)`

Save page to PDF file.

Note

Requires weasyprint library.

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Destination filepath.	`'./esparto-doc.pdf'`
`return_html`	`bool`	If True, return intermediate HTML representation as a string.	`False`

Returns:

Type	Description
`Optional[str]`	html (str): Document rendered as HTML. (If `return_html` is True)

Source code in esparto/design/layout.py

@options_context(output_options)
def save_pdf(
    self, filepath: str = "./esparto-doc.pdf", return_html: bool = False
) -> Optional[str]:
    """
    Save page to PDF file.

    Note:
        Requires `weasyprint` library.

    Args:
        filepath (str): Destination filepath.
        return_html (bool): If True, return intermediate HTML representation as a string.

    Returns:
        html (str): Document rendered as HTML. (If `return_html` is True)

    """
    html = publish_pdf(self, filepath, return_html=return_html)
    if return_html:
        return html
    return None

`Section`

Layout class that defines a Section.

Parameters:

Name	Type	Description	Default
`title`	`str`	Used as a title within the page and as a key value.	required
`children`	`list`	Child items defining layout and content.	required
`title_classes`	`list`	Additional CSS classes to apply to title.	required
`title_styles`	`dict`	Additional CSS styles to apply to title.	required
`body_classes`	`list`	Additional CSS classes to apply to body.	required
`body_styles`	`dict`	Additional CSS styles to apply to body.	required

`CardSection`

Layout class that defines a CardSection. CardSections wrap content in Cards by default.

Parameters:

Name	Type	Description	Default
`title`	`str`	Used as a title within the page and as a key value.	required
`children`	`list`	Child items defining layout and content.	required
`cards_equal`	`bool`	Cards in the same Row are stretched vertically if True.	required
`title_classes`	`list`	Additional CSS classes to apply to title.	required
`title_styles`	`dict`	Additional CSS styles to apply to title.	required
`body_classes`	`list`	Additional CSS classes to apply to body.	required
`body_styles`	`dict`	Additional CSS styles to apply to body.	required

`Row`

Layout class that defines a Row.

Parameters:

Name	Type	Description	Default
`title`	`str`	Used as a title within the page and as a key value.	required
`children`	`list`	Child items defining layout and content.	required
`title_classes`	`list`	Additional CSS classes to apply to title.	required
`title_styles`	`dict`	Additional CSS styles to apply to title.	required
`body_classes`	`list`	Additional CSS classes to apply to body.	required
`body_styles`	`dict`	Additional CSS styles to apply to body.	required

`CardRow`

Layout class that defines a CardRow. CardRows wrap content in Cards by default.

Parameters:

Name	Type	Description	Default
`title`	`str`	Used as a title within the page and as a key value.	required
`children`	`list`	Child items defining layout and content.	required
`title_classes`	`list`	Additional CSS classes to apply to title.	required
`title_styles`	`dict`	Additional CSS styles to apply to title.	required
`body_classes`	`list`	Additional CSS classes to apply to body.	required
`body_styles`	`dict`	Additional CSS styles to apply to body.	required

`CardRowEqual`

Layout class that defines a CardRow with Cards of equal height.

Parameters:

Name	Type	Description	Default
`title`	`str`	Used as a title within the page and as a key value.	required
`children`	`list`	Child items defining layout and content.	required
`title_classes`	`list`	Additional CSS classes to apply to title.	required
`title_styles`	`dict`	Additional CSS styles to apply to title.	required
`body_classes`	`list`	Additional CSS classes to apply to body.	required
`body_styles`	`dict`	Additional CSS styles to apply to body.	required

`Column`

Layout class that defines a Column.

Parameters:

Name	Type	Description	Default
`title`	`str`	Used as a title within the page and as a key value.	required
`children`	`list`	Child items defining layout and content.	required
`col_width`	`int`	Fix column width - must be between 1 and 12.	required
`title_classes`	`list`	Additional CSS classes to apply to title.	required
`title_styles`	`dict`	Additional CSS styles to apply to title.	required
`body_classes`	`list`	Additional CSS classes to apply to body.	required
`body_styles`	`dict`	Additional CSS styles to apply to body.	required

`Card`

Layout class that defines a Card.

Child items will be vertically stacked by default. Horizontal arrangement is achieved by nesting content inside a Row.

Parameters:

Name	Type	Description	Default
`title`	`str`	Used as a title within the page and as a key value.	required
`children`	`list`	Child items defining layout and content.	required
`col_width`	`int`	Fix column width - must be between 1 and 12.	required
`title_classes`	`list`	Additional CSS classes to apply to title.	required
`title_styles`	`dict`	Additional CSS styles to apply to title.	required
`body_classes`	`list`	Additional CSS classes to apply to body.	required
`body_styles`	`dict`	Additional CSS styles to apply to body.	required

`to_html(self, **kwargs)`

Render content to HTML string.

Returns:

Type	Description
`str`	html (str): HTML string.

Source code in esparto/design/layout.py

def to_html(self, **kwargs: bool) -> str:
    """Render content to HTML string.

    Returns:
        html (str): HTML string.

    """
    children_rendered = " ".join([c.to_html(**kwargs) for c in self.children])
    title_rendered = (
        render_html(
            self.title_html_tag,
            self.title_classes,
            self.title_styles,
            self.title,
            self.get_title_identifier(),
        )
        if self.title
        else ""
    )
    card_body_classes = ["es-card-body"]
    card_body_styles: Dict[str, str] = {}
    html_body = render_html(
        "div",
        card_body_classes,
        card_body_styles,
        f"\n{title_rendered}\n{children_rendered}\n",
        f"{self.get_identifier()}-body",
    )
    html_full = render_html(
        self.body_html_tag,
        self.body_classes,
        self.body_styles,
        f"\n{html_body}\n",
        f"{self.get_identifier()}",
    )

    return html_full

`Spacer`

Empty Column for making space within a Row.

`PageBreak`

Defines a page break when printing or saving to PDF.