SeoSuite.cfc

/**
 * wheels-seo-suite — Wheels package providing SEO tooling.
 *
 * Supplies meta-tag rendering, Open Graph / Twitter Card output, canonical
 * URLs, custom third-party meta, XML sitemaps, robots.txt output, a
 * database-backed per-page meta loader, and an in-page debug/admin panel.
 *
 * Mixin methods are injected into the controller target, which makes them
 * available in controller actions and in view templates (Wheels views run
 * inside the controller's variables scope).
 *
 * Mixin methods available in controllers and views:
 *   whlsSeoSet(key, value)               Set SEO value on request.seo
 *   whlsSeoGet(key, defaultValue)        Read from request.seo with fallback
 *   whlsSeoMetaTags()                    <title> + description + keywords
 *   whlsSeoOpenGraphTags()               Open Graph + Twitter Card meta
 *   whlsSeoCanonicalTag()                <link rel="canonical">
 *   whlsSeoCustomTags()                  Custom/third-party meta tags
 *   whlsSeoAddSitemapUrl(url, ...)       Register an additional sitemap URL
 *   whlsSeoSitemap()                     XML sitemap document
 *   whlsSeoRobots()                      robots.txt content
 *   whlsSeoDebugPanel()                  Render the debug/admin panel
 *   whlsSeoLoadFromDatabase(route, ...)  Load per-page meta from DB
 *   whlsSeoAdminSave()                   Persist admin-panel edits
 */
component hint="wheels-seo-suite" output="false" mixin="controller" {

    public any function init() {
        this.version = "2.0.0";

        $setDefaultSettings();
        $loadService();

        return this;
    }

    /**
     * Default plugin configuration
     */
    private void function $setDefaultSettings() {
        local.appKey = application.wo.$appKey();

        if (!structKeyExists(application[local.appKey], "seo_defaultTitle")) {
            application.wo.set(seo_defaultTitle = application.name);
        }
        if (!structKeyExists(application[local.appKey], "seo_defaultDescription")) {
            application.wo.set(seo_defaultDescription = "");
        }
        if (!structKeyExists(application[local.appKey], "seo_defaultKeywords")) {
            application.wo.set(seo_defaultKeywords = "");
        }
        if (!structKeyExists(application[local.appKey], "seo_defaultImage")) {
            application.wo.set(seo_defaultImage = "");
        }
        if (!structKeyExists(application[local.appKey], "seo_stripQueryString")) {
            application.wo.set(seo_stripQueryString = true);
        }
        if (!structKeyExists(application[local.appKey], "seo_showDebugPanel")) {
            application.wo.set(seo_showDebugPanel = true);
        }
        if (!structKeyExists(application[local.appKey], "seo_dbTablePages")) {
            application.wo.set(seo_dbTablePages = "seo_pages");
        }
        if (!structKeyExists(application[local.appKey], "seo_dbRouteColumn")) {
            application.wo.set(seo_dbRouteColumn = "route_name");
        }
        if (!structKeyExists(application[local.appKey], "seo_dbEntityColumn")) {
            application.wo.set(seo_dbEntityColumn = "entity_id");
        }
        if (!structKeyExists(application[local.appKey], "seo_dbTableMeta")) {
            application.wo.set(seo_dbTableMeta = "seo_meta");
        }
        if (!structKeyExists(application[local.appKey], "seo_dbPageIdColumn")) {
            application.wo.set(seo_dbPageIdColumn = "seo_page_id");
        }
        if (!structKeyExists(application[local.appKey], "seo_dbKeyColumn")) {
            application.wo.set(seo_dbKeyColumn = "meta_key");
        }
        if (!structKeyExists(application[local.appKey], "seo_dbValueColumn")) {
            application.wo.set(seo_dbValueColumn = "meta_value");
        }

    }

    /**
     * Load SEO service singleton
     */
    private void function $loadService() {
        local.appKey = application.wo.$appKey();

        application[local.appKey].seoService = createObject(
            "component",
            "vendor.wheels-seo-suite.lib.SeoSuiteService"
        ).init(
            defaultTitle       = application.wo.get("seo_defaultTitle"),
            defaultDescription = application.wo.get("seo_defaultDescription"),
            defaultKeywords    = application.wo.get("seo_defaultKeywords"),
            defaultImage       = application.wo.get("seo_defaultImage"),
            stripQueryString   = application.wo.get("seo_stripQueryString")
        );
    }

    /* ==========================================================
        PUBLIC API – META DATA
       ========================================================== */

    public void function whlsSeoSet(required any key, any value = "") {
        application[application.wo.$appKey()].seoService.$whlsSeoSet(arguments.key, arguments.value);
    }

    public any function whlsSeoGet(required string key, any defaultValue = "") {
        return application[application.wo.$appKey()].seoService.$whlsSeoGet(arguments.key, arguments.defaultValue);
    }

    /* ==========================================================
        PUBLIC API – RENDER TAGS
       ========================================================== */

    public string function whlsSeoMetaTags() {
        return application[application.wo.$appKey()].seoService.$renderMeta();
    }

    public string function whlsSeoOpenGraphTags() {
        return application[application.wo.$appKey()].seoService.$renderOpenGraph();
    }

    public string function whlsSeoCanonicalTag() {
        return application[application.wo.$appKey()].seoService.$renderCanonical();
    }

    public string function whlsSeoCustomTags() {
        return application[application.wo.$appKey()].seoService.$renderCustomMeta();
    }


    /* ==========================================================
        SITEMAP API
       ========================================================== */

    public void function whlsSeoAddSitemapUrl(
        required string url,
        string lastmod = "",
        string changefreq = "",
        numeric priority = ""
    ) {
        application[application.wo.$appKey()].seoService.$addSitemapUrl(
            url        = arguments.url,
            lastmod    = arguments.lastmod,
            changefreq = arguments.changefreq,
            priority   = arguments.priority
        );
    }

    public string function whlsSeoSitemap() {
        return application[application.wo.$appKey()].seoService.$renderSitemap();
    }

    /* ==========================================================
        ROBOTS.TXT
       ========================================================== */

    public string function whlsSeoRobots() {
        return application[application.wo.$appKey()].seoService.$renderRobots();
    }

    /* ==========================================================
        DEBUG PANEL
       ========================================================== */

    public void function whlsSeoDebugPanel() {
        // ignoring wheels internal pages  
        local.path = lcase( cgi.path_info ?: "" );

        if ( left(local.path, 8) == "/wheels/" ) {
            return;
        }

        application.wo.$includeAndOutput(
            template = "/vendor/wheels-seo-suite/views/seoDebugPanel.cfm"
        );
    }

    /* ==========================================================
        SEO META LOADER
       ========================================================== */

    public void function whlsSeoLoadFromDatabase(
        required string route,
        numeric entityId = 0
    ) {
        application[application.wo.$appKey()].seoService.$loadFromDatabase(
            route    = arguments.route,
            entityId = arguments.entityId
        );
    }

    public void function whlsSeoAdminSave() {
        local.service = application[application.wo.$appKey()].seoService;

        local.url = trim(form.url ?: "");
        if (!len(local.url)) {
            location(url="/", addToken=false);
        }

        // Build custom meta struct from parallel arrays
        local.customMeta = {};
        if (
            structKeyExists(form, "custom_meta_keys") && 
            isArray(form.custom_meta_keys) && 
            structKeyExists(form, "custom_meta_values") && 
            isArray(form.custom_meta_values)
        ) {

            local.keys   = form.custom_meta_keys;
            local.values = form.custom_meta_values;
            local.len = max(arrayLen(local.keys), arrayLen(local.values));

            for (local.i = 1; local.i <= local.len; local.i++) {
                local.key   = trim(local.i <= arrayLen(local.keys) ? local.keys[local.i] : "");
                local.value = trim(local.i <= arrayLen(local.values) ? local.values[local.i] : "");

                if (len(local.key)) {
                    local.customMeta[local.key] = local.value;
                }
            }
        }

        // Handle keywords
        local.keywordString = "";
        if (structKeyExists(form, "keywords")) {
            if (isArray(form.keywords)) {
                local.cleaned = [];
                for (local.kw in form.keywords) {
                    if (len(trim(local.kw))) arrayAppend(local.cleaned, trim(local.kw));
                }
                local.keywordString = arrayToList(local.cleaned, ", ");
            } else {
                local.keywordString = trim(form.keywords);
            }
        }

        // Save everything
        local.service.$savePageMeta(
            url         = local.url,
            title       = trim(form.title ?: ""),
            description = trim(form.description ?: ""),
            keywords    = local.keywordString,
            image       = trim(form.image ?: ""),
            canonical   = trim(form.canonical ?: ""),
            meta        = local.customMeta
        );

        location(url = local.url, addToken = false);
    }

}