The Plugin API

About this document

This reference covers the main classes and methods of django-resume’s plugin architecture. It assumes familiarity with how plugins are registered and included in a django-resume project.

Plugin Attributes

Each plugin provides several class attributes to identify and configure it in the plugin registry.

django_resume.plugins.name

A string used to identify the plugin in the plugin registry. This must be unique among all installed plugins.

django_resume.plugins.verbose_name

A human-readable name for the plugin. Used in the Django admin interface and other user-facing areas.

Plugin Methods

Plugins must implement or can optionally override the following methods to integrate seamlessly with django-resume:

django_resume.plugins.get_context(request, plugin_data, resume_pk, *, context, edit=False, theme='plain')

Returns the object (often a dictionary) to be stored in the template context under this plugin’s key. Typical usage is to take the plugin’s data (e.g., from the resume’s stored data or a form) and prepare it for display.

Note

The resume_pk parameter must be passed because it might be needed to generate edit URLs or other links that are unique to the current resume. Often, resume_pk is not included in plugin_data, so it’s important to have it as a separate parameter.

Parameters:

  • request – The current HttpRequest instance.

  • plugin_data – A dict containing the plugin’s data (if any).

  • resume_pk – The primary key of the parent Resume object.

  • context – The existing template context for the resume.

  • edit – A boolean indicating whether the resume is in edit mode.

  • theme – The string name of the current resume theme, e.g. "plain".

Returns:

An object (commonly a dictionary) that is merged into the overall resume’s context.

django_resume.plugins.get_data(resume)

Returns the plugin’s data for the given resume. This typically returns a dictionary that can be rendered or manipulated by the plugin’s forms.

Parameters:

resume – A Resume instance.

Returns:

A dict containing the plugin’s data for the specified resume.

Returns a string of HTML linking to the plugin’s admin change view, typically used in Django admin to allow quick editing of plugin data.

Parameters:

resume_id – The primary key of the Resume object.

Returns:

A string containing HTML markup for a link.

django_resume.plugins.get_admin_urls(admin_view)

Returns the URL patterns required for the plugin’s admin interface. Typically, this is a list of Django path() entries for editing or viewing plugin-specific data in the admin.

Parameters:

admin_view – A callable usually wrapped with Django’s admin decorators.

Returns:

A list (or list-like) of URLs (patterns) used by the plugin’s admin functionality.

django_resume.plugins.get_inline_urls()

Returns URL patterns used to manage the plugin’s data “inline,” outside of the full Django admin. This is especially useful for front-end editing (inline editing) or simpler UIs.

Returns:

A list (or list-like) of URLs (patterns) for inline editing.

Export hooks

A content plugin can opt into the import/export framework with two optional export methods (both default to “nothing exported” on the base classes):

  • get_structured_data(resume) -> dict returns format-neutral, normalized facts (stable field names, machine-readable values) for the resume.

  • get_export_adapters() -> dict maps a format id (e.g. "json_resume") to an export adapter.

An export adapter declares owned_paths (the JSON Pointers it writes) and multivalued_paths (array paths several adapters may concatenate into), and implements export(facts) -> AdapterExport returning contributions ((pointer, value) pairs, each pointer one of owned_paths) and notes (dropped fields or other diagnostics surfaced in the export report).

Import hooks

Plugins can opt into JSON Resume import with get_import_adapters() -> dict. The base classes return an empty mapping. An import adapter declares source_paths (JSON Pointers it consumes) and implements import_data(document) -> AdapterImport. The returned plugin_data is stored under that plugin’s name when a portable JSON Resume document is imported. Import source paths must be unique and non-overlapping across adapters; conflicts abort the import as configuration errors.

For django-resume round-trip exports, meta.django_resume.plugin_data is restored before portable adapters are used. This preserves plugin fields that do not have a standard JSON Resume representation. Restored plugin data is accepted only when the envelope is an object of plugin-name keys to object payloads.

For imported JSON Resume documents, django-resume stores the parsed source document, the adapter-generated projection, and the imported plugin-data snapshot in resume integration state. If a later export sees the same projection and the same plugin data, it re-emits the parsed source document so unsupported standard fields owned by no bundled plugin are not lost during an unchanged import/export check. Once plugin data changes, export uses the current plugin adapters and the normal django-resume extension envelope.

The bundled timeline import adapter maps the portable JSON Resume /work array into employed_timeline and reports that JSON Resume does not preserve the django-resume freelance/employed split. Plugins that need a different portable split should provide their own import adapter or use meta.django_resume.plugin_data for exact round trips. Import adapters should add report notes for any standard JSON Resume fields they deliberately ignore or normalize.

Usage Example

Below is a minimal plugin demonstrating how to implement these methods. By default, the name and verbose_name fields are required, along with definitions for get_context, get_data, get_admin_link, get_admin_urls, and get_inline_urls:

class SomeNewPlugin:
    name: str = "some_new_plugin"
    verbose_name: str = "Some New Plugin"

    def get_context(self, request, plugin_data, resume_pk, *, context, edit=False, theme="plain"):
        # Return a dictionary or other object to merge into the resume's context
        # Note: resume_pk may be needed to generate resume-specific URLs
        return {"some_data": plugin_data.get("some_key", "default")}

    def get_data(self, resume):
        # Return the plugin data from the resume
        return resume.plugin_data.get(self.name, {})

    def get_admin_link(self, resume_id):
        # Typically returns an HTML <a> element linking to a change form
        url = reverse(f"admin:{self.name}-admin-change", kwargs={"resume_id": resume_id})
        return format_html('<a href="{}">Edit {}</a>', url, self.verbose_name)

    def get_admin_urls(self, admin_view):
        return [
            path(
                f"<int:resume_id>/plugin/{self.name}/change/",
                admin_view(self.some_admin_view),
                name=f"{self.name}-admin-change",
            ),
            # add more URLs as needed
        ]

    def get_inline_urls(self):
        return [
            path(
                f"<int:resume_id>/plugin/{self.name}/edit/",
                self.some_inline_view,
                name=f"{self.name}-edit",
            ),
            # add more URLs as needed
        ]

By adhering to these method signatures, django-resume can detect and manage your plugin automatically, making its data available in both the admin interface and the front-end inline editing views.