stacy

ستايسي

Stacy هو منشئ مواقع الويب الذي يجمع المحتوى من Contentful CMS مع قوالب Handlebars لإنشاء صفحات موقع الويب.

يقوم Stacy بمطابقة أنواع محتوى إدخال Contentful مع قوالب Handlebars في مشروع موقع الويب الخاص بك في علاقة رأس برأس - يوجد قالب لكل نوع إدخال محدد في نموذج المحتوى الخاص بك. هناك نوعان من الإدخالات من وجهة نظر ستايسي: إدخالات الصفحة وإدخالات الوحدة النمطية . يُنتج إدخال الصفحة المدمج مع القالب الخاص بها صفحة موقع ويب واحدة بعنوان URL فريد. يمكن تضمين إدخالات الوحدة النمطية في الصفحات والوحدات النمطية الأخرى باستخدام الحقول المرجعية الخاصة بـ Contentful لإنشاء أجزاء قابلة لإعادة الاستخدام من المحتوى أو ببساطة لتوفير بنية المحتوى والقوالب عن طريق تقسيمها إلى أجزاء أصغر.

ما يجعل Stacy مختلفًا عن العديد من مولدات مواقع الويب الثابتة الحالية هو أنه يدعم النشر التلقائي لموقع الويب إلى مجموعة S3 في Amazon Cloud، حيث يمكن تقديمه على الإنترنت. تنشر Stacy بنية تحتية خاصة في Amazon Cloud والتي يمكن توصيلها بـ Contentful عبر وظيفة Webhooks الخاصة بها. عندما يتم تحديث المحتوى في مساحة Contentful الخاصة بك، يتم إخطار البنية التحتية لموقع الويب الخاص بك التي تم نشرها بواسطة Stacy في Amazon Cloud وتقوم تلقائيًا بإعادة إنشاء وإعادة نشر تلك الصفحات من موقع الويب الخاص بك التي تأثرت بالتحديث فقط. لا يلزم تجديد موقع الويب وإعادة نشره يدويًا.

عند استخدام Stacy، يكون موقع الويب الخاص بك عبارة عن مشروع NPM يتم فحصه عادةً في مستودع git للتحكم في الإصدار. يتضمن المشروع قوالب Handlebars الخاصة بك والمحتوى الثابت (مثل أوراق أنماط CSS والصور المستخدمة في تصميم موقع الويب والخطوط وما إلى ذلك)، بينما يوجد محتوى موقع الويب في مساحة المحتوى. من مشروع موقع الويب، يستخدم مطورو موقع الويب أداة سطر الأوامر Stacy لتطوير الموقع ونشره وإعادة نشره. بمجرد نشر موقع الويب في Amazon Cloud، يعمل مؤلفو المحتوى فقط مع Contentful UI.

راجع إنشاء موقع ويب باستخدام Stacy للحصول على برنامج تعليمي/إرشادات تفصيلية.

ابدء

أولاً، أنت بحاجة إلى مساحة محتوى لمحتوى موقع الويب الخاص بك. وبمجرد الانتهاء من ذلك، يمكنك إنشاء مشروع جديد لموقع الويب الخاص بك.

تأكد من تثبيت الإصدار 10.16.3 أو الأحدث من Node.js مع npm. إذا كنت ستنشر موقع الويب في Amazon Cloud، فستحتاج أيضًا إلى تثبيت AWS CLI.

ابدأ بتثبيت Stacy عالميًا:

 npm install -g stacy

في مساحة المحتوى الخاصة بك، انتقل إلى إعدادات المساحة ← مفاتيح واجهة برمجة التطبيقات وأضف مفتاح واجهة برمجة التطبيقات في الرموز المميزة لتسليم/معاينة المحتوى . لاحظ قيم الرمز المميز للوصول إلى Space ID و Content Delivery API التي ستستخدمها لتوصيل بيئة Stacy الخاصة بك بمساحة Contentful الخاصة بك.

الآن، يمكنك إنشاء المشروع الأولي لموقع الويب الخاص بك:

 stacy new --cf-space <your space ID> --cf-access-token <your access token> mywebsite

سيؤدي هذا إلى إنشاء دليل مشروع جديد يسمى "mywebsite" في الدليل الحالي. تُعرف قيمة "mywebsite" بمعرف الموقع . استخدم قيمة مختلفة تحدد موقع الويب الخاص بك. يجب أن تكون القيمة متوافقة مع عنوان URL (أحرف صغيرة وأرقام وشرطات).

في دليل مشروعك، ضع المحتوى الثابت ضمن /static (يتم نسخ هذا إلى موقع الويب الخاص بك كما هو) ثم ضع قوالب الإدخال الخاصة بك ضمن /templates . يجب أن يتطابق اسم ملف القالب (بدون الامتداد) تمامًا مع نوع محتوى الإدخال المقابل في نموذج المحتوى المحتوى الخاص بك. ضمن /templates ، يمكن تنظيم ملفات القالب في مجلدات فرعية. ومع ذلك، يجب أن تكون أسماء الملفات فريدة عبر جميع المجلدات الفرعية لأنها تُستخدم لمطابقة القوالب بشكل فريد مع أنواع محتوى الإدخال (لا تلعب المجلدات الفرعية في /templates أي دور).

ملاحظة: عادةً ما ينتج عن القالب، مع محتوى الإدخال، HTML. إذا كنت بحاجة إلى إنتاج نوع آخر من المحتوى، فيمكنك إضافة امتداد لاسم القالب. على سبيل المثال، ينتج page.hbs HTML. لإنتاج نص عادي استخدم page.txt.hbs . وهذا يعني أيضًا أن page.hbs و page.html.hbs متماثلان.

يمكنك الآن تشغيل موقع الويب الخاص بك محليًا لأغراض التطوير:

 stacy serve

يمكنك رؤية موقع الويب الخاص بك على http://localhost:8080/ . بعد تحرير أي قالب أو محتوى ثابت أو محتوى في Contentful، ما عليك سوى إعادة تحميل الصفحة.

لإيقاف خادم الويب المحلي Stacy، استخدم Ctrl+C .

قم بتشغيل stacy --help لرؤية الأوامر الأخرى المتاحة.

يمكنك تسجيل محتوى دليل مشروعك في مستودع git مثل GitHub أو Bitbucket.

قوالب

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

< h3 > {{ caption }} </ h3 >

سيؤدي هذا إلى إخراج قيمة حقل caption للإدخال. لاحظ أن معرف الحقل هو المستخدم هنا وليس اسم الحقل.

تضيف Stacy بعض المساعدات الخاصة التي يمكنك استخدامها في القوالب الخاصة بك:

• module <reference field> - قم بتضمين إدخال الوحدة النمطية المشار إليه بواسطة حقل نوع المرجع. على سبيل المثال، بشرط أن يكون لديك حقل يحتوي على paragraphs معرف وهو عبارة عن قائمة مراجع:

   {{ #each paragraphs }} {{{ module this }}} {{ /each }}

• asset <asset field> - قم بتضمين الأصل المشار إليه، مثل الصورة. على سبيل المثال:

   {{ asset picture }}

  حاليًا، يتم دعم أصول الصور فقط، والتي يتم عرض علامة HTML <img> لها.

• assetSrc <asset field> - احصل على عنوان URL للأصل. على سبيل المثال:

  < img src = " {{ assetSrc picture }} " >

• assetTitle <asset field> - احصل على عنوان الأصل. على سبيل المثال:

  < img src = " {{ assetSrc picture }} " alt = " {{ assetTitle picture }} " >

• markdown <long text field> - تقديم حقل نص طويل لتخفيض السعر. على سبيل المثال:

   {{{ markdown description }}}

  لاحظ الأقواس الثلاثية المطلوبة هنا لأن المساعد يقوم بإنشاء HTML الذي لا يلزم الهروب منه.

• richText <rich text field> - عرض حقل النص المنسق. على سبيل المثال:

   {{{ richText content }}}

  كما هو الحال مع markdown ، لاحظ الأقواس الثلاثية.

• json <field> - إخراج تمثيل JSON الداخلي للمحتوى للحقل. على سبيل المثال:

  < pre > {{ json myField }} </ pre >

  قد يكون هذا المساعد مفيدًا لتشخيص المشكلات.

نموذج المحتوى

كما هو مذكور أعلاه، هناك علاقة رأس برأس بين أنواع المحتوى التي تحددها في نموذج المحتوى والقوالب الخاصة بمساحة المحتوى الخاصة بك.

ملاحظة: بالمعنى الدقيق للكلمة، يمكن أن يكون لديك أكثر من قالب واحد لنوع محتوى معين للسماح بإنشاء أنواع مختلفة من الملفات لنفس إدخال المحتوى. على سبيل المثال، بالنسبة module معرف نوع المحتوى، يمكن أن يكون لديك قوالب module.html.hbs و module.xml.hbs . سينتج القالب الأول ملف HTML للإدخال وسينتج القالب الثاني ملف XML.

عندما تقوم بتعريف نوع محتوى، لاحظ معرف واجهة برمجة التطبيقات (المعروف أيضًا باسم معرف نوع المحتوى ). يجب أن يحمل ملف القالب الخاص بنوع المحتوى نفس الاسم (بالإضافة إلى الامتداد).

هناك متطلب واحد لأنواع المحتوى لإدخالات الصفحة (بدلاً من إدخالات الوحدة النمطية): يجب أن يحدد نوع محتوى الصفحة حقلاً ثابتًا مطلوبًا. ستحدد القيمة الموجودة في الحقل اسم الملف الذي تم إنشاؤه عند دمج إدخال المحتوى مع القالب المقابل. على سبيل المثال، إذا كانت القيمة الثابتة لإدخال الصفحة هي "index"، فستكون الصفحة التي تم إنشاؤها هي "/index.html". إذا كان الارتباط الثابت هو "more/terms"، فستكون الصفحة "/more/terms.html". وهكذا.

افتراضيًا، يجب أن يكون معرف الحقل لحقل الارتفاع الثابت هو slug . يمكن تجاوز المعرف في ملف stacy.json الخاص بالمشروع. إلى جانب جعل الحقل الثابت مطلوبًا في تعريف نوع المحتوى، يوصى أيضًا بربط مدقق نمط المطابقة المخصص به لضمان التنسيق المحدد لقيمة الحقل. يمكن أن يكون التعبير العادي للمدقق هو ^w[w-]*(/w[w-]*)*$ .

النشر في أمازون كلاود

عندما تكون مستعدًا لنشر موقع الويب الخاص بك في AWS، تحتاج أولاً إلى إعداد البنية التحتية لـ Stacy ضمن حساب AWS الخاص بك. يجب عليك تنفيذ عدة خطوات قبل أن تتمكن من القيام بذلك:

1. قم بإنشاء مجموعة S3 المستهدفة. هذا هو المكان الذي سيتم فيه نشر موقع الويب الخاص بك ومن حيث سيتم تقديمه (ربما عبر CloudFront). وبدلاً من ذلك، يمكنك استخدام مجموعة موجودة لديك بالفعل (يدعم Stacy أيضًا النشر في مجلد فرعي في المجموعة المستهدفة).

2. إذا لم يكن لديك بعد، فقم بإنشاء حاوية S3 التي ستستخدمها Stacy لتحميل حزمة وظيفة Lambda للناشر. وظيفة الناشر Lambda هي الجزء الذي يستجيب لأحداث النشر وإلغاء النشر للمحتوى ويقوم بتحديث الصفحات والأصول ذات الصلة في مجموعة S3 المستهدفة.

3. بناء حزمة الناشر:

    stacy build-publisher
   

   سيؤدي هذا إلى إنشاء حزمة وظيفة Lambda للناشر في مشروعك ضمن /build/stacy-mywebsite-publisher.zip . قم بتحميل هذا الملف إلى مجموعة وظائف Lambda S3 الخاصة بك.

قام أمر Stacy stacy new بإنشاء قالب CloudFormation لبيئة AWS وحفظه في مشروعك ضمن /misc/cfn-template.json . يمكنك مراجعته وتخصيصه إذا لزم الأمر. بخلاف ذلك، يمكنك المضي قدمًا وإنشاء Stacy Stack لموقعك على الويب ضمن حساب AWS الخاص بك.

بمجرد إنشاء حزمة CloudFormation، تحتاج إلى تعديل سياسة مجموعة S3 المستهدفة للسماح لناشر Stacy بنشر محتوى موقع الويب الذي تم إنشاؤه فيه. يمكن أن تتضمن سياسة الحاوية شيئًا مثل ما يلي:

{
    "Version" : " 2012-10-17 " ,
    "Statement" : [
        {
            "Effect" : " Allow " ,
            "Principal" : {
                "AWS" : " <Stacy publisher role ARN> "
            },
            "Action" : [
                " s3:PutObject " ,
                " s3:DeleteObject "
            ],
            "Resource" : " arn:aws:s3:::<bucket name>/* "
        }
    ]
}

في السياسة المذكورة أعلاه، استبدل دور الناشر Stacy ARN بالقيمة التي يمكنك العثور عليها في معلمة الإخراج PublisherRoleArn الخاصة بمكدس CloudFormation، واسم المجموعة باسم مجموعة موقع الويب المستهدف (المجموعة التي يتم تطبيق السياسة عليها).

الآن عليك إعداد بيئة التطوير الخاصة بك للنشر. افتح وحرر ملف .env في مشروع موقع الويب الخاص بك. في ذلك، قم بتعيين جميع متغيرات AWS_* على القيم الصحيحة. لاحظ أنه يمكنك العثور على قيمة متغير AWS_PUBLISH_EVENT_SOURCE_MAPPING في معلمة إخراج PublishEventSourceMappingId الخاصة بمكدس CloudFormation.

بمجرد إعداد ملف .env بشكل صحيح، يمكنك نشر موقع الويب الخاص بك باستخدام:

 stacy publish

خطوة الإعداد الأخيرة هي تكوين خطاف ويب في مساحة المحتوى الخاصة بك للاتصال بناشر Stacy عند أحداث النشر وإلغاء النشر . في حساب AWS الخاص بك، في خدمة API Gateway، ابحث عن واجهة برمجة التطبيقات التي أنشأتها لك Stacy. توجد طريقة واحدة فقط POST /publish في مرحلة prod واجهة برمجة التطبيقات. لاحظ عنوان URL الخاص به للاستدعاء .

انتقل أيضًا إلى قسم مفاتيح API ولاحظ قيمة مفتاح API الذي تم إنشاؤه لـ Stacy.

في مساحتك المحتوى، انتقل إلى إعدادات المساحة → Webhooks وأضف خطافًا على الويب. ضع عنوان URL لاستدعاء API Gatwey في حقل URL (اترك الطريقة POST ). ثم اختر خيار تحديد أحداث تشغيل محددة في قسم المشغلات . حدد مربعي اختيار النشر وإلغاء النشر في صفي الإدخال والأصول (تم تحديد 4 مربعات اختيار تمامًا).

في قسم الرؤوس ، انقر فوق إضافة رأس سري . ضع "X-API-Key" في حقل المفتاح وفي حقل القيمة ، ضع مفتاح API من بوابة API.

بمجرد حفظ خطاف الويب هذا، سيؤدي نشر الإدخالات والأصول وإلغاء نشرها في Contentful إلى تشغيل الناشر في إعداد AWS وستكون جاهزًا تمامًا!