كتابة ملحق xbar لـ Plausible.io

كتابة ملحق xbar في Javascript

كمشروع عطلة نهاية الأسبوع ، أردت كتابة مكون إضافي بسيط لـ xbar ، وهو تطبيق عثرت عليه مؤخرًا. xbar نفسه مكتوب بلغة البرمجة "Go" ويستخدم "Wails" كخدمة أساسية لتمكين المطورين من كتابة إدخالات قائمة مخصصة لشريط القائمة في macOS (نعم ، يقتصر حاليًا على macOS فقط).

الشيء الجميل في xbar هو أنه يدعم مجموعة متنوعة من لغات البرمجة ، والتي تتضمن أيضًا Javascript. بصفتي مطور ويب ، كنت أرغب في معرفة مدى سهولة كتابة مكون إضافي مخصص يتصل بـ Plausible.io ، خدمة التحليلات الصديقة للخصوصية الخاصة بي. الهدف هو عرض جميع المستخدمين الحاليين الموجودين حاليًا في تطبيق الويب هذا. حتى كتابة هذا التقرير ، لا يزال طلب السحب قيد المراجعة.

الإعداد الأساسي xbar

يمكن ببساطة تنزيل xbar وتثبيته على جهاز Mac الخاص بك. بمجرد بدء تشغيله لأول مرة ، يمكن استخدام شاشة تحتوي على جميع المكونات الإضافية القابلة للتنزيل والمنشورة للحصول على المكون الإضافي الذي تريده.

تقوم عملية التثبيت ببساطة بنسخ شفرة مصدر المكون الإضافي (ملف واحد لكل مكون إضافي) في مجلد خاص ، حيث يقرأ xbar جميع المكونات الإضافية المثبتة حاليًا. لبدء كتابة المكون الإضافي الخاص بك ، ما عليك سوى إنشاء ملف في الدليل والبدء في القرصنة. مرتب!

اصطلاح اسم ملف xbar

يتكون اسم الملف من ثلاثة أجزاء ، مفصولة بنقاط.

• اسم المكون الإضافي الفريد الخاص بك
• الفترة الزمنية التي يتم فيها تنفيذ التعليمات البرمجية الخاصة بك ، على غرار وظيفة CRON
• لاحقة الملف الشائعة

plausible.1m.js

ترميز البرنامج المساعد xbar في JS

أنت الآن جاهز لبدء البرمجة! قم أولاً بتضمين توجيه shebang المطلوب لإخبار xbar بمكان وجود مثيل العقدة.

#!/usr/bin/env /usr/local/bin/node

الجزء التالي هو ثم إضافة بعض البيانات الوصفية. بالطبع ، بالنسبة للتنمية المحلية ، يمكن حذف هذا ، ولكن هذا ما أستخدمه للمكوِّن الإضافي "معقول".

// Metadata allows your plugin to show up in the app, and website.
//
//  <xbar.title>Plausible Tracker</xbar.title>
//  <xbar.version>v1.0</xbar.version>
//  <xbar.author>Tom Schönmann</xbar.author>
//  <xbar.author.github>flaming-codes</xbar.author.github>
//  <xbar.desc>See who's on your site at-a-glance.</xbar.desc>
//  <xbar.dependencies>node</xbar.dependencies>
//  <xbar.abouturl>https://flaming.codes</xbar.abouturl>
//  <xbar.image>https://raw.githubusercontent.com/flaming-codes/xbar-plausible-stats/main/plausible-icon-36-36-144.png</xbar.image>

وهذا كل ما هو مطلوب لتشغيل المكون الإضافي الخاص بك. الآن لديك لوحة قماشية حيث يمكنك الترميز بجافا سكريبت خالص ، يتم تنفيذه بواسطة مثيل Node.js للمستخدم. هذا يعني أنه يمكننا الوصول إلى جميع حزم Node الأساسية ، مثل "https". بالنسبة لحالة الاستخدام الخاصة بي ، هذا هو كل ما أحتاجه ، حيث أن تتبع المستخدمين يتطلب ببساطة إحضارًا من Plausible.io-API.

تُظهر الأجزاء التالية من التعليمات البرمجية الجزء الأكثر صلة الذي أعتقد أنه يستحق الحديث عنه. الكود الكامل متاح في المستودع العام ذي الصلة ، رابط في الملحق في نهاية هذه الصفحة.

// Here you see how to make network
// requests with 'https'-only.
// This is a native node-lib that
// works w/ data streams, as you'll see.

const https = require("https");

// Those have to edited by the
// user directly in the file,
// after it has been downloaded
// (aka installed)!
const SITE_ID = "";
const API_KEY = "";

// ... other code ...

async function fetcher() {
  return new Promise((resolve, reject) => {
    let body = "";
    const request = {
      host: "plausible.io",
      path: `/api/v1/stats/realtime/visitors?site_id=${SITE_ID}`,
      method: "GET",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
      },
    };

    try {
      const req = https.get(request, (res) => {
        res.on("data", (data) => {
          body += data;
        });
        res.on("end", () => {
          resolve(JSON.parse(body));
        });
      });

      req.on("error", (error) => {
        console.error(error);
      });

      req.end();
    } catch (error) {
      reject(error);
    }
  });
}

// I've implemented an array of tuples
// that hold an icon + count threshold
// when to active it.

// The first entry doesn't render a 
// string (which can be direclty used),
// but rather a mapping that results in
// the following code:
//
// `image="..." font=Menlo color=white`
//
// This is a special syntax that tells
// xbar to render a base64 image w/
// a custom font and color.
//
// 'plausibleIconWhite' is just the string
// for the base64-image.
const stepIcons = [
  [0, `${plausibleIconWhite} Menlo white`, "image font color"],
  [5, "💫"],
  [10, "⭐️"],
  [50, "🌟"],
  [100, "⚡️"],
  [500, "💥"],
];

// Actually rendering stuff in xbar
// is super simple - just output it
// with console.log(...).
//
// As you'll see, '---' define 
// separator. The first log-call
// gets rendered as acutal menu item.

const linksMenu = [
  "---",
  `🔮 Open dashboard | href=https://plausible.io/${SITE_ID}`,
  `🔥 Made by flaming.codes | href=https://flaming.codes`,
];

function renderError(props) {
  const { error } = props;
  const output = [
    "❔",
    "---",
    "No data accessible",
    "Please check your user data",
    ...linksMenu,
  ];

  console.log(output.join("\n"));
}

// Finally, I defined a single function
// where everything starts. This function
// just gets called to kick everyting off.
// Plain JS, it's that simple.

async function render() {
  const { data, error } = await fetcher()
    .then((data) => ({ data }))
    .catch((error) => ({ error }));

  if (data >= 0) return renderData({ data });
  if (error) return renderError({ error });
}

render();

الترميز لـ xbar سهل

استغرقت العملية برمتها بضع ساعات لإكمالها ، وتحقق معظمها من واجهة برمجة التطبيقات من xbar بالإضافة إلى التلاعب بتكوينات مختلفة للتصميم. الكل في الكل ، كتابة مكون إضافي بسيط مثل هذا ليس في الحقيقة الكثير من الجهد الذي هو متعة حقيقية للقيام به. إذا كان لديك بعض ساعات الفراغ ، فيجب أن تجربها أيضًا!

أعتقد أن أكثر ما يتحدث عن xbar هو فرصة البرمجة النصية التي يتيحها هذا التطوير المرن والسريع. يمكنك كتابة متتبعات مخصصة للإعدادات السحابية أو خدمات التحليلات ، بحيث تظهر جميع المقاييس في لمحة في شريط القائمة في macOS. أحبها!