تطوير إضافات Discourse - الجزء 5 - إضافة واجهة إدارية

[Discourse]

الدورة التدريبية السابقة: Developing Discourse Plugins - Part 4 - Setup git

---

في بعض الأحيان، لا تكون إعدادات الموقع كافية كواجهة إدارية لعمل إضافتك بالطريقة التي تريدها. على سبيل المثال، إذا قمت بتثبيت إضافة discourse-akismet، فقد لاحظت أنها تضيف عنصر تنقل إلى قسم الإضافات في لوحة تحكم Discourse الخاص بك:

في هذه الدورة التدريبية، سنوضح لك كيفية إضافة واجهة إدارية لإضافتك. سأطلق على إضافتي اسم purple-tentacle، تكريمًا لـ أحد ألعاب الحاسوب المفضلة لدي. بجدية، أنا أحب ذلك اللعبة حقًا!

إعداد مسار الإدارة (Admin Route)

لنبدأ بإضافة ملف plugin.rb كما فعلنا في الأجزاء السابقة من الدورة التدريبية.

plugin.rb

# name: purple-tentacle
# about: A sample plugin showing how to add a plugin route
# version: 0.1
# authors: Robin Ward
# url: https://github.com/discourse/purple-tentacle

add_admin_route 'purple_tentacle.title', 'purple-tentacle'

Discourse::Application.routes.append do
  get '/admin/plugins/purple-tentacle' => 'admin/plugins#index', constraints: StaffConstraint.new
end

تخبر سطر add_admin_route نظام Discourse أن هذه الإضافة ستحتاج إلى رابط في صفحة /admin/plugins. سيكون عنوانه purple_tentacle.title من ملف ترجمات i18n الخاص بنا، وسيرتبط بمسار purple-tentacle.

تقوم الأسطر التالية بإعداد تعيين المسارات على جانب الخادم (server side) لإضافتنا. إحدى الافتراضات التي يقوم بها Discourse هي أن كل مسار تقريبًا في الواجهة الأمامية له مسار على جانب الخادم يوفر البيانات. في مثال الإضافة هذا، لا نحتاج فعليًا إلى أي بيانات من الخلفية (back end)، لكننا نحتاج إلى إخبار Discourse بتقديم شيء ما في حال قام المستخدم بزيارة /admin/plugins/purple-tentacle مباشرة. هذا السطر يخبره فقط: ‘مرحبًا، إذا قام المستخدم بزيارة هذا الرابط مباشرة على جانب الخادم، قم بتقديم محتوى الإضافات الافتراضي!’

(إذا كان هذا مربكًا، فلا تقلق كثيرًا، سنعود إليه في دورة تدريبية مستقبلية عندما نتعامل مع الإجراءات على جانب الخادم.)

الآن، سنضيف قالبًا (template) سيُعرض عندما يزور المستخدم المسار /admin/plugins/purple-tentacle. سيكون مجرد زر يعرض صورة متحركة (GIF) لحبرقة بنفسجية عندما ينقر المستخدم على الزر:

assets/javascripts/discourse/templates/admin/plugins-purple-tentacle.gjs

import DButton from "discourse/components/d-button";

<template>
  {{#if @controller.tentacleVisible}}
    <div class="tentacle">
      <img src="https://eviltrout.com/images/tentacle.gif" />
    </div>
  {{/if}}

  <div class="buttons">
    <DButton
      @label="purple_tentacle.show"
      @action={{@controller.showTentacle}}
      @icon="eye"
      @id="show-tentacle"
    />
  </div>
</template>

إذا كنت قد تعلمت أساسيات handlebars، فيجب أن يكون فهم القالب بسيطًا إلى حد ما. <DButton /> هو مكوّن (component) في Discourse نستخدمه لعرض زر مع تسمية وأيقونة.

لربط قالبنا الجديد، نحتاج إلى إنشاء خريطة مسارات (route map):

assets/javascripts/discourse/purple-tentacle-route-map.js

export default {
  resource: "admin.adminPlugins",
  path: "/plugins",
  map() {
    this.route("purple-tentacle");
  },
};

خريطة المسارات هي شيء أضفناه إلى discourse للسماح للإضافات بإضافة مسارات إلى تطبيق ember. الصياغة داخل map() تشبه جدًا موجّه Ember. في هذه الحالة، خريطة المسارات لدينا بسيطة جدًا، فهي تعلن عن مسار واحد فقط يُدعى purple-tentacle تحت /admin/plugins.

أخيرًا، لنضيف نصوص الترجمة الخاصة بنا:

config/locales/client.en.yml

en:
  js:
    purple_tentacle:
      title: "Purple Tentacle"
      show: "Show Purple Tentacle"

إذا أعدت تشغيل خادم التطوير (development server)، فيجب أن تتمكن من زيارة /admin/plugins وسترى رابطنا! إذا نقرت عليه، فسترى الزر لعرض حبرقتنا البنفسجية:

للأسف، عند النقر على الزر، لا يحدث شيء

إذا نظرت إلى وحدة تحكم المطور (developer console)، يجب أن ترى خطأً يقدم تلميحًا عن السبب:

Uncaught Error: Nothing handled the action 'showTentacle'`

آه نعم، السبب هو أننا نعتمد في قالبنا على بضع أشياء:

1. أن showTentacle سيتم استدعاؤها على المتحكم (controller) عندما ينقر المستخدم على الزر.
2. يجب أن يحدد showTentacle الخاصية tentacleVisible إلى true حتى تظهر الصورة.

إذا لم تكن قد قمت بقراءة أدلة Ember حول المتحكمات (Controllers) بعد، فهذه فرصة جيدة للقيام بذلك، لأننا سننفذ متحكمًا (controller) لقالب purple-tentacle الخاص بنا للتعامل مع هذه المنطق.

أنشئ الملف التالي:

assets/javascripts/discourse/controllers/admin-plugins-purple-tentacle.js

import Controller from "@ember/controller";
import { action } from "@ember/object";
import { tracked } from "@glimmer/tracking";

export default class AdminPluginsPurpleTentacleController extends Controller {
  @tracked tentacleVisible = false;

  @action
  showTentacle() {
    this.tentacleVisible = true;
  }
}

والآن عند تحديث صفحتنا، يعرض النقر على الزر شخصيتنا المتحركة!

سأترك الأمر كتمرين إضافي للقارئ لإضافة زر يخفي الحبرقة عند النقر عليه

إذا كنت تواجه مشكلة في جعل نسختك من هذه الإضافة تعمل، فقد قمت برفعها إلى github.

---

المزيد في السلسلة

الجزء 1: أساسيات الإضافات
الجزء 2: فتحات الإضافات (Plugin Outlets)
الجزء 3: إعدادات الموقع
الجزء 4: إعداد git
الجزء 5: هذا الموضوع
الجزء 6: اختبارات القبول
الجزء 7: نشر إضافتك

---

هذا المستند مُدار بإصدارات - اقترح تعديلات على github.

[snjqi188 (Sarah Ni)]

Hm, doesn’t seem to work on my local side… did anyone face the same problem?

[eviltrout (Robin Ward)]

What’s the problem? If you install the purple tentacle plugin does it not work?

[snjqi188 (Sarah Ni)]

edit: issue resolved. it works!

@eviltrout nope, it doesn’t work. I believe @ladydanger is also facing the same problem.
nothing appears in the site settings or plugins tabs.
I tried both following the instructions as well as symlink-ing your plugin (dl-ed from github).
I then tried to create server.en.yml, client.en.yml, settings.yml following the format of other plugins, but the image wouldn’t render anyhow.

probably something wrong with the ..route-map.js.es6 or config files.

interestingly enough, akismet’s plugin does work for me.

[sam (Sam Saffron)]

One issue that keeps on biting me is that I still need to do

rm -fr /tmp/cache

To kick away some odd caching we have in some cases.

[snjqi188 (Sarah Ni)]

@eviltrout

oh now this is an interesting finding - apparently our ad plugins were interfering with the purple-tentacle plugin. or the other way round. it works now, after having removed the ad plugin files.

• it now works with our ad plugins! possibly some minor bug yesterday. all is good!

@sam, what’s the difference between rm -rf tmp and rm -fr /tmp/cache

[sam (Sam Saffron)]

I usually only delete the cache directory, no need to nuke the entire tmp directory.

[Mittineague]

@snjqi188

possibly some minor bug yesterday

Are you sure it was a plugin conflict?

I copied it into my localhost plugin folder and started up the VM without removing the temp folder and got the same results as you posted.

I was puzzled to see the route in object dot notation but ignored that.

I then started up the VM and did remove the temp folder and all was OK

[riking (Kane York)]

Actually, sometimes you need just cache, and sometimes you need the whole tmp directory.

Maybe we could have an initializer that checks the timestamps on the plugin folders and nukes tmp if they were updated (dev only).

[eviltrout (Robin Ward)]

@snjqi188

it now works with our ad plugins! possibly some minor bug yesterday. all is good!

One thing I really should have warned you about is I started raising errors on ember deprecations. We are really working towards upgrading our version of Ember soon and I wanted to make sure developers caught them. It’s possible your plugin has a deprecation or two and is now raising an error with the latest version of Discourse.

If you can’t figure out how to fix the deprecation, it’s okay to temporarily disable it in the Discourse working directory you are using. Try removing these two lines.

[webeindustry]

No clue what I’m doing wrong here, but it shows up like this:

It must be the /config/locales/en.yml not loading, but why?

I put this file structure in the root of the plugin directory. Verified it’s there, nuked the tmp, restart rails.

en:
  js:
    purple_tentacle:
      title: "Purple Tentacle"
      show: "Show Purple Tentacle"

[Mittineague]

@webeindustry

but why?

I was a bit surprised to see the file named “en.yml” but figured either eviltrout knew something I didn’t (which I’m sure he does … anyway) or that maybe something had changed the way things worked.

I’m guessing that what Robin meant was client,en.yml because that works for me.

@webeindustry

in the root of the plugin director

the file goes in the plugins config/locales folder

[webeindustry]

Thanks I’ll try that after I get my dev environment setup on the xeon, went through hell getting ubuntu 16.04 to work right with my hardware. Turned out it wasn’t the server mobo, but the new nvidia card.

Yea I meant I put all the directories listed hierarchically starting with the plugins folder. Was wondering if for some reason that last file went elsewhere.

[webeindustry]

Same thing.

I tried naming the file client,en.yml, client.en.yml, and creating a client folder placing en.yml inside it.

Same result

[Mittineague]

Did you stop vagrant, clear the cache
$> rm -rf tmp
and restart vagrant?

[webeindustry]

I’m not using vagrant, yes I nuked tmp, restart rails.

This is a bit too annoying, and not a big deal. I’m going to move forward, but thanks for the efforts.

[Mittineague]

I have a feeling you may have the folder structure wrong, or maybe the naming. Mine is like

/discourse
../plugins
..../{yourpluginname}
......plugin.rb
....../config
........settings.yml
......../locales
..........client.en.yml
..........server.en.yml
....../assets
......../javascripts
........../discourse
............{yourpluginname}-route-map.js.es6
............/controllers
..............admin-plugins-{yourpluginname}.js.es6
............/templates
............../admin
................plugins-{yourpluginname}.hbs

[webeindustry]

That’s the file structure I have.

I don’t see a point in getting stuck on this, already hacked together a couple of rails sites and trying to absorb as much as possible.

Just going to leave this as some simple error on my part that I’ll come look back at later on and probably realize right away what it was.

Thanks, thou

[eviltrout (Robin Ward)]

Another mistake of mine! I’ve updated the OP, thanks.

[Einsteino]

Is there any way I can change a global plugin setting, say, a siteSetting, from here?
I need admins to be able to use this interface to add data into a global array.