کاربر:Alavi/صفحه تمرین

راهنمای ماژول QuoteCard

📌 معرفی ماژول

این ماژول برای ایجاد کارت‌های نقل‌قول با استایل‌های مختلف در ویکی‌شیعه طراحی شده است.

با استفاده از این ماژول، می‌توان نقل‌قول‌ها را با فونت، رنگ، انیمیشن و سبک‌های متنوع نمایش داد.

🛠 جزئیات خط به خط کد و نحوه عملکرد آن

📦 تعریف متغیرهای اصلی

local p = {}  -- ایجاد جدول اصلی ماژول
local mw = require('mw')  -- بارگذاری کتابخانه MediaWiki

🔹 p یک جدول خالی است که در پایان ماژول مقداردهی و بازگردانی می‌شود.

🔹 mw ماژول داخلی MediaWiki را بارگیری می‌کند که ابزارهای لازم برای پردازش ورودی‌ها را فراهم می‌کند.

---

🛡️ تابع ایمن‌سازی ورودی‌ها

local function escape(s)
    return mw.text.encode(tostring(s or ""))
end

🔹 این تابع مقدار ورودی را ایمن‌سازی می‌کند تا از اجرای کدهای مخرب جلوگیری شود.

🔹 مقدار ورودی را ابتدا رشته (string) می‌کند و سپس آن را کدگذاری (encode) می‌نماید.

🔹 اگر مقدار ورودی nil باشد، مقدار پیش‌فرض "" را در نظر می‌گیرد.

---

🧩 تابع دریافت مقدار از ورودی (با پشتیبانی از چند کلید مختلف)

local function getInput(args, keys, default)
    for _, key in ipairs(keys) do
        if args[key] then
            local value = mw.getCurrentFrame():preprocess(args[key])
            return mw.text.decode(value)
        end
    end
    return mw.text.decode(mw.getCurrentFrame():preprocess(default))
end

🔹 این تابع مقدار یک ورودی را از چندین کلید ممکن دریافت می‌کند.

🔹 مثلاً برای دریافت مقدار title، هم "عنوان" و هم "title" بررسی می‌شود.

🔹 در صورت نبود مقدار، مقدار پیش‌فرض (default) را برمی‌گرداند.

---

🎨 تابع دریافت رنگ از ورودی‌ها

local function getColor(args, keys, default)
    return escape(getInput(args, keys, default))
end

🔹 این تابع مانند getInput عمل می‌کند اما مقدار را با escape ایمن‌سازی می‌کند.

🔹 برای رنگ‌ها استفاده می‌شود تا مقادیر غیرمجاز حذف شوند.

---

🗺️ جدول‌های نگاشت (Mapping)

local fontMapping = {
    ["nastaliq"] = "font-nastaliq",
    ["نستعلیق"] = "font-nastaliq",

    ["moalla"] = "font-moalla",
    ["معلی"] = "font-moalla",

    ["yekan"] = "font-yekan",
    ["یکان"] = "font-yekan",

    ["iranbold"] = "font-iranbold",
    ["ایران_بولد"] = "font-iranbold",
    ["ایران بولد"] = "font-iranbold",

    ["arial"] = "font-arial",
    
    ["iransansxlight"] = "font-iransansxlight"
}

🔹 فونت‌های مختلف به کلاس‌های CSS مربوطه نگاشت می‌شوند.

🔹 اگر کسی "نستعلیق" یا "nastaliq" را وارد کند، کلاس font-nastaliq استفاده خواهد شد.

🔹 این نگاشت برای جهت، انیمیشن و سبک کارت نیز به‌کار رفته است.

---

🎨 تابع دریافت کلاس فونت

local function getFontClass(font)
    local fontClass = fontMapping[font]
    return fontClass or "font-default"  -- مقدار پیش‌فرض
end

🔹 مقدار ورودی را از fontMapping جستجو کرده و کلاس مناسب را برمی‌گرداند.

🔹 اگر مقدار یافت نشود، مقدار پیش‌فرض font-default استفاده می‌شود.

---

📍 تابع دریافت کلاس جهت (Align)

local function getAlignClass(align)
    return alignMapping[align] or alignMapping["center"]
end

🔹 مقدار جهت (چپ، راست، وسط) را دریافت و کلاس مناسب را برمی‌گرداند.

🔹 مقدار پیش‌فرض وسط (center) است.

---

🌟 تابع دریافت کلاس انیمیشن

local function getAnimationClass(animation)
    return animationMapping[animation] or ""
end

🔹 مقدار ورودی را در animationMapping جستجو کرده و کلاس مناسب را برمی‌گرداند.

🔹 مقدار پیش‌فرض بدون انیمیشن ("") است.

---

🖋️ بارگذاری استایل‌های CSS

local templatestyles = mw.getCurrentFrame():extensionTag{
    name = 'templatestyles',
    args = { src = 'Module:QuoteCard/styles.css' }
}

🔹 استایل‌های مربوط به ماژول را از فایل styles.css بارگذاری می‌کند.

🔹 این کار باعث جداسازی استایل از کد و بهبود مدیریت CSS می‌شود.

---

🖋️ تابع اصلی برای رندر نقل‌قول

function p.render(frame)
    local args = frame:getParent().args

🔹 تابع اصلی که داده‌ها را پردازش و HTML مربوط به نقل‌قول را تولید می‌کند.

🔹 args شامل ورودی‌های الگو (Template) است.

📝 دریافت ورودی‌های مختلف

    local title = getInput(args, {"عنوان", "title"}, "نقل‌قول")
    local text = getInput(args, {"متن", "text"}, "متن نقل‌قول اینجا قرار می‌گیرد.")
    local author = getInput(args, {"نویسنده", "author"}, "ناشناس")

🔹 مقدار عنوان، متن و نویسنده را دریافت کرده و مقدار پیش‌فرض برای آن‌ها تعیین می‌شود.

🎨 دریافت رنگ‌ها

local titleColor = getColor(args, {"رنگ عنوان", "titleColor"}, "#2ca58d")
    local textColor = getColor(args, {"رنگ متن", "textColor"}, "#333333")
    local authorColor = getColor(args, {"رنگ نویسنده", "authorColor"}, "#8b0000")

🔹 رنگ‌های عنوان، متن و نویسنده را دریافت می‌کند.

📌 دریافت کلاس‌های مربوط به استایل و انیمیشن

    local textFontClass = getFontClass(fontFamily)
    local alignClass = getAlignClass(align)
    local animationClass = getAnimationClass(animation)
    local quoteClass = getStyleClass(style)

🔹 این بخش کلاس‌های فونت، جهت، انیمیشن و سبک نقل‌قول را تعیین می‌کند.

📦 تولید HTML نقل‌قول

    return templatestyles .. string.format([[
        <div class="quote-card%s%s%s%s">
            <div class="quote-title" style="color:%s;">%s</div>
            <div class="quote-text %s" style="color:%s;">%s</div>
            <div class="quote-author" style="color:%s;">%s</div>
        </div>
    ]],
        animationClass ~= "" and (" " .. animationClass) or "",
        quoteClass ~= "" and (" " .. quoteClass) or "",
        alignClass ~= "" and (" " .. alignClass) or "",
        customClass ~= "" and (" " .. customClass) or "",
        titleColor, title,
        textFontClass, textColor, text,
        authorColor, author
    )
end

🔹 HTML کارت نقل‌قول را تولید می‌کند.

🔹 درصورتی‌که مقدار انیمیشن، استایل یا جهت‌دهی وجود داشته باشد، به کلاس اضافه می‌شود.

---

📤 بازگردانی ماژول

return p

🔹 در پایان، ماژول برگردانده می‌شود تا در ویکی‌شیعه قابل استفاده باشد.

🚀 چگونه می‌توان ماژول را ارتقا داد؟

✅ اضافه کردن سبک‌های جدید (Style)

✅ اضافه کردن فونت‌های بیشتر

✅ پشتیبانی از تنظیمات بیشتر مثل حاشیه یا سایه‌ها

✅ اضافه کردن انیمیشن‌های متنوع‌تر