# 1. 导入所需的基础类和模块

# 从插件管理模块导入基类 BasePlugin
# 所有自定义插件都应该继承这个基类，它提供了插件的基本结构和生命周期管理
from djangoblog.plugin_manage.base_plugin import BasePlugin

# 导入钩子管理模块
# 这个模块提供了注册和触发钩子的功能
from djangoblog.plugin_manage import hooks

# 从常量定义文件导入文章内容钩子的名称
# 使用常量可以避免硬编码字符串，增加代码的可读性和可维护性
# ARTICLE_CONTENT_HOOK_NAME 的值很可能就是 'article_content' 或类似的字符串
from djangoblog.plugin_manage.hook_constants import ARTICLE_CONTENT_HOOK_NAME


# 2. 定义插件主类

# 定义一个名为 ArticleCopyrightPlugin 的类，并让它继承自 BasePlugin
class ArticleCopyrightPlugin(BasePlugin):
    # 定义插件的元数据，这些信息通常会在后台管理界面显示
    PLUGIN_NAME = '文章结尾版权声明'            # 插件的显示名称
    PLUGIN_DESCRIPTION = '一个在文章正文末尾添加版权声明的插件。' # 插件的详细描述
    PLUGIN_VERSION = '0.2.0'                 # 插件的版本号
    PLUGIN_AUTHOR = 'liangliangyy'           # 插件的作者

    # 3. 实现钩子注册方法 (关键步骤)
    def register_hooks(self):
        """
        这个方法是插件与系统交互的入口。
        当插件被加载时，系统会调用这个方法，让插件有机会注册自己的功能。
        """
        # 使用 hooks.register() 函数来注册钩子
        # 参数1: 要注册到哪个钩子上。这里我们使用导入的常量 ARTICLE_CONTENT_HOOK_NAME，
        #        它指向文章内容处理的那个钩子。
        # 参数2: 当钩子被触发时，要执行的函数。这里是 self.add_copyright_to_content，
        #        即当前类的 add_copyright_to_content 方法。
        hooks.register(ARTICLE_CONTENT_HOOK_NAME, self.add_copyright_to_content)

    # 4. 定义插件的核心功能方法
    def add_copyright_to_content(self, content, *args, **kwargs):
        """
        这是插件的核心逻辑所在。
        当文章内容钩子被触发时，这个方法会被调用。

        :param content: 文章的原始 HTML 内容。
        :param *args:   预留参数，方便未来扩展。
        :param **kwargs: 一个包含额外上下文信息的字典，比如当前的文章对象。
        :return: 经过处理后、添加了版权声明的新内容。
        """
        # 从 kwargs 中获取当前的文章对象 (Article instance)
        # 使用 .get() 方法是一个好习惯，如果 'article' 键不存在，它会返回 None 而不是抛出错误
        article = kwargs.get('article')

        # 做一个安全检查：如果文章对象不存在，或者钩子在没有文章上下文的情况下被调用，
        # 就直接返回原始内容，不做任何处理。
        if not article:
            return content

        # 构建版权声明的 HTML 字符串
        # 使用 f-string (格式化字符串字面值) 来方便地插入变量
        # <hr> 会插入一条水平线，<p> 标签包裹版权信息。
        copyright_info = f"\n<hr><p>本文由 {article.author.username} 原创，转载请注明出处。</p>"

        # 将原始内容和版权声明拼接起来，并返回新的内容
        return content + copyright_info


# 5. 实例化插件 (关键步骤)
# 这行代码非常重要。当 Python 解释器加载这个文件时，它会执行这行代码。
# 1. 创建一个 ArticleCopyrightPlugin 类的实例。
# 2. 这个实例化过程会调用父类 BasePlugin 的 __init__ 构造方法。
# 3. 在 BasePlugin 的 __init__ 方法中，会自动调用我们上面定义的 register_hooks() 方法。
# 4. 这样，插件就完成了自身的注册，静静地等待着文章内容钩子被触发。
plugin = ArticleCopyrightPlugin()