Widgets

This part of the documentation covers all the reusable django-wildewidgets widgets provided by django-sphinx-hosting.

Navigation

These widgets are used on every page.

class sphinx_hosting.wildewidgets.SphinxHostingSidebar(*args, wide: Optional[bool] = None, **kwargs)

This is the vertical menu area on the left of the page. It houses our search form, sphinx_hosting.wildewidgets.search.GlobalSearchFormWidget, our main menu SphinxHostingMainMenu, possibly our utility menu SphinxHostingLookupsMenu and finally the global navigation for a sphinx_hosting.models.Version when we’re reading our documentation.

branding: Block = <wildewidgets.widgets.base.Block object>

contents: Iterable[Block] = [<sphinx_hosting.wildewidgets.navigation.SphinxHostingMainMenu object>]

hide_below_viewport: str = 'xl'

The viewport size at which our menu container collapses to be hidden,

wide: bool = True

class sphinx_hosting.wildewidgets.SphinxHostingMainMenu(*items, **kwargs)

This is the primary menu that appears in SphinxHostingSidebar directly underneath the “Search” form, sphinx_hosting.wildewidgets.search.GlobalSearchFormWidget.

It gives access to all the views that normal, non privileged users should be allowed to use.

__init__(*items, **kwargs) → None

activate(text: str) → bool

Normally, how activate works is that it looks through our menu items, finds the one whose text or url matches text.

In our case, we’re building the menu items in build_menu, which occurs after activate would be called, so we have to save the text here, and use it later in build_menu.

Parameters

text – the text to search for among our items

Returns

We always return True here, since we won’t know if we match until later.

build_menu(items: List[MenuItem]) → None

Programatically build our menu here. We have this code because the presence of some items in this menu depends on the user’s permissions.

We have to do it here because if we do it in __init__, that’s too early in the Django boostrap and the global Django urlpatterns have not finished building, and even reverse_lazy fails.

items: Iterable[MenuItem] = [MenuItem(text='Projects', icon='bookshelf', url='/', items=[], active=False)]

title: str = 'Main'

class sphinx_hosting.wildewidgets.SphinxHostingBreadcrumbs(*args, title_class: Optional[str] = None, **kwargs)

items: List[BreadcrumbItem] = [BreadcrumbItem(title='Sphinx Hosting', url='/')]

The list of BreadcrumbItem objects from which we will

Projects

These widgets are used on the project listing and details pages.

class sphinx_hosting.wildewidgets.ClassifierFilterForm(table_name: str, column_number: int, **kwargs)

This is the tree-like classifier filter form that appears to the right of the sphinx_hosting.wildewidgets.project.ProjectTable. It is embedded in ClassifierFilterBlock.

It allows the user to select a set of classifiers by which to filter the projects listing table.

__init__(table_name: str, column_number: int, **kwargs)

add_subtree(contents: UnorderedList, nodes: Dict[str, ClassifierNode]) → None

Add a subtree of classifier checkboxes.

Parameters

• contents – the <ul> block to which to add our list of classifier checkboxes

• nodes (_type_) – _description_

get_checkbox(node: ClassifierNode) → HorizontalLayoutBlock

Build and return the wildewidgets.CheckboxInputBlock for the classifier node.

Parameters

node – the classifier data

Returns

A configured wildewidgets.CheckboxInputBlock

block: str = 'classifiers__filter__form'

block is the official wildewidgets name of the block; it can’t be changed

tag: str = 'form'

class sphinx_hosting.wildewidgets.ClassifierFilterBlock(table_name: str, column_number: int, **kwargs)

A wildewidgets.CardWidget that contains the ClassifierFilterForm. This the right of the sphinx_hosting.wildewidgets.project.ProjectTable. This widget is embedded in sphinx_hosting.wildewdigets.project.ProjectTableWidget

Parameters

• table_name – the name of the dataTables table to control

• column_number – the number of the column in the dataTable that contains classifier names

__init__(table_name: str, column_number: int, **kwargs)

name: str = 'classifiers__filter'

The CSS class that will be added to this element to as an identifier for

class sphinx_hosting.wildewidgets.ProjectCreateModalWidget(*args, **kwargs)

This is a modal dialog that holds the sphinx_hosting.forms.ProjectCreateForm.

__init__(*args, **kwargs)

class sphinx_hosting.wildewidgets.ProjectDetailWidget(*blocks, form: Optional[Form] = None, **kwargs)

This widget renders an update form for a sphinx_hosting.models.Project.

Use directly it like so:

>>> project = Project.objects.get(pk=1)
>>> form = ProjectUpdateForm(instance=project)
>>> widget = ProjectDetailWidget(form=form)

Or you can simply add the form to your view context and ProjectDetailWidget will pick it up automatically.

css_class: str = ' p-4'

modifier: str = 'general'

If specified, also add a class named {name}--{modifier} to the CSS

name: str = 'project-detail__section'

The CSS class that will be added to this element to as an identifier for

class sphinx_hosting.wildewidgets.ProjectTableWidget(user: AbstractUser, **kwargs)

This is a wildewidgets.CardWidget that gives our ProjectTable dataTable a nice header with a total book count and an “Add Project” button that opens a modal dialog.

__init__(user: AbstractUser, **kwargs)

class sphinx_hosting.wildewidgets.ProjectTableWidget(user: AbstractUser, **kwargs)

This is a wildewidgets.CardWidget that gives our ProjectTable dataTable a nice header with a total book count and an “Add Project” button that opens a modal dialog.

__init__(user: AbstractUser, **kwargs)

class sphinx_hosting.wildewidgets.ProjectVersionsTableWidget(project_id: int, **kwargs)

This is a wildewidgets.CardWidget that gives our ProjectVersionTable dataTable a nice header with a total version count.

__init__(project_id: int, **kwargs)

class sphinx_hosting.wildewidgets.ProjectTable(*args, actions: Optional[List[RowActionButton]] = None, button_size: Optional[str] = None, justify: Optional[str] = None, **kwargs)

This widget displays a dataTable of our sphinx_hosting.models.Project instances.

It’s used as a the main widget in by ProjectTableWidget.

model

alias of Project

filter_classifiers_column(qs: QuerySet, column: str, value: str) → QuerySet

Filter our results by the value, a comma separated list of sphinx_hosting.models.Classifier names.

Parameters

• qs – the current QuerySet

• colunn – the name of the column to filter on

• value – a comma-separated list of classifier names

Returns

A QuerySet filtered for rows that contain the selected classifiers.

render_classifiers_column(row: Project, column: str) → str

Render our classifiers column.

Parameters

• row – the Project we are rendering

• colunn – the name of the column to render

Returns

A <br> separated list of classifier names

render_latest_version_column(row: Project, column: str) → str

Render our latest_version column. This is the version string of the sphinx_hosting.models.Version that has the most recent sphinx_hosting.models.Version.modified timestamp.

If there are not yet any sphinx_hosting.models.Version instances for this project, return empty string.

Parameters

• row – the Project we are rendering

• colunn – the name of the column to render

Returns

The version string of the most recently published version, or empty string.

render_latest_version_date_column(row: Project, column: str) → str

Render our latest_version_date column. This is the last modified date of the sphinx_hosting.models.Version that has the most recent sphinx_hosting.models.Version.modified timestamp.

If there are not yet any sphinx_hosting.models.Version instances for this project, return empty string.

Parameters

• row – the Project we are rendering

• colunn – the name of the column to render

Returns

The of the most recently published version, or empty string.

alignment: Dict[str, str] = {'classifiers': 'left', 'description': 'left', 'latest_version': 'left', 'latest_version_date': 'left', 'machine_name': 'left', 'title': 'left'}

fields: List[str] = ['title', 'machine_name', 'classifiers', 'latest_version', 'description', 'latest_version_date']

A list of fields that we will list as columns. These are either fields on our model, or defined as render_FIELD_NAME_column methods

hidden: List[str] = ['classifiers', 'machine_name', 'latest_version_date']

page_length: int = 25

striped: bool = True

unsearchable: List[str] = ['lastest_version', 'latest_version_date']

A list of names of columns that will will not be searched when doing a

verbose_names: Dict[str, str] = {'latest_version': 'Latest Version', 'latest_version_date': 'Import Date', 'machine_name': 'Machine Name', 'title': 'Project Name'}

A dict of column name to column label. We use it to override the

class sphinx_hosting.wildewidgets.ProjectVersionTable(*args, **kwargs)

This widget displays a dataTable of our sphinx_hosting.models.Version instances for a particular sphinx_hosting.models.Project.

It’s used as a the main widget in by ProjectVersionTableWidget.

model

alias of Version

__init__(*args, **kwargs) → None

One of our kwargs must be project_id, the pk of the sphinx_hosting.models.Project for which we want to list sphinx_hosting.models.Version objects.

This will get added to the extra_data dict in the kwargs key, from which we reference it.

get_initial_queryset() → QuerySet

Filter our sphinx_hosting.models.Version objects by project_id.

Returns

A filtered QuerySet on sphinx_hosting.models.Version

render_num_images_column(row: Version, column: str) → str

Render our num_images column. This is the number of sphinx_hosting.models.SphinxImage objects imported for this version.

Parameters

• row – the Version we are rendering

• colunn – the name of the column to render

Returns

The number of images for this version.

render_num_pages_column(row: Version, column: str) → str

Render our num_pages column. This is the number of sphinx_hosting.models.SphinxPage objects imported for this version.

Parameters

• row – the Version we are rendering

• colunn – the name of the column to render

Returns

The number of pages for this version.

actions: bool = True

Per row action buttons. If not False, this will simply add a rightmost column named Actions with a button named default_action_button_label which when clicked will take the

alignment: Dict[str, str] = {'created': 'left', 'modified': 'left', 'num_images': 'right', 'num_pages': 'right', 'version': 'left'}

fields: List[str] = ['version', 'num_pages', 'num_images', 'created', 'modified']

A list of fields that we will list as columns. These are either fields on our model, or defined as render_FIELD_NAME_column methods

order_columns: List[str] = ['version']

page_length: int = 25

project_id: Optional[int]

sort_ascending: bool = False

striped: bool = True

unsearchable: List[str] = ['num_pages', 'num_images']

A list of names of columns that will will not be searched when doing a

verbose_names: Dict[str, str] = {'num_images': '# Images', 'num_pages': '# Pages', 'title': 'Version'}

A dict of column name to column label. We use it to override the

ProjectRelatedLinks

class sphinx_hosting.wildewidgets.ProjectRelatedLinkCreateModalWidget(project: Project, *args, **kwargs)

This is a modal dialog that holds the sphinx_hosting.forms.ProjectRelatedLinkForm for creating links.

__init__(project: Project, *args, **kwargs)

class sphinx_hosting.wildewidgets.ProjectRelatedLinkUpdateModalWidget(link: ProjectRelatedLink, *args, **kwargs)

This is a modal dialog that holds the sphinx_hosting.forms.ProjectRelatedLinkForm for updating links.

One of these is created for each sphinx_hosting.models.ProjectRelatedLink object, and lives in the sphinx_hosting.widgets.ProjectRelatedLinksWidget.

__init__(link: ProjectRelatedLink, *args, **kwargs)

class sphinx_hosting.wildewidgets.ProjectRelatedLinksListWidget(*args, remove_url=None, **kwargs)

This widget renders a list of sphinx_hosting.models.ProjectRelatedLink objects as a list of wildewidgets.Link objects.

This is used on the project detail page, and is the read-only version of ProjectRelatedLinksWidget.

item_label: str = 'Related Link'

The label to use for each instance. This is used in the confirmation

class sphinx_hosting.wildewidgets.ProjectRelatedLinksWidget(project: Project, **kwargs)

This is a wildewidgets.CardWidget that allows us to manage the sphinx_hosting.models.ProjectRelatedLink objects for this sphinx_hosting.models.Project.

It renders a list of ProjectRelatedLinkListItemWidget objects and a “Add Related Link” button that opens a modal dialog.

This is used on the project update page, and is the editable version of ProjectRelatedLinksListWidget.

__init__(project: Project, **kwargs)

class sphinx_hosting.wildewidgets.ProjectRelatedLinkListItemWidget(object: ProjectRelatedLink)

This is used by ProjectRelatedLinksWidget to render a single sphinx_hosting.models.ProjectRelatedLink object in its list.

__init__(object: ProjectRelatedLink)

css_class: str = 'mb-2'

Search

These widgets are used on the search results page.

class sphinx_hosting.wildewidgets.GlobalSearchFormWidget(*args, **kwargs)

This widget encapsulates the sphinx_hosting.forms.GlobalSearchForm.

__init__(*args, **kwargs)

css_class: str = 'mb-3'

name: str = 'global-search'

The CSS class that will be added to this element to as an identifier for

class sphinx_hosting.wildewidgets.PagedSearchLayout(results: SearchQuerySet, query: Optional[str] = None, facets: Optional[Dict[str, List[str]]] = None, **kwargs)

This is the page layout for the entire search results page.

Parameters

query – the text entered into the search form that got us to this results page

Keyword Arguments

• query – the text entered into the search form that got us to this results page

• facets – the active facet filters. This will be a dict where the key is the facet name, and the value is a list of facet values to filter by.

__init__(results: SearchQuerySet, query: Optional[str] = None, facets: Optional[Dict[str, List[str]]] = None, **kwargs)

modifier: str = 'paged'

If specified, also add a class named {name}--{modifier} to the CSS

name: str = 'search-layout'

The CSS class that will be added to this element to as an identifier for

class sphinx_hosting.wildewidgets.SearchResultsPageHeader(query: Optional[str], facets: Optional[Dict[str, List[str]]] = None, **kwargs)

The header for the entire search results page. This shows the search string that got us here, and any active facet filters, allowing the user to remove any active filter by clicking the “X” next to the filter name.

Parameters

query – the text entered into the search form that got us to this results page

Keyword Arguments

facets – the active facet filters. This will be a dict where the key is the facet name, and the value is a list of facet values to filter by.

__init__(query: Optional[str], facets: Optional[Dict[str, List[str]]] = None, **kwargs)

block: str = 'search-results__header'

block is the official wildewidgets name of the block; it can’t be changed

css_class: str = 'mb-5'

class sphinx_hosting.wildewidgets.FacetBlock(results: SearchQuerySet, query: Optional[str], **kwargs)

This is a base class for blocks that appear to the right of the search results listing on the search results page that allows you to refine your results by a particular facet that is present in the result set.

Subclass this to create facet filtering blocks for specific facets. Any facet you want to filter by must be defined on your search index by adding faceted=True to the field definition.

Parameters

• results – the Haystack search queryset containing our search results

• query – the text entered into the search form that got us to this results page

__init__(results: SearchQuerySet, query: Optional[str], **kwargs)

facet: str

model: Type[Model]

model_field: str

class sphinx_hosting.wildewidgets.SearchResultsClassifiersFacet(results: SearchQuerySet, query: Optional[str], **kwargs)

A FacetBlock that allows the user to filter search results by classifier.

model

alias of Classifier

facet: str = 'classifiers'

model_field: str = 'name'

title: str = 'Classifiers'

class sphinx_hosting.wildewidgets.SearchResultsProjectFacet(results: SearchQuerySet, query: Optional[str], **kwargs)

A FacetBlock that allows the user to filter search results by project.

model

alias of Project

facet: str = 'project_id'

model_field: str = 'pk'

title: str = 'Projects'

class sphinx_hosting.wildewidgets.PagedSearchResultsBlock(results: SearchQuerySet, query: Optional[str], **kwargs)

This is a paged listing of SearchResultBlock entries describing our search results.

model

alias of SphinxPage

model_widget

alias of SearchResultBlock

__init__(results: SearchQuerySet, query: Optional[str], **kwargs)

class sphinx_hosting.wildewidgets.SearchResultsHeader(results: SearchQuerySet, **kwargs)

The header for the search results listing (not the page header – that is SearchResultsPageHeader).

Parameters

results – the Haystack search queryset containing our search results

__init__(results: SearchQuerySet, **kwargs)

justify: str = 'between'

start, center, end, between, around, evenly. See Bootstrap: Flex, justify content. If not supplied here and justify is None, do whatever horizontal aligment Bootstrap does by default.

name: str = 'search-results__title'

The CSS class that will be added to this element to as an identifier for

class sphinx_hosting.wildewidgets.SearchResultBlock(object: Optional[SearchResult] = None, **kwargs)

This is the block we use for rendering a particular search result on the search results page.

Keyword Arguments

object – the haystack.models.SearchResult object to render

class Header(result: SearchResult, **kwargs)

__init__(result: SearchResult, **kwargs)

name: str = 'search-result__header'

The CSS class that will be added to this element to as an identifier for

__init__(object: Optional[SearchResult] = None, **kwargs)

block: str = 'search-result'

block is the official wildewidgets name of the block; it can’t be changed

Versions

class sphinx_hosting.wildewidgets.VersionInfoWidget(version: Version, **kwargs)

This widget gives a wildewidget.Datagrid type overview of information about this version:

• A link to the project that owns this sphinx_hosting.models.Version

• Create and last modified timestamps

• What version of Sphinx was used to generate the pages

Parameters

version – the Version object we’re describing

__init__(version: Version, **kwargs)

class sphinx_hosting.wildewidgets.VersionSphinxPageTableWidget(version_id: int, **kwargs)

This is a wildewidgets.CardWidget that gives our VersionSphinxPageTable dataTable a nice header with a total page count.

__init__(version_id: int, **kwargs)

class sphinx_hosting.wildewidgets.VersionUploadBlock(*blocks, form=None, **kwargs)

This block holds the upload form for uploading documentation tarballs. Once uploaded, the tarball will be run through sphinx_hosting.importers.SphinxPackageImporter to actually import it into the database.

__init__(*blocks, form=None, **kwargs)

css_class: str = 'my-3 border'

class sphinx_hosting.wildewidgets.VersionSphinxImageTableWidget(version_id: int, **kwargs)

This is a wildewidgets.CardWidget that gives our VersionSphinxImageTable dataTable a nice header with a total image count.

__init__(version_id: int, **kwargs)

class sphinx_hosting.wildewidgets.VersionSphinxPageTable(*args, **kwargs)

This widget displays a dataTable of our sphinx_hosting.models.SphinxPage instances for a particular sphinx_hosting.models.Version.

It’s used as a the main widget in by VersionSphinxPageTableWidget.

model

alias of SphinxPage

__init__(*args, **kwargs) → None

One of our kwargs must be version_id, the pk of the sphinx_hosting.models.Version for which we want to list sphinx_hosting.models.SphinxPage objects.

This will get added to the extra_data dict in the kwargs key, from which we reference it.

get_initial_queryset() → QuerySet

Filter our sphinx_hosting.models.SphinxPage objects by version_id.

actions: bool = True

Per row action buttons. If not False, this will simply add a rightmost column named Actions with a button named default_action_button_label which when clicked will take the

alignment: Dict[str, str] = {'relative_path': 'left', 'size': 'right', 'title': 'left'}

A mapping of field name to field alignment. Valid values are left, right, and

fields: List[str] = ['title', 'relative_path', 'size']

This is either None, the string __all__ or a list of column names to use in our table. For the list, entries can either be field names from our model, or names of computed fields that will be rendered with a render_FIELD_column method. If None, empty list

page_length: int = 25

striped: bool = True

version_id: Optional[int]

class sphinx_hosting.wildewidgets.VersionSphinxImageTable(*args, **kwargs)

This widget displays a dataTable of our sphinx_hosting.models.SphinxImage instances for a particular sphinx_hosting.models.Version.

It’s used as a the main widget in by VersionSphinxImageTableWidget.

model

alias of SphinxImage

__init__(*args, **kwargs) → None

One of our kwargs must be version_id, the pk of the sphinx_hosting.models.Version for which we want to list sphinx_hosting.models.SphinxPage objects.

This will get added to the extra_data dict in the kwargs key, from which we reference it.

get_initial_queryset() → QuerySet

Filter our sphinx_hosting.models.SphinxPage objects by version_id.

render_file_path_column(row: Version, column: str) → str

Render our file_path column. This is the path to the file in MEDIA_ROOT.

Parameters

• row – the Version we are rendering

• colunn – the name of the column to render

Returns

The size in bytes of the uploaded file.

render_size_column(row: Version, column: str) → str

Render our size column. This is the size in bytes of the sphinx_hosting.models.SphinxImage.file field.

Parameters

• row – the Version we are rendering

• colunn – the name of the column to render

Returns

The size in bytes of the uploaded file.

alignment: Dict[str, str] = {'file_path': 'left', 'orig_path': 'left', 'size': 'right'}

A mapping of field name to field alignment. Valid values are left, right, and

fields: List[str] = ['orig_path', 'file_path', 'size']

This is either None, the string __all__ or a list of column names to use in our table. For the list, entries can either be field names from our model, or names of computed fields that will be rendered with a render_FIELD_column method. If None, empty list

page_length: int = 25

striped: bool = True

version_id: Optional[int]

Sphinx Pages

class sphinx_hosting.wildewidgets.SphinxPageGlobalTableOfContentsMenu(*items: MenuItem, title: Optional[str] = None, title_tag: Optional[str] = None, title_css_classes: Optional[str] = None, **kwargs)

This is the version-specific navigation menu that gets inserted into the page sidebar when viewing the documentation for a sphinx_hosting.models.Version. It will appear on all pages for that version.

classmethod parse_obj(version: Version) → SphinxPageGlobalTableOfContentsMenu

Parse the globaltoc of a sphinx_hosting.models.Version into a wildewidgets.Menu suitable for insertion into a wildewidgets.Navbar

The sphinx_hosting.models.Version.globaltoc is a dict that looks like this:

{
    items: [
        {'text': 'foo'},
        {'text': 'bar', 'url': '/foo', 'icon': 'blah'}
        {'text': 'bar', 'url': '/foo', 'icon': 'blah', items: [{'text': 'blah' ...} ...]}
        ...
    ]
}

Parameters

version – the Version for which we are building the menu

Returns

A configured SphinxPageGlobalTableOfContentsMenu.

css_class: str = 'mt-4'

title_css_classes: str = 'mt-3'

class sphinx_hosting.wildewidgets.SphinxPageLayout(page: SphinxPage, **kwargs)

The page layout for a single sphinx_hosting.models.SphinxPage. It consists of a two column layout with the page’s table of contents in the left column, and the content of the page in the right column.

Parameters

page – the SphinxPage to render

__init__(page: SphinxPage, **kwargs)

class sphinx_hosting.wildewidgets.SphinxPagePagination(page: SphinxPage, **kwargs)

This widget draws the “Previous Page”, Parent Page and Next Page buttons that are found at the top of each sphinx_hosting.views.SphinxPageDetailView.

It is built out of a Tabler/Bootstrap row, with each of the buttons in an equal sized col.

__init__(page: SphinxPage, **kwargs)

name: str = 'sphinxpage-pagination'

The CSS class that will be added to this element to as an identifier for

class sphinx_hosting.wildewidgets.SphinxPageTitle(page: SphinxPage, **kwargs)

The title block for a sphinx_hosting.models.SphinxPage page.

Parameters

page – the SphinxPage to render

__init__(page: SphinxPage, **kwargs)

block: str = 'sphinxpage-title'

block is the official wildewidgets name of the block; it can’t be changed

css_class: str = 'mb-5'

class sphinx_hosting.wildewidgets.SphinxPageBodyWidget(page: SphinxPage, **kwargs)

This widget holds the body of the page. The body as stored in the model is actually a Django template, so we retrieve the body, run it through the Django template engine, and display the results.

Parameters

page – the SphinxPage we are rendering

__init__(page: SphinxPage, **kwargs)

css_class: str = 'sphinxpage-body'

class sphinx_hosting.wildewidgets.SphinxPageTableOfContentsWidget(page: SphinxPage, **kwargs)

This widget draws the in-page navigation – the header hierarchy.

Parameters

page – the SphinxPage we are rendering

__init__(page: SphinxPage, **kwargs)

css_class: str = 'sphinxpage-toc'