wunderbar

Wunderbar: تطبيقات HTML5 سهلة

يجعل Wunderbar من السهل إنتاج تطبيقات HTML5 صالحة وXHTML جيدة التصميم وUnicode (utf-8) وتطبيقات ذات مسافة بادئة متسقة وقابلة للقراءة.

Wunderbar مستوحى من Jim Weirich's Builder، ويوفر معرف العنصر وبناء جملة معرف الفئة ويعتمد على التنفيذ من Markaby.

دعم Wunderbar's JSON مستوحى من jbuilder الخاص بـ David Heinemeier Hansson.

البرنامج التعليمي قيد التطوير.

يتم توفير وظائف إضافية عن طريق الملحقات.

ملخص

فرضية Wunderbar هي أن مخرجات الأنواع المختلفة يتم تشكيلها عادةً عن طريق إلحاق إما سلسلة من أزواج المفاتيح/القيمة أو القيم البسيطة، وينبغي تحسين هذه العمليات من أجلها. يتم إلحاق زوج المفتاح/القيمة عبر:

 _key value

... ويتم إلحاق قيمة بسيطة على النحو التالي:

 _ value

بالنسبة لـ HTML، يتم استخدام المفتاح/القيمة لعقد العناصر، ويتم استخدام القيم البسيطة لعقد النص. بالنسبة لـ JSON، يتم استخدام المفتاح/القيمة للتجزئة ويتم استخدام القيم البسيطة للمصفوفات. بالنسبة للنص، يتم إخراج القيم البسيطة عبر عمليات البيع، ولا يتم استخدام أزواج المفاتيح/القيمة.

يتم تنفيذ التعشيش باستخدام الكتل.

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

قد تؤدي طريقة الشرطة السفلية عند تمرير وسائط متعددة أو مجموعة من الوسائط وكتلة وظائف شائعة أخرى، اعتمادًا على أنواع الوسائط التي تم تمريرها.

قد تؤدي علامة الاستفهام وعلامة التعجب ولاحقات الشرطة السفلية لاسم الطريقة إلى تعديل النتائج.

البدء السريع (HTML)

عنصر بسيط:

 _br

العناصر المتداخلة:

 _div do
  _hr
end

العنصر مع النص:

 _h1 "My weblog"

العنصر ذو السمات:

 _img src: '/img/logo.jpg', alt: 'site logo'

العنصر الذي يحتوي على كل من النص والسمات:

 _a 'search', href: 'http://google.com'

العنصر ذو السمات المنطقية:

 _input 'Cheese', type: 'checkbox', name: 'cheese', checked: true

عنصر ذو سمات منطقية (نموذج بديل):

 _input 'Cheese', :checked, type: 'checkbox', name: 'cheese'

العنصر ذو السمات الاختيارية (المحذوفة):

 _tr class: nil

النص (يتم هروب أحرف الترميز):

 _ "<3"

النص (قد يحتوي على علامات):

 _{"<em>hello</em>!!!"}

استيراد HTML/XML:

 _[Nokogiri::XML "<em>hello</em>"]

محتوى مختلط (مسافة تلقائية):

 _p do
  _ 'It is a'
  _em 'very'
  _ 'nice day.'
end

محتوى مختلط (التحكم في المساحة):

 _p! do
  _ 'Source is on '
  _a 'github', href: 'https://github.com/'
  _ '.'
end

أدخل أسطرًا فارغة بين الصفوف في HTML المنتج:

 _tbody do
  _tr_ do
    _td 1
  end
  _tr_ do
    _td 2
  end
  _tr_ do
    _td 3
  end
end

التقاط الاستثناءات:

 _body? do
  raise NotImplementedError.new('page')
end

اختصار سمة الفئة (أي ما يعادل الفئة = "الجبهة"):

 _div.front do
end

اختصار سمات المعرف (أي ما يعادل id = "بحث"):

 _div.search! do
end

يمكن تعريف القوائم/الصفوف الكاملة باستخدام المصفوفات:

 _ul %w(apple orange pear)
_ol %w(apple orange pear)
_table do
  _tr %w(apple orange pear)
end

يمكن إجراء التكرار التعسفي على Enumerables:

 _dl.colors red: '#F00', green: '#0F0', blue: '#00F' do |color, hex|
  _dt color.to_s
  _dd hex
end

الواجهة الأساسية

ينتج البرنامج الرئيسي النموذجي واحدًا أو أكثر من مخرجات HTML أو JSON أو النص العادي. ويتم تحقيق ذلك من خلال توفير واحد أو أكثر مما يلي:

 _html do
  code
end

_xhtml do
  code
end

_json do
  code
end

_text do
  code
end

_websocket do
  code
end

يمكن وضع رمز روبي التعسفي في كل منها. يتم توفير معلمات النموذج كمتغيرات الحالة (على سبيل المثال، @name ). يمكن الوصول إلى قيم البيئة المضيفة (CGI، Rack، Sinatra) كطرق للكائن _ : على سبيل المثال _.headers (CGI)، _.set_cookie (Rack)، _.redirect (Sinatra).

لإلحاق المخرجات المنتجة، استخدم الطرق _ الموضحة أدناه. تطبيقات الأمثلة موجودة في البرنامج التعليمي.

الأساليب المقدمة إلى Wunderbar.html

سيؤدي استدعاء الأساليب التي تبدأ بحرف Unicode المنخفض ("_") إلى إنشاء علامة HTML. كما هو الحال مع المنشئ، الذي تعتمد عليه هذه المكتبة، يمكن أن تحتوي هذه العلامات على محتوى وسمات نصية. يمكن أيضًا أن تكون العلامات متداخلة. يمكن خلط المنطق بحرية.

يعرف Wunderbar علامات HTML التي يجب إغلاقها بشكل صريح بعلامات نهاية منفصلة (مثال: textarea )، والتي لا ينبغي أبدًا إغلاقها بعلامات نهاية منفصلة (مثال: br ). كما أنه يعتني باقتباس HTML والهروب من الوسائط والنص.

سوف تقوم اللواحق بعد اسم العلامة بتعديل المعالجة.

• ! : يقوم بإيقاف كافة عمليات المعالجة الخاصة، بما في ذلك المسافة البادئة
• ? : يضيف تعليمات برمجية لإنقاذ الاستثناءات وإنتاج عمليات التتبع
• _ : يضيف أسطرًا فارغة إضافية بين هذه العلامة والأشقاء

تخدم الطريقة " _ " عددًا من الأغراض. يؤدي استدعاؤها باستخدام وسيطة واحدة إلى إدراج علامة، مع احترام المسافة البادئة. يتم إدراج العلامات دون النظر إلى المسافة البادئة باستخدام " _ << text ". تم تحديد عدد من طرق الراحة الأخرى:

• _ : أدخل نصًا بمسافة بادئة تطابق الإخراج الحالي
• _! : أدخل النص بدون مسافة بادئة
• _.post? - هل تم استدعاء هذا عبر HTTP POST؟
• _.system - يستدعي أمر shell ويلتقط stdin وstdout وstderr
• _.submit -- يقوم بتشغيل الأمر (أو الحظر) كعملية شيطانية
• _.xhtml? - الإخراج بتنسيق XHTML؟

يأخذ الأسلوب _.system تجزئة اختيارية كمعلمة أخيرة. يمكن استخدام هذا لتوفير إعدادات طريقة Process.spawn الأساسية. على سبيل المثال: ._system('pwd',{ system_opts: { chdir: dir } , system_env: { 'FOO' => 'BAR' } }) لاحظ أنه يجب توفير أسماء متغيرات البيئة كسلاسل، وليس رموز. تتضمن الخيارات الإضافية التي يمكن استخدامها مع _.system ما يلي:

• :tag - علامة HTML التي سيتم استخدامها للإدخال/الإخراج؛ الإعدادات الافتراضية إلى pre
• :bundlelines - ما إذا كان سيتم معالجة جميع الأسطر لنوع إخراج معين (stderr، stdout، إلخ) كجزء من علامة واحدة. إذا لم يتم تحديدها، فستكون القيمة الافتراضية true للعلامات pre false بخلاف ذلك. إذا كان false ، تتم معالجة كل سطر من الإخراج بشكل منفصل.

يمكن الوصول إلى جميع الأساليب التي حددها المنشئ (عادةً ما تنتهي بعلامة تعجب) وجميع أساليب وحدة Wunderbar بهذه الطريقة. أمثلة:

• _.tag! :foo : أدخل العناصر حيث يمكن أن يكون الاسم ديناميكيًا
• _.comment! "text" : أضف تعليقًا
• _.error 'Log message' : اكتب رسالة إلى سجل الخادم

يتم تحويل الشرطات السفلية في أسماء العناصر والسمات إلى شرطات. لتعطيل هذا السلوك، قم بالتعبير عن أسماء السمات كسلاسل واستخدم العلامة _.tag! طريقة أسماء العناصر

يختلف XHTML عن HTML في الهروب من النمط المضمن وعناصر البرنامج النصي. سيعود XHTML أيضًا إلى إخراج HTML ما لم يشير وكيل المستخدم إلى أنه يدعم XHTML عبر رأس قبول HTTP.

بالإضافة إلى المعالجة الافتراضية للعناصر والنصوص والسمات، يحدد Wunderdar معالجة إضافية لما يلي:

• _head : أدخل مجموعة محارف التعريف utf-8
• _svg : أدخل مساحة اسم svg
• _math : أدخل مساحة اسم الرياضيات
• _coffeescript : تحويل Coffeescript إلى JS وإدراج علامة البرنامج النصي

لاحظ أن إضافة علامة تعجب إلى نهاية اسم العلامة يؤدي إلى تعطيل هذا السلوك.

إذا كانت إحدى السمات التي تم تمريرها في إعلان _html هي :_width ، فستتم محاولة لإعادة تدفق النص حتى لا يتجاوز عرض السطر هذا. لن يتم ذلك إذا كان سيؤثر على ما يتم عرضه بالفعل.

إذا لم يكن أي من العناصر الفرعية لعنصر html head أو body ، فسيتم إنشاء هذه العلامات لك، وسيتم نقل العناصر الفرعية ذات الصلة إلى القسم المناسب. إذا كان النص يحتوي على عنصر h1 ، head لا يحتوي على title ، فسيتم إنشاء عنصر عنوان بناءً على النص المقدم إلى عنصر h1 الأول.

الطرق المقدمة إلى Wunderbar.json

العمليات الشائعة هي إرجاع التجزئة أو مجموعة من القيم. التجزئة هي سلسلة من أزواج الاسم/القيمة، والمصفوفات هي سلسلة من القيم.

 Wunderbar . json do
  _content format_content ( @message . content )
  _ @message , :created_at , :updated_at 

  _author do
    _name @message . creator . name . familiar
    _email_address @message . creator . email_address_with_name
    _url url_for ( @message . creator , format : :json )
  end

  if current_user . admin?
    _visitors calculate_visitors ( @message )
  end

  _comments @message . comments , :content , :created_at
  
  _attachments @message . attachments do | attachment |
    _filename attachment . filename
    _url url_for ( attachment )
  end
end

سيؤدي استدعاء الأساليب التي تبدأ بحرف Unicode المنخفض ("_") إلى إضافة زوج مفتاح/قيمة إلى هذا التجزئة. يمكن أيضًا أن تكون التجزئة متداخلة. يمكن خلط المنطق بحرية.

تخدم الطريقة " _ " عددًا من الأغراض.

• سيؤدي استدعاؤها باستخدام وسائط متعددة إلى معاملة الوسيطة الأولى على أنها الكائن، والباقي على أنه السمات التي سيتم استخراجها

  • مثال: _ File.stat('foo'), :mtime, :size, :mode

• سيؤدي استدعاؤه باستخدام كائن واحد قابل للتعداد وكتلة إلى إرجاع مصفوفة بناءً على تعيين كل اعتراض من التعداد مقابل الكتلة

  • مثال: _([1,2,3]) {|n| n*n}

• يمكن أيضًا بناء المصفوفات باستخدام الطريقة _ :

    _ 1
    _ 2
  

تقوم الطريقة _ بإرجاع وكيل إلى الكائن الذي يتم إنشاؤه. غالبًا ما يكون هذا مفيدًا عند الاتصال بدون وسائط. أمثلة:

    _.sort!
    _['foo'] = 'bar'

الطرق المقدمة إلى Wunderbar.text

يتم الإلحاق بتدفق الإخراج باستخدام الأسلوب _ ، وهو ما يعادل puts . تقوم الطريقة _ بإرجاع كائن وكيل لتدفق الإخراج، والذي يوفر الوصول إلى أساليب مفيدة أخرى، على سبيل المثال:

    _.print 'foo'
    _.printf "Hello %s!n", 'world'

الطرق المقدمة إلى Wunderbar.websocket

يتطلب دعم WebSocket تثبيت em-websocket .

مقبس الويب هو قناة ثنائية الاتجاه. يمكن استخدام _.send أو _.push لإرسال سلاسل عشوائية. والأكثر شيوعًا، أنه يمكن استخدام جميع طرق مصفوفة JSON الموضحة أعلاه، والفرق المهم هو أن الإدخالات الفردية يتم إرسالها بشكل فردي وعند إنتاجها.

يمكن استخدام _.recv أو _.pop لتلقي سلاسل عشوائية. والأكثر شيوعًا هو استخدام _.subscribe لتسجيل كتلة يتم استخدامها كرد اتصال.

_. سيقوم _.system بتشغيل أمر تعسفي. يتم إرسال سطور الإخراج عبر websocket حيث يتم استلامها كتجزئة مشفرة JSON بقيمتين: type هو واحد من stdin أو stdout أو stderr ؛ line الذي يحتوي على الخط نفسه. إذا كان الأمر عبارة عن مصفوفة، فسيتم تهريب عناصر المصفوفة كوسيطات أمر Shell. يمكن استخدام المصفوفات المتداخلة لإخفاء العناصر من تكرار الأمر إلى stdin. تم حذف القيم الصفرية.

يتم توفير خيارات _websocket كعلامة تجزئة:

• :port سيختار رقم منفذ، مع الافتراضي هو اختيار رقم متاح لك.
• سيؤدي تعيين :sync على false إلى تشغيل خادم WebSocket كعملية خفية. هذا الإعداد الافتراضي هو true عند تشغيله من سطر الأوامر وإلى false عند تشغيله كـ CGI.
• سوف يحد buffer_limit من كمية الإدخالات التي يتم الاحتفاظ بها وإرسالها إلى العملاء الجدد بناءً على الطلبات المفتوحة. الافتراضي هو 1 . ستؤدي القيمة صفر إلى تعطيل التخزين المؤقت. ستؤدي القيمة nil إلى تخزين مؤقت غير محدود. ملاحظة: التخزين المؤقت غير محدود بشكل فعال حتى يتصل العميل الأول.

آمن بشكل افتراضي

سوف يفلت Wunderbar بشكل صحيح من جميع مخرجات HTML وJSON، مما يزيل مشاكل إدخال HTML أو JavaScript. يتضمن ذلك الاستدعاءات إلى _ لإدراج نص مباشرةً. ما لم يكن nokogiri مطلوبًا مسبقًا (راجع التبعيات الاختيارية أدناه)، فإن الاستدعاءات لإدراج العلامات ( _{...} ) ستتجاوز العلامات.

تم توفير الكرات العالمية

• $USER - معرف المستخدم المضيف
• $PASSWORD - كلمة مرور المضيف (في حالة تمرير CGI وHTTP_AUTHORIZATION)
• $HOME - الدليل الرئيسي
• $SERVER - اسم الخادم
• $HOME - الدليل الرئيسي للمستخدم
• $HOST - مضيف الخادم

بالإضافة إلى ذلك، يتم تعيين متغيرات البيئة التالية إذا لم تكن كذلك بالفعل:

• HOME
• HTTP_HOST
• LANG
• REMOTE_USER

وأخيرًا، تم تعيين الترميزات الافتراضية الخارجية والداخلية على UTF-8.

التسجيل

• _.debug : رسائل التصحيح
• _.info : رسائل إعلامية
• _.warn : رسائل التحذير
• _.error : رسائل الخطأ
• _.fatal : رسائل خطأ فادحة
• _.log_level =: ضبط مستوى التسجيل (الافتراضي: :warn )
• _.default_log_level =: قم بتعيين مستوى السجل، ولكن لا تتجاوزه
• _.logger : إرجاع مثيل المسجل

خيارات سطر الأوامر

عند التشغيل من سطر الأوامر، يمكن تحديد أزواج القيمة = اسم CGI. بالإضافة إلى ذلك، يتم دعم الخيارات التالية:

• --get : من المتوقع إخراج HTML (HTTP GET).
• --post : من المتوقع إخراج HTML (HTTP POST).
• --json : من المتوقع إخراج JSON (طلب XML HTTP).
• --html : فرض إخراج HTML
• --prompt أو --offline : المطالبة بأزواج المفاتيح/القيمة باستخدام stdin
• --debug ، --info ، --warn ، --error ، --fatal : تعيين مستوى السجل
• --install= path: قم بإنتاج برنامج نصي مجمع قابل للاستدعاء suexec
• --rescue أو --backtrace يتسبب في قيام البرنامج النصي المجمّع بالتقاط الأخطاء

التبعيات الاختيارية

هناك حاجة إلى الأحجار الكريمة التالية بناءً على الوظائف التي تستخدمها:

• مطلوب em-websocket بواسطة wunderbar/websocket
• kramdown مطلوب بواسطة wunderbar/markdown
• يضيف ruby2js دعمًا للنصوص المكتوبة على شكل كتل
• sourcify مطلوب بواسطة wunderbar/opal

الأحجار الكريمة التالية مطلوبة من خلال الامتدادات التي تحمل الاسم نفسه:

• coderay - تسليط الضوء على بناء الجملة
• opal - روبي إلى مترجم جافا سكريبت
• rack - واجهة خادم الويب
• sinatra - DSL لإنشاء تطبيقات الويب

الأحجار الكريمة التالية، إذا تم تثبيتها، ستنتج مخرجات أنظف وأجمل:

• يقوم nokogiri بتنظيف أجزاء HTML المُدرجة عبر << و _{} .
• يقوم nokogumbo أيضًا بتنظيف أجزاء HTML المُدرجة عبر << و _{} . إذا كانت هذه الجوهرة متاحة، فسيتم تفضيلها على الاستخدام المباشر لـ nokogiri .
• escape من الاقتباس الجميل لأوامر system

الجهود ذات الصلة

• منشئ
• JBuilder
• مركبي
• نوكوجيري::HTML::Builder
• تاجز