stacy

สเตซี่

Stacy คือเครื่องมือสร้างเว็บไซต์ที่รวมเนื้อหาจาก Contentful CMS เข้ากับเทมเพลตแฮนด์บาร์เพื่อสร้างหน้าเว็บไซต์

Stacy จับคู่ประเภทเนื้อหารายการของ Contentful กับเทมเพลตแฮนด์บาร์ในโครงการเว็บไซต์ของคุณโดยมีความสัมพันธ์แบบหนึ่งต่อหนึ่ง โดยจะมีเทมเพลตสำหรับรายการทุกประเภทที่กำหนดไว้ใน โมเดลเนื้อหา ของคุณ มีรายการสองประเภทจากมุมมองของ Stacy: รายการหน้า และ รายการโมดูล รายการหน้าเว็บที่รวมกับเทมเพลตจะสร้างหน้าเว็บไซต์เดียวที่ URL ที่ไม่ซ้ำใคร รายการโมดูลสามารถรวมไว้ในเพจและโมดูลอื่นๆ ได้โดยใช้ฟิลด์ อ้างอิง ของ Contentful เพื่อสร้างชิ้นส่วนของเนื้อหาที่นำมาใช้ซ้ำได้ หรือเพียงแค่จัดเตรียมเนื้อหาและโครงสร้างเทมเพลตโดยแบ่งออกเป็นชิ้นเล็กๆ

สิ่งที่ทำให้ Stacy แตกต่างจากโปรแกรมสร้างเว็บไซต์คงที่ที่มีอยู่หลายตัวก็คือ รองรับการเผยแพร่เว็บไซต์โดยอัตโนมัติไปยังบัคเก็ต S3 ใน Amazon Cloud จากที่ที่สามารถให้บริการบนอินเทอร์เน็ตได้ Stacy ปรับใช้โครงสร้างพื้นฐานพิเศษใน Amazon Cloud ซึ่งสามารถเชื่อมต่อกับ Contentful ผ่านฟังก์ชัน Webhooks เมื่อเนื้อหาได้รับการอัปเดตในพื้นที่ Contentful ของคุณ โครงสร้างพื้นฐานของเว็บไซต์ของคุณที่ใช้งานโดย Stacy ใน Amazon Cloud จะได้รับการแจ้งเตือนและสร้างใหม่และเผยแพร่ซ้ำเฉพาะหน้าเว็บไซต์ของคุณที่ได้รับผลกระทบจากการอัปเดตโดยอัตโนมัติ ไม่จำเป็นต้องสร้างเว็บไซต์ใหม่และปรับใช้ใหม่ด้วยตนเอง

เมื่อใช้ Stacy เว็บไซต์ของคุณเป็นโปรเจ็กต์ NPM ซึ่งมักจะตรวจสอบในพื้นที่เก็บข้อมูล git สำหรับการควบคุมเวอร์ชัน โปรเจ็กต์นี้ประกอบด้วยเทมเพลตแฮนด์บาร์และเนื้อหาคงที่ (เช่น สไตล์ชีต CSS รูปภาพที่ใช้ในการออกแบบเว็บไซต์ แบบอักษร ฯลฯ) ในขณะที่เนื้อหาเว็บไซต์อยู่ในพื้นที่เนื้อหา จากโครงการเว็บไซต์ นักพัฒนาเว็บไซต์ใช้เครื่องมือบรรทัดคำสั่งของ Stacy เพื่อพัฒนา เผยแพร่ และเผยแพร่ไซต์อีกครั้ง เมื่อเผยแพร่เว็บไซต์ใน Amazon Cloud แล้ว ผู้เขียนเนื้อหาจะทำงานเฉพาะกับ Contentful UI เท่านั้น

ดูการสร้างเว็บไซต์ด้วย Stacy สำหรับบทช่วยสอน/คำแนะนำแบบละเอียด

เริ่มต้นใช้งาน

ขั้นแรก คุณต้องมีพื้นที่เนื้อหาเพียงพอสำหรับเนื้อหาเว็บไซต์ของคุณ เมื่อคุณมีสิ่งนั้นแล้ว คุณสามารถสร้างโปรเจ็กต์ใหม่สำหรับเว็บไซต์ของคุณได้

ตรวจสอบให้แน่ใจว่าคุณได้ติดตั้ง Node.js เวอร์ชัน 10.16.3 หรือใหม่กว่าพร้อมกับ npm หากคุณกำลังจะเผยแพร่เว็บไซต์ใน Amazon Cloud คุณจะต้องติดตั้ง AWS CLI ด้วย

เริ่มต้นด้วยการติดตั้ง Stacy ทั่วโลก:

 npm install -g stacy

ใน Contentful space ของคุณ ให้ไปที่ การตั้งค่า Space → คีย์ API และเพิ่มคีย์ API ใน โทเค็นการส่งเนื้อหา/การแสดงตัวอย่าง หมายเหตุ ค่าโทเค็นการเข้าถึง Space ID และ Content Delivery API ที่คุณจะใช้ในการเชื่อมต่อสภาพแวดล้อม Stacy กับ Contentful Space ของคุณ

ตอนนี้คุณสามารถสร้างโปรเจ็กต์เริ่มต้นสำหรับเว็บไซต์ของคุณได้:

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

สิ่งนี้จะสร้างไดเร็กทอรีโปรเจ็กต์ใหม่ชื่อ "mywebsite" ในไดเร็กทอรีปัจจุบัน ค่า "mywebsite" เรียกว่า รหัสไซต์ ใช้ค่าอื่นที่ระบุเว็บไซต์ของคุณ ค่าควรเป็นแบบ URL-fiendly (ตัวอักษรตัวเล็ก ตัวเลข และขีดกลาง)

ในไดเร็กทอรีโปรเจ็กต์ของคุณ ให้วางเนื้อหาคงที่ไว้ใต้ /static (ซึ่งจะถูกคัดลอกไปยังเว็บไซต์ของคุณตามสภาพที่เป็นอยู่) และวางเทมเพลตรายการของคุณไว้ข้างใต้ /templates ชื่อของไฟล์เทมเพลต (ไม่มีส่วนขยาย) จะต้องตรงกับประเภทเนื้อหารายการที่เกี่ยวข้องใน โมเดล Contentful Content ของคุณทุกประการ ภายใต้ /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 ของรายการ โปรดทราบว่าเป็น Field ID ที่ใช้ที่นี่ ไม่ใช่ Field Name

Stacy เพิ่มตัวช่วยพิเศษบางอย่างที่คุณสามารถใช้ในเทมเพลตของคุณได้:

• module <reference field> - รวมรายการโมดูลที่อ้างอิงโดยฟิลด์ประเภทการอ้างอิง ตัวอย่างเช่น คุณมีฟิลด์ที่มี paragraphs ID และเป็นรายการข้อมูลอ้างอิง:

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

• asset <asset field> - รวมเนื้อหาที่อ้างอิง เช่น รูปภาพ ตัวอย่างเช่น:

   {{ asset picture }}

  ปัจจุบันรองรับเฉพาะเนื้อหารูปภาพซึ่งมีการแสดงผลแท็ก HTML <img>

• assetSrc <asset field> - รับ URL ของ Asset ตัวอย่างเช่น:

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

• assetTitle <asset field> - รับชื่อของสินทรัพย์ ตัวอย่างเช่น:

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

• markdown <long text field> - เรนเดอร์ฟิลด์ข้อความยาว Markdown ตัวอย่างเช่น:

   {{{ markdown description }}}

  โปรดสังเกตว่าจำเป็นต้องใช้วงเล็บปีกกาสามอันที่นี่เนื่องจากตัวช่วยสร้าง HTML ซึ่งไม่จำเป็นต้อง Escape

• richText <rich text field> - แสดงผลฟิลด์ข้อความที่หลากหลาย ตัวอย่างเช่น:

   {{{ richText content }}}

  เช่นเดียวกับ markdown ให้สังเกตเครื่องหมายปีกกาสามอัน

• json <field> - เอาท์พุตการแสดง Contentful JSON ภายในของฟิลด์ ตัวอย่างเช่น:

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

  ตัวช่วยนี้อาจมีประโยชน์สำหรับการวินิจฉัยปัญหา

โมเดลเนื้อหา

ตามที่กล่าวไว้ข้างต้น มีความสัมพันธ์แบบหนึ่งต่อหนึ่งระหว่างประเภทเนื้อหาที่คุณกำหนดใน รูปแบบเนื้อหา และเทมเพลตของ Contentful space

หมายเหตุ: พูดอย่างเคร่งครัด คุณสามารถมีเทมเพลตได้มากกว่าหนึ่งเทมเพลตสำหรับประเภทเนื้อหาที่กำหนด เพื่อให้สามารถสร้างไฟล์ประเภทต่างๆ สำหรับรายการเนื้อหาเดียวกันได้ ตัวอย่างเช่น สำหรับ module ID ประเภทเนื้อหา คุณสามารถมีเทมเพลต module.html.hbs และ module.xml.hbs เทมเพลตแรกจะสร้างไฟล์ HTML สำหรับรายการ และเทมเพลตที่สองจะสร้างไฟล์ XML

เมื่อคุณกำหนดประเภทเนื้อหา ให้จดบันทึก Api Identifier (หรือที่เรียกว่า Content Type ID ) ไฟล์เทมเพลตสำหรับประเภทเนื้อหาจะต้องมีชื่อเดียวกัน (บวกส่วนขยาย)

มีข้อกำหนดประการหนึ่งสำหรับประเภทเนื้อหาสำหรับรายการเพจ (ซึ่งตรงกันข้ามกับรายการโมดูล): ประเภทเนื้อหาของหน้าต้องกำหนดฟิลด์ Slug ที่จำเป็น ค่าในฟิลด์จะเป็นการกำหนดชื่อของไฟล์ที่สร้างขึ้นเมื่อรายการเนื้อหาถูกรวมเข้ากับเทมเพลตที่เกี่ยวข้อง ตัวอย่างเช่น หากค่า Slug สำหรับการป้อนเพจคือ "index" เพจที่สร้างขึ้นจะเป็น "/index.html" หากตัวบุ้งคือ "more/terms" หน้านั้นจะเป็น "/more/terms.html" และอื่นๆ

ตามค่าเริ่มต้น ID ฟิลด์สำหรับฟิลด์ slug จะต้องเป็น slug สามารถแทนที่รหัสได้ในไฟล์ stacy.json ของโปรเจ็กต์ นอกจากการทำให้ฟิลด์ Slug จำเป็นในคำจำกัดความประเภทเนื้อหาแล้ว ยังแนะนำให้เชื่อมโยงเครื่องมือตรวจสอบรูปแบบการจับคู่ที่กำหนดเองด้วยเพื่อให้แน่ใจว่าค่าของฟิลด์มีรูปแบบเฉพาะ นิพจน์ทั่วไปสำหรับเครื่องมือตรวจสอบความถูกต้องสามารถเป็น ^w[w-]*(/w[w-]*)*$

การเผยแพร่ใน Amazon Cloud

เมื่อคุณพร้อมที่จะปรับใช้เว็บไซต์ของคุณใน AWS คุณต้องตั้งค่าโครงสร้างพื้นฐาน Stacy ภายใต้บัญชี AWS ของคุณก่อน คุณต้องดำเนินการหลายขั้นตอนก่อนจึงจะสามารถทำได้:

1. สร้างบัคเก็ต S3 เป้าหมาย นี่คือที่ที่เว็บไซต์ของคุณจะถูกเผยแพร่และจะให้บริการจากที่ใด (อาจผ่าน CloudFront) หรือคุณสามารถใช้บัคเก็ตที่คุณมีอยู่แล้ว (Stacy ยังรองรับการเผยแพร่ในโฟลเดอร์ย่อยในบัคเก็ตเป้าหมายด้วย)

2. หากคุณยังไม่มี ให้สร้างบัคเก็ต S3 ที่ Stacy จะใช้อัปโหลดแพ็คเกจฟังก์ชัน Lambda ของผู้เผยแพร่ ฟังก์ชัน Lambda ผู้เผยแพร่เป็นส่วนที่ตอบสนองต่อเหตุการณ์ การเผยแพร่ และ ยกเลิกการเผยแพร่ อย่างมีเนื้อหา และอัปเดตหน้าและเนื้อหาที่เกี่ยวข้องในบัคเก็ต S3 เป้าหมาย

3. สร้างแพ็คเกจผู้เผยแพร่:

    stacy build-publisher
   

   สิ่งนี้จะสร้างแพ็คเกจฟังก์ชัน Lambda ผู้เผยแพร่ในโปรเจ็กต์ของคุณภายใต้ /build/stacy-mywebsite-publisher.zip อัปโหลดไฟล์นี้ไปยังบัคเก็ต S3 ฟังก์ชัน Lambda ของคุณ

คำสั่ง stacy new ของ Stacy ได้สร้างเทมเพลต 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

ขั้นตอนการตั้งค่าสุดท้ายคือการกำหนดค่าเว็บฮุคในพื้นที่ Contentful ของคุณเพื่อโทรหาผู้เผยแพร่ Stacy เมื่อ เผยแพร่ และ ยกเลิกการเผยแพร่ กิจกรรม ในบัญชี AWS ของคุณ ในบริการ API Gateway ให้ค้นหา API ที่สร้างโดย Stacy สำหรับคุณ มีเพียงวิธีเดียวเท่านั้น POST /publish ในขั้นตอน prod ของ API สังเกตว่ามัน เรียกใช้ URL

นอกจากนี้ ให้ไปที่ส่วน คีย์ API และจดบันทึกค่าของคีย์ API ที่สร้างขึ้นสำหรับ Stacy

ในพื้นที่ Contentful ของคุณ ให้ไปที่ การตั้งค่า Space → Webhooks และเพิ่ม webhook ใส่ URL การเรียกใช้ของ API Gatwey ลงในช่อง URL (ปล่อยให้เมธอด POST ) จากนั้นเลือกตัวเลือก เลือก เหตุการณ์การทริกเกอร์เฉพาะ ในส่วน ทริกเกอร์ เลือกช่องทำเครื่องหมาย เผยแพร่ และ ยกเลิก การเผยแพร่ในแถว รายการ และ เนื้อหา (เลือกช่องทำเครื่องหมายทั้งหมด 4 ช่อง)

ในส่วน ส่วนหัว ให้ คลิก เพิ่มส่วนหัวที่เป็นความลับ ใส่ "X-API-Key" ในช่อง คีย์ และในช่อง Value ให้ใส่คีย์ API จาก API Gateway

เมื่อคุณบันทึก webhook นี้ การเผยแพร่และการยกเลิกรายการและเนื้อหาใน Contentful จะทริกเกอร์ผู้เผยแพร่ในการตั้งค่า AWS และคุณก็พร้อมแล้ว!