spaghettify

สปาเก็ตตี้ฟาย

Spaghettify เปลี่ยนไซต์ HTML แบบคงที่ให้เป็นแอปพลิเคชันหน้าเดียวด้วยการนำทางที่ขับเคลื่อนด้วย AJAX และองค์ประกอบ DOM จะช่วยรักษาคุณสมบัติการคงอยู่ ในการดำเนินการดังกล่าว ระบบจะใช้ตัวดักจับ DOM และ ตัวประมวลผลช่องทางมิดเดิลแวร์ ที่รวบรวมเหตุการณ์การคลิกลิงก์ ดึงเอกสารที่ร้องขอแต่ละรายการผ่าน XHR และย่อยการตอบสนองโดยการสตรีมผ่านชุดฟังก์ชัน middlware ก่อนที่จะรีเฟรชเอกสารเบราว์เซอร์

ฟังก์ชันมิดเดิลแวร์เหล่านี้เป็นตัวจัดการ I/O แบบเสียบได้ ซึ่งปฏิบัติตามหลักการความรับผิดชอบเดี่ยวและเป็นไปตามไปป์ไลน์ของขั้นตอนทั้งหมด ซึ่งสามารถจัดหมวดหมู่ได้เป็น hook มิดเดิลแวร์ onBeforeComplete ซึ่งไม่เปลี่ยนรูปแบบ DOM ของเพจปัจจุบัน และ hook มิดเดิลแวร์ onAfterComplete ที่ใช้การเปลี่ยนแปลง (จึงกลายพันธุ์) โดยตรงบน DOM ของหน้าปัจจุบันหลังจากที่ถูกแทรกเข้าไป

โครงการทั้งหมดสร้างขึ้นจาก TypeScript และใช้โพลีฟิลและกลยุทธ์การเขียนโค้ดหลายอย่างเพื่อขยายการรองรับไปยังเบราว์เซอร์รุ่นเก่า เช่น MSIE11

การตั้งค่าสภาพแวดล้อมของคุณ

ข้อกำหนดขั้นต่ำสำหรับการรันโปรเจ็กต์นี้ ทั้งในโหมดการพัฒนาหรือการใช้งานจริง และสคริปต์การพัฒนาคือ node v12.16.0 และ npm v.6.14.15 หรือเวอร์ชันที่ใหม่กว่า โปรเจ็กต์นี้อาจทำงานได้อย่างราบรื่นบน node และ npm เวอร์ชันเก่า แต่เราขอแนะนำให้ใช้ LTS เวอร์ชันล่าสุด

โปรเจ็กต์นี้อาศัย BabelJS และ Webpack ในการคอมไพล์โค้ดในโหมด dev การรันบิลด์จะรองรับไฟล์ไซต์สาธิต และการจัดการการเพิ่มประสิทธิภาพโค้ด

การโต้ตอบทั้งหมดกับ BabelJS และ Webpack ได้รับการสรุปในสคริปต์ npm ที่กำหนดเองเพื่อความสะดวกของคุณ

การติดตั้งการพึ่งพา

ในขั้นตอนแรกในการสร้างสภาพแวดล้อมการพัฒนาหรือรุ่นที่ใช้งานจริง โปรดรัน yarn หรือ npm install เพื่อดึงการขึ้นต่อกันที่จำเป็นทั้งหมดสำหรับโปรเจ็กต์นี้

สร้างโครงการเพื่อการผลิต

กรุณาดำเนินการ yarn build หรือ npm run build จากหน้าต่างเทอร์มินัลของคุณ

ตัวรวมโปรเจ็กต์จะนำทางผ่านแผนผังแอปพลิเคชันทั้งหมด และจะสร้างส่วน JavaScript ลงในโฟลเดอร์ /dist ซึ่งรวมเป็น spaghettify.js ชุดรวมที่มีประโยชน์อื่นๆ จะถูกบันทึกไว้ที่นั่นเช่นกันเพื่อความสะดวกของคุณ

ฉันสามารถดึง Spaghettify จากรีจิสทรี npm ได้หรือไม่ ในขณะที่เขียนสิ่งนี้ ลำดับความสำคัญของโครงการคือการเพิ่มความครอบคลุมการทดสอบอีกเล็กน้อย และขยายขีดความสามารถของ API ด้วยการสนับสนุนเพิ่มเติมสำหรับ hook มิดเดิลแวร์ที่ผู้ใช้จัดเตรียมไว้ ในขณะนี้ Spaghettify มีไว้เพื่อใช้เป็นการพึ่งพาเบราว์เซอร์ แต่การแจกจ่ายเป็นแพ็คเกจ NPM ยังอยู่ในแผนงาน โปรดกลับมาตรวจสอบการอัปเดตอีกครั้งเร็วๆ นี้

Spaghettify API

คุณสามารถสร้างอินสแตนซ์และโต้ตอบกับ Spaghettify ผ่านการจัดเลี้ยง API ที่สะดวกสบายด้วยการสลับส่วนกลาง ตัวดักเส้นทาง การยกเว้น และแฟล็กแอตทริบิวต์การคงอยู่ของสถานะ และสุดท้ายแต่ไม่ท้ายสุดคือการโหลดตัวบ่งชี้ความคืบหน้าและตัวจัดการ

เมื่อคุณคอมไพล์ Spaghettify สำเร็จแล้ว คุณสามารถนำเข้าและสร้างอินสแตนซ์ลงในแอปพลิเคชันของคุณได้ดังนี้:

 < script type =" text/javascript " src =" /dist/spaghettify.js " > </ script >
< script type =" text/javascript " >
  new Spaghettify ( {
    enabled : true ,
    routes : [ '*.html' , 'content/*' ] ,
    excludeByAttr : 'no-spa' ,
    loadProgress : true ,
    persistAttr : 'data-persist' ,
  } ) ;
</ script >

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

API การตั้งค่า Spaghettify

ออบเจ็กต์การตั้งค่าการกำหนดค่า Spaghettify สามารถสรุปได้ดังนี้:

สนาม	พิมพ์	ค่าเริ่มต้น	คำอธิบาย
enabled	Boolean	true	เปิดหรือปิดใช้งาน Spaghettify เมื่อสร้างอินสแตนซ์
routes	String[]	['*']	กำหนดรูปแบบเส้นทางที่จะดักจับและให้บริการผ่าน Spaghettify รองรับโทเค็น glob
excludeByAttr	String	undefined	กำหนดโทเค็นแอตทริบิวต์ข้อมูลการยกเว้น (มีหรือไม่มีคำนำหน้า data- ) ลิงก์ที่ตกแต่งด้วยคุณลักษณะนี้จะถูกข้ามโดย Spaghettify
loadProgress	Function Boolean	false	เปิดใช้งานแถบความคืบหน้าในตัวหรือไม่ นอกจากนี้ยังสามารถใช้ตัวจัดการฟังก์ชันที่จะได้รับจำนวนเต็มความคืบหน้าเป็นเปอร์เซ็นต์เมื่อโหลด
persistAttr	String	undefined	กำหนดแอตทริบิวต์ข้อมูลสถานะการคงอยู่ของสถานะ UI (มีหรือไม่มีคำนำหน้า data- ) องค์ประกอบที่ตกแต่งด้วยแอตทริบิวต์นี้จะยังคงอยู่ในสถานะตลอดการนำทางหน้า

โปรดทราบว่าตัวเลือกการกำหนดค่าทั้งหมด (และเพย์โหลดของตัวเลือกเอง) เป็นทางเลือกและจะใช้ค่าเริ่มต้นหากไม่ได้ประกาศไว้อย่างชัดเจน

ทิ้ง Spaghettify หลังการใช้งาน

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

 < script type =" text/javascript " >
  // First, we instantiate Spaghettify
  const spa = new Spaghettify ( ) ;
  // Then we dispose it after use
  spa . destroy ( ) ;
</ script >

เคล็ดลับ: การยกเว้นลิงก์ไม่ให้ถูกดักจับโดย Spaghettify

ลิงก์ทั้งหมดได้รับการกำหนดค่าโดย Spaghettify เนื่องจากอาจถูกดักจับได้ เครื่องจักรตัวจัดการเหตุการณ์ภายในจะประเมินว่าลิงก์มีสิทธิ์ได้รับการปฏิบัติเหมือนคำขอ AJAX หรือไม่โดยการทดสอบค่า link href กับโทเค็น glob routes

อย่างไรก็ตาม เราสามารถข้ามขั้นตอนนี้ล่วงหน้าได้โดยการกำหนดค่าตัวเลือก excludeByAttr ด้วยค่าแอตทริบิวต์ ไม่ว่าจะมีคำนำหน้า data- หรือไม่ก็ตาม

อย่างไรก็ตาม เพื่อประโยชน์ด้านความหมาย Spaghettify จะพิจารณาเฉพาะองค์ประกอบลิงก์ที่กำหนดค่าด้วยแอตทริบิวต์แบบเต็มเท่านั้น

 < script type =" text/javascript " >
  new Spaghettify ( {
    excludeByAttr : 'skip-me' ,
  } ) ;
</ script >

<!-- Spaghettify will disregard the following link -->
< a href =" foo.html " data-skip-me > Skip this link </ a >

คุณลักษณะที่กำหนดค่าสามารถเติมด้วยค่าใดๆ หรือไม่มีเลยก็ได้ Spaghettify จะไม่สนใจค่านั้นเลย

เคล็ดลับ: การกำหนดค่าตัวจัดการโหลดแบบกำหนดเอง

ดังที่เราเห็นไปแล้ว ตัวเลือกการกำหนด loadProgress สามารถใช้ค่า Boolean ดั้งเดิมหรือ ตัวจัดการฟังก์ชัน

 < script type =" text/javascript " >
  new Spaghettify ( {
    loadProgress : true ,
  } ) ;
</ script >

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

อย่างไรก็ตาม ผู้บริโภคอาจต้องการใช้โซลูชันภาพของตนเองเพื่อแสดงข้อมูลความคืบหน้าในการดาวน์โหลด Spaghettify ครอบคลุมสิ่งเหล่านี้ด้วยการจัดหาตัวจัดการความคืบหน้าในการโหลดที่คาดหวังพารามิเตอร์ค่าจำนวนเต็มในลายเซ็น ซึ่งจะใช้ค่าตั้งแต่ 0 ถึง 100 เมื่อมีการร้องขอและดาวน์โหลดเพจผ่าน HXR

 < script type =" text/javascript " >
  new Spaghettify ( {
    loadProgress : function onLoad ( progress ) {
      console . log ( progress ) ; // Will log values from 0 to 100
    } ,
  } ) ;
</ script >

เคล็ดลับ: สถานะคงอยู่ตลอดการนำทาง

Spaghettify ใช้ API ทดลองสำหรับสถานะคงอยู่ในโหนด DOM ที่เลือกและมีคำอธิบายประกอบในการนำทางหน้า ในการทำเช่นนั้น คุณเพียงแค่ต้องกำหนดค่าโทเค็นค่าในตัวเลือก persistAttr จากนั้นใส่คำอธิบายประกอบองค์ประกอบ DOM เหล่านั้นซึ่งมีสถานะที่คุณต้องการคงอยู่ด้วย data- แอตทริบิวต์ที่เทียบเท่ากับค่าที่ไม่ซ้ำกันแต่ละรายการ:

 < script type =" text/javascript " >
  new Spaghettify ( {
    persistAttr : 'persist-id' ,
  } ) ;
</ script >

< input type =" text " data-persist-id =" my-input " />

คุณสามารถกำหนดคำนำหน้าค่าด้วย data- หรือไม่ก็ได้ แต่ Spaghettify จะต้องให้คุณใส่คำอธิบายประกอบองค์ประกอบ DOM เพื่อคงอยู่กับไวยากรณ์แอตทริบิวต์ข้อมูลแบบเต็ม

โปรดทราบ : ค่าแอตทริบิวต์มีไว้เพื่อให้ไม่ซ้ำกัน Spaghettify จะส่งข้อยกเว้นหากมีการกำหนดค่าองค์ประกอบประเภทที่แตกต่างกันมากกว่าหนึ่งรายการด้วยค่าแอตทริบิวต์เดียวกัน

เป็นเรื่องที่ควรค่าแก่การเน้นว่าการคงอยู่จะถูกนำไปใช้กับ Node DOM แบบเต็ม ดังนั้นจะครอบคลุมไม่เพียงแต่ HTML ภายในขององค์ประกอบเท่านั้น แต่ยังรวมไปถึงสถานะ การสัมผัส ดั้งเดิมสำหรับการควบคุมอินพุตด้วย และทั้งหมดนี้โดยไม่คำนึงถึงการเปลี่ยนแปลงใน HTML ภายนอก

การรัน Spaghettify ในโหมดการพัฒนา

คุณสามารถสร้างสภาพแวดล้อมการพัฒนาได้โดยการรัน yarn dev หรือ npm run dev ในคอนโซล

ระบบจะสร้างสิ่งประดิษฐ์ทั้งหมดและให้บริการไซต์แซนด์บ็อกซ์ (รายละเอียดเพิ่มเติมด้านล่าง) จาก http://localhost:3000 (หรือพอร์ตอื่น ๆ ที่คุณเลือกหากคุณผนวก --port=PORT พารามิเตอร์ต่อท้ายคำสั่ง dev โดยที่ PORT คือพอร์ตที่ต้องการ) ใน โหมดนาฬิกา ดังนั้นแอปพลิเคชันจะถูกคอมไพล์ใหม่เมื่อมีการเปลี่ยนแปลงในซอร์สโค้ด

ไซต์แซนด์บ็อกซ์

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

• index.html หลักมีอินสแตนซ์ของ Spaghettify แบบอินไลน์เพื่อวัตถุประสงค์ในการสาธิต เอกสารอื่นๆ ทั้งหมดใช้อินสแตนซ์ดังกล่าวเป็นสคริปต์ที่นำเข้า คุณไม่จำเป็นต้องนำเข้า Spaghettify ในแต่ละเอกสาร เฉพาะรายการเดียวเท่านั้น อย่างไรก็ตาม สิ่งนี้ทำให้สามารถเปิด Spaghettify จากเอกสารใด ๆ หลังจากโหลดหน้าต่างเบราว์เซอร์ซ้ำเพื่อวัตถุประสงค์ในการสาธิต ในสถานการณ์การผลิตจริง Spaghettify สามารถ (และควร) นำเข้าและสร้างอินสแตนซ์ได้เพียงครั้งเดียวในตำแหน่งรายการ
• ลิงก์ไปยังเพจ B ได้รับการกำหนดค่าให้ข้าม Spaghettify และบังคับให้โหลดทั้งหน้า เนื่องจากมีการนำเข้าที่นั่น Spaghettify จะเข้ามาควบคุมการนำทางจากที่นั่น
• เนื้อหากระจัดกระจายอยู่ระหว่างระดับรากของ /sandbox และโฟลเดอร์ย่อย /sandbox/content ดังนั้นผู้ร่วมให้ข้อมูลสามารถเล่นกับตัวเลือกลิงก์ที่ชี้ไปยังโฟลเดอร์ย่อยได้ หากจำเป็น
• เนื้อหาหลักประกอบด้วยข้อความจำลองที่มีการเปลี่ยนแปลงเล็กน้อยเพื่อให้แน่ใจว่าการเปลี่ยนหน้าจะสังเกตเห็นได้ชัดเจน
• เมนูด้านข้างมีการควบคุมอินพุตที่หลากหลายเพื่อตรวจสอบความคงอยู่ของสถานะในหน้าต่างๆ ที่สำรวจ
• หน้า A และหน้าภายใน /sandbox/content มี JavaScript แบบกำหนดเองแบบอินไลน์หรือนำเข้าที่ Spaghettify จะแยกแยะ ปฏิเสธซ้ำ และดำเนินการเมื่อจำเป็น
• Spaghettify รองรับการนำทางประวัติไปข้างหน้าและข้างหลัง เดินดูรอบๆ และลองดูสิ!

การร่วมสนับสนุนโค้ดของคุณ

ปัจจุบัน ESLint เปิดใช้งานอยู่ในโค้ดเบส Spaghettify และการตรวจสอบ Linting จะถูกทริกเกอร์เมื่อสร้างโปรเจ็กต์ คุณสามารถกำหนดค่า IDE ของคุณเพื่อให้มีการประเมิน Linting โดยอัตโนมัติเมื่อคุณแนะนำการเปลี่ยนแปลง ยิ่งไปกว่านั้น คุณยังสามารถทริกเกอร์การ Lint โค้ดได้ทุกเมื่อด้วยการรัน npm run lint หรือ yarn lint ในคอนโซลเทอร์มินัลของคุณ

ทดสอบการมีส่วนร่วมของโค้ดของคุณ

คุณสามารถแนะนำการทดสอบในโค้ดเบสหรือดำเนินการการทดสอบที่มีอยู่โดยการรัน npm test หรือ yarn test ในคอนโซลเทอร์มินัลของคุณ ข้อมูลการครอบคลุมโค้ดจะถูกรวบรวมและจัดเก็บไว้ในเอกสารที่มีรูปแบบสะดวกที่ /coverage/lcov-report สำหรับการรายงานความครอบคลุมบนหน้าจอ โปรดเพิ่มพารามิเตอร์ --coverage ต่อท้ายคำสั่ง test

คุณยังสามารถตรวจสอบรายงานความครอบคลุมการทดสอบที่ครอบคลุมทางออนไลน์ได้ที่ Coveralls

เผยแพร่ภายใต้ใบอนุญาต MIT

ลิขสิทธิ์ 2021 ปาโบล ดีเลแมน

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

ประกาศเกี่ยวกับลิขสิทธิ์ข้างต้นและประกาศการอนุญาตนี้จะรวมอยู่ในสำเนาทั้งหมดหรือส่วนสำคัญของซอฟต์แวร์

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