==========================
Tutorial: Creating Plugins
==========================

.. admonition:: Choose your tutorial

   django-resume supports two types of plugins. Choose the tutorial that matches your needs:

   - **Simple Plugins**: Single-form plugins like "About", "Motto", or "Contact Info"
   - **List Plugins**: Multi-item plugins like "Projects", "Certifications", or "Jobs"

Overview
========

Plugins in django-resume are Python classes that define how specific sections
of a resume are displayed and edited. Each plugin handles its own data,
provides forms for editing, and renders content using templates.

Custom plugins are filesystem-based: you add Python modules to your project,
store templates on disk, and register the plugin classes from Python code.
Database-backed plugins are no longer supported.

Plugin Types
============

django-resume provides two base plugin types:

**SimplePlugin**
   For plugins with a single form and straightforward data structure.
   
   Examples: About section, personal motto, contact information, availability status.
   
   **When to use**: When you need to store and display a single piece of content
   that doesn't need to be broken into multiple items.

**ListPlugin**
   For plugins that manage collections of related items.
   
   Examples: Work experience, projects, certifications, education, skills.
   
   **When to use**: When users need to add, edit, and manage multiple related items
   with individual forms and ordering.

Choose Your Tutorial
====================

.. admonition:: New to django-resume plugins?

   **Start here**: :doc:`creating_simple_plugins`
   
   Learn the basics with a simple "Motto" plugin that displays an inspirational quote.
   This tutorial covers all the fundamental concepts without complexity.

.. admonition:: Need to manage multiple items?

   **Go to**: :doc:`creating_list_plugins`
   
   Learn to build complex plugins that handle lists of items, like certifications
   or work experience. This tutorial covers advanced concepts like positioning,
   item management, and multiple templates.

Tutorial Comparison
===================

+-------------------------+----------------------+------------------------+
| Feature                 | Simple Plugin        | List Plugin            |
+=========================+======================+========================+
| **Complexity**          | Low                  | High                   |
+-------------------------+----------------------+------------------------+
| **Forms needed**        | 1 form class         | 2 form classes         |
+-------------------------+----------------------+------------------------+
| **Templates needed**    | 2 templates          | 5 templates            |
+-------------------------+----------------------+------------------------+
| **Data structure**      | Single object        | Array of objects       |
+-------------------------+----------------------+------------------------+
| **Position management** | Not needed           | Required               |
+-------------------------+----------------------+------------------------+
| **Individual editing**  | Section only         | Section + items        |
+-------------------------+----------------------+------------------------+
| **Example use cases**   | About, Motto, Theme  | Projects, Jobs, Certs  |
+-------------------------+----------------------+------------------------+

Quick Start Recommendations
===========================

**For beginners or simple content**:
   Start with :doc:`creating_simple_plugins` to learn the fundamentals.

**For experienced developers**:
   Jump to :doc:`creating_list_plugins` if you need to manage multiple items.

**Not sure which to choose?**
   Ask yourself: "Will users want to add multiple instances of this content?"
   
   - **Yes** → Use List Plugin
   - **No** → Use Simple Plugin

Supported Custom Plugin Workflow
================================

Custom plugins are added in three parts:

1. Write the plugin class in your Django project.
2. Add the plugin templates under ``templates/django_resume/plugins/...``.
3. Register the plugin class from your app's Python code, usually in
   ``AppConfig.ready()``.

This keeps plugin behavior explicit and version-controlled alongside the rest
of your project code.

.. toctree::
   :hidden:

   creating_simple_plugins
   creating_list_plugins