צינור הנכסים

הנכסים של האתר (CSS, JS, SCSS) לא נכתבים ידנית ל-<head>. הקוד רושם אותם ב-PAGE, והליבה מפיקה מהם את התגים, מוסיפה גרסה לכתובת, מקמפלת SCSS ומאחדת קבצים לקבוצות. בעמוד הזה: איך רושמים נכסים, איך עובד .scss.css, איך בונים קבוצות minify, איפה מנהלים סקריפטים חיצוניים, ואיך הגרסה (attaches_version) מנקה מטמונים.

רישום נכס#

הרישום נעשה מקוד ה-PHP של ה-theme, של הבקר או של application/includes. החתימות המלאות ב-PAGE API וב-ref-page; כאן מה שחשוב לצינור:

// בתוך TEMPLATE_default::index() או בבקר
PAGE::add_asset("themes/default/style.scss.css");                 // head, בסוף הרשימה
PAGE::add_asset("themes/default/app.js", false, "body_end");      // סוף ה-body
PAGE::add_asset_advanced("themes/default/slider.js", [
    "area"  => "body_end",
    "defer" => true,
]);
PAGE::add_asset_advanced("themes/default/chat.js", [
    "after_user_intraction" => true,   // נטען רק בלחיצה או במקש הראשון
]);

כל נכס נפלט כתג בהתאם לסיומת. לכתובת יחסית מתווספים פרוטוקול ו-original_site_url, ולכל כתובת (CSS וגם JS) מתווסף ?ver=<attaches_version> (MISC::add_querystring_var), כך שהדפדפן וה-CDN מביאים גרסה חדשה אחרי שהגרסה עולה.

SCSS: כתובות .scss.css#

הדפדפן לא יודע לטעון SCSS, אז הליבה מגישה קבצי SCSS מתחת לכתובת שנגמרת ב-.scss.css. ה-ROUTER מזהה את הסיומת ומעביר ל-minify::scss:

כלומר ב-HTML כותבים themes/default/style.scss.css, ועל הדיסק יושב themes/default/style.scss. FILES::scss($file) עושה את העבודה:

1. מסיר query ו-hash מהכתובת. כתובת חיצונית (עם דומיין אחר) מחזירה false.
2. מאתר את קובץ המקור. אם אין .scss אבל יש .css פיזי באותו שם, מוחזר תוכן ה-CSS כמות שהוא. קובץ .css רגיל נקרא ישירות.
3. בודק מטמון: cache/<SERVER_NAME>/scss/<file>ver=<attaches_version>.css. קובץ מטמון ריק נחשב שריד מכתיבה שנקטעה ומקומפל מחדש.
4. מקמפל עם ScssPhp בפלט COMPRESSED, כשתיקיית המקור היא נתיב ה-@import. כך @import "variables" בתוך style.scss מוצא את _variables.scss שלידו.
5. מתקן url(...) יחסיים לנתיבים מוחלטים משורש האתר (נתיבים עם http, data: או / בתחילתם נשארים).
6. כותב את המטמון ומחזיר את ה-CSS. כשל קומפילציה (חריגה של ScssPhp) מחזיר false.

// themes/default/style.scss
@import "variables";
@import "header";

.hero {
    padding-inline: 1rem;
    background: $brand;
}

קבוצות minify#

בעמוד רגיל כל נכס הוא בקשה נפרדת. קבוצת minify מאחדת כמה קבצים לבקשה אחת, minify/<id>.js או minify/<id>.css. הקבוצות מוגדרות בשתי טבלאות:

הניהול בפאנל minify של האדמין (ADMINMODULE_minify): רשימת קבוצות, ולחיצה כפולה על קבוצה פותחת את רשימת הקבצים שלה. שינוי בפאנל מנקה את מפתחות המטמון minify_groups ו-minify.

בטעינת העמוד, PAGE::load קורא את שתי הטבלאות (מהמטמון, 30 יום) ורושם כל קבוצה שה-theme שלה ריק או שווה ל-theme הנוכחי. קבצים ששייכים לקבוצה לא נפלטים בנפרד. אפשר גם לרשום קבוצה ידנית:

PAGE::add_asset_group(3);   // מזהה הקבוצה ב-minify_groups

מה minify::index עושה#

1. טוען את הקבוצה לפי ה-id שבכתובת.
2. JS: מדביק את כל הקבצים לפי ord ומעביר ב-JShrink.
3. CSS: קבצי .scss.css עוברים FILES::scss, שאר הקבצים נטענים ב-include(), וכל url(...) יחסי נכתב מחדש לנתיב מוחלט. התגובה נשלחת עם Expires ו-Cache-Control של שבוע, ועם 304 כשהדפדפן שלח If-Modified-Since חדש מספיק.
4. אם התוצאה אינה ריקה היא נכתבת ל-cache/<SERVER_NAME>/minify/<id>.<type>ver=<ver>.<type> (קובץ זמני ואז rename, כדי שקורא לא יתפוס קובץ חצי כתוב). תוצאה ריקה לא נשמרת.

סקריפטים חיצוניים וניהול תגיות#

לסקריפטים של צד שלישי (אנליטיקס, פיקסלים, צ'אט) יש שני מנגנונים, ושניהם בלי שינוי קוד:

תגי ה-tag manager לא נכתבים ל-HTML של העמוד. הם מוגשים כ-JS מהכתובת /tag_manager.js?id=<group_id>, שמחזירה applyTags([...]), ו-system.js מזריק כל תג למקום שנבחר (head, body_start או body_end). את תג ה-<script src> של קבוצה מסוימת מוסיפים בעצמכם (למשל כנכס או כסקריפט בפאנל Scripts); הליבה מוסיפה אוטומטית רק את tag_manager.js?id=system, כשקיים הקובץ system/system_tags.json. אפשר לסנן לפי מפתח: ?keys=checkout,cart מחזיר רק תגים עם page_key מתאים, ותג בלי page_key נטען תמיד. תגים עם environment שלא תואם ל-CONFIG::$environment מסוננים בשרת. תג שסומן is_after_done נטען רק אחרי שכל הסקריפטים החיצוניים של אותה קבוצה הסתיימו.

התשובה של tag_manager.js עם no-store, ולכל כתובת מקומית בתוכה (src או href) מתווסף ver. התגים עצמם נשמרים במטמון הפריטים tag_manager.

attaches_version: ניקוי מטמונים#

attaches_version היא שורה בטבלת params (קריאה: PARAMS::get('attaches_version')). היא מספר שעולה ב-1 בכל פעולת "ניקוי מטמון" מהאדמין (Tools::delete_cache) ובכל עדכון גרסה של הליבה. הערך משתתף ב:

• ?ver= בכל נכס ש-PAGE פולט.
• שם קובץ המטמון של SCSS ושל קבוצות minify.
• הכתובת tag_manager.js?id=...&ver=....

כך נוצרת כתובת חדשה, והדפדפן וה-CDN מושכים גרסה חדשה בלי ניקוי ידני. המשמעות המעשית אחרי פריסה: שינוי ב-.scss או ב-.js לא יופיע עד שמנקים מטמון (ראו cache-admin).

ראו גם#

• PAGE API: חתימות add_asset, add_asset_advanced, add_asset_group ושאר הממשק
• Themes: איפה רושמים נכסים של theme
• תגיות SEO: מה עוד נכנס ל-<head>
• Frontend runtime: system.js וטעינת הנכסים בדפדפן
• מצב הסוואה: שינוי הכתובות minify/ ו-tag_manager.js ב-HTML
• ניקוי מטמון ו-מטמון עמודים