pushtape cassette

เทปคาสเซ็ต

Pushtape Cassette เป็นเฟรมเวิร์กน้ำหนักเบาสำหรับการสร้างแอปพลิเคชันเว็บเพลงที่ดีขึ้น สร้างเทปเพลงของคุณและเรนเดอร์เว็บแอปเพลงที่สมบูรณ์ภายในไม่กี่วินาที พร้อมด้วยเครื่องเล่นเพลงแบบถาวร

สาธิต

เกี่ยวกับ

โปรเจ็กต์นี้สร้างเว็บแอปเพลงแบบคงที่ที่สามารถรวมเข้ากับเทคโนโลยีแบ็กเอนด์จำนวนเท่าใดก็ได้: ไฟล์แบบเรียบ, Wordpress/Drupal, JS Frameworks, Python และ Ruby องค์ประกอบสำคัญที่ขับเคลื่อนแนวคิดนี้คือไฟล์ cassette.json ซึ่งเป็นรูปแบบรายชื่อผลงานแบบพกพา ไฟล์นี้ทำหน้าที่เหมือนกับจุดสิ้นสุดเดียว - และจากจุดสิ้นสุดนี้ javascript จะถูกใช้เพื่อสร้างแอปพลิเคชันหน้าเดียวโดยใช้ไมโครไลบรารีต่างๆ

การติดตั้ง

• โคลน repo นี้ไปยังเว็บเซิร์ฟเวอร์ของคุณ
• ตรวจสอบแท็ก URL พื้นฐานใน index.html
• เพิ่มโฟลเดอร์เพลงใหม่ภายในไดเร็กทอรี releases และเพิ่มไฟล์มาร์กดาวน์ภายในไดเร็กทอรีหน้า
• เรียกใช้ python dub.py หรืออัปเดต cassette.json ด้วยตนเอง
• ไปที่ index.html ในเบราว์เซอร์ของคุณ

URL ฐาน

หากคุณเรียกใช้แอปจากไดเรกทอรีย่อยจากรูทเอกสาร ใน index.html ให้เปลี่ยนแท็กฐานเป็น:

  <base href="/subdirectory/" />

หรือโหลดเนื้อหาทั้งหมดโดยใช้เส้นทางที่แน่นอน

Cassette.json

• สร้าง cassette.json โดยการแก้ไขไฟล์ด้วยตนเองหรือรันสคริปต์ build

 $ cd pushtape-cassette
$ python dub.py

Dub.py

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

• สคริปต์นี้จะค้นหาไฟล์และโฟลเดอร์ในไดเร็กทอรีการทำงานแบบวนซ้ำ และสร้าง cassette.json รวมถึงไฟล์ tracklist.jspf ที่จำเป็น
• ไฟล์ .jspf จะถูกจัดเก็บไว้ใน _data และไดเร็กทอรีเพลงจะไม่ถูกแตะต้อง
• คุณสามารถใช้โฟลเดอร์ย่อยเพื่อจัดระเบียบการเผยแพร่ตามศิลปิน เช่น releases/artist-name/release-name
• หากไม่พบไฟล์อาร์ตเวิร์ค ระบบจะใช้assets/images/default-artwork.jpg

ล้าง URL

หากคุณต้องการลบแฮช # ออกจากเส้นทาง URL และใช้ History API แทน ใน index.html ให้ตั้งค่า app.settings.cleanURLs เป็นจริง โปรดทราบว่าเราสนับสนุนให้เรียกใช้แอปโดยเปิดใช้งาน History API จากรูทเอกสาร เนื่องจากจะดูแลปัญหาลิงก์ที่เกี่ยวข้องทั้งหมด

ตัวอย่างไฟล์แบบแบน

หมายเหตุ: คุณสามารถข้ามขั้นตอนที่ 3 และ 4 ได้หากคุณใช้สคริปต์ dub.py

1. เพิ่มเพจแบบคงที่โดยการสร้างไฟล์มาร์กดาวน์ในไดเร็กทอรี /pages แต่ละไฟล์ควรมีนามสกุล .md
2. เพิ่มเพลงของคุณในไดเรกทอรี /releases วางแต่ละรุ่นไว้ในไดเร็กทอรีของตัวเอง เช่น /releases/release-title หรือ /releases/artist/release-title

• เพิ่มบันทึกย่อซับโดยรวมไฟล์มาร์กดาวน์ของ Notes.md
• เพิ่มอาร์ตเวิร์คโดยรวมไฟล์ Artwork.jpg (แนะนำขนาด 400x400)
• เพิ่ม MP3 หรือรวบรวมรายการ URL MP3 ระยะไกล (แนะนำ 128kbps - 320kbps CBR MP3)

3. สร้างไฟล์ tracklist.jspf สำหรับแต่ละรีลีส ซึ่งมีลำดับของรายการเพลง ข้อมูลเมตา และตำแหน่งไฟล์ (ในเครื่องหรือระยะไกล)
4. สร้าง cassette.json ด้วย URL สำหรับเพจและเพลงใหม่ของคุณ
5. เยี่ยมชมไซต์คงที่ใหม่ของคุณ

การปรับเปลี่ยนธีม

• CSS ได้รับการจัดระเบียบตามหลักการ SMACSS คุณสามารถค้นหาไฟล์ที่เกี่ยวข้องกับธีมได้ใน /assets/css
• รวมตาราง Bootstrap ไว้ด้วย โปรดทราบว่าใน index.html #content div คอนเทนเนอร์มีการใช้คลาส .container-fluid ของ Bootstrap ซึ่งหมายความว่าคุณสามารถใช้คลาส .row และ .col-* สำหรับมาร์กอัปใดๆ ภายใน div นั้นได้
• สำหรับพื้นหลังหน้าขนาดเต็ม ให้มองหาความคิดเห็นภายในasset/css/theme/theme.css

ขั้นสูง

Cassette.json

คุณสมบัติ	พิมพ์	คำอธิบาย
สร้างครั้งสุดท้าย	การประทับเวลา	วิธีการติดตามเมื่อไฟล์ถูกสร้างหรือแก้ไขครั้งล่าสุด
หน้า	วัตถุ	ประกอบด้วยคู่คีย์:ค่าสำหรับเพจแบบคงที่บนไซต์ของคุณ คีย์จะกำหนดเส้นทางเราเตอร์ JS ระดับแรก เช่น 'เกี่ยวกับ' ค่านี้มีตำแหน่ง URL สำหรับเอกสารมาร์กดาวน์ URL อาจเป็นแบบสัมพัทธ์หรือแบบสัมบูรณ์ก็ได้ หากเซิร์ฟเวอร์ของคุณส่งคืนเอกสารโดยใช้ JSON/JSONP ให้ตั้งค่า "format" : "json" หากคุณต้องการรวมลิงก์ภายนอกและข้ามเราเตอร์ JS ให้ตั้งค่า "type" : "external"
เผยแพร่	วัตถุ	ประกอบด้วยคู่คีย์:ค่าซึ่งกำหนดเพลงที่เผยแพร่ คีย์จะกำหนดเส้นทางเราเตอร์ JS และควรเป็นตัวพิมพ์เล็กทั้งหมดโดยไม่มีช่องว่าง เช่น ชื่ออัลบั้ม หรือชื่อศิลปิน/อัลบั้ม เส้นทางที่สร้างขึ้นโดยสมบูรณ์จะลงเอยด้วยการเป็น release/ชื่ออัลบั้ม หรือ release/ศิลปิน/ชื่ออัลบั้ม ค่าที่สอดคล้องกันจะกำหนดคุณสมบัติสำหรับรุ่นนี้ อย่างน้อยที่สุด คุณควรระบุ URL สำหรับ Artwork.jpg และ Notes.md (แบบสัมพัทธ์หรือแบบสัมบูรณ์ คุณสามารถเลือกระบุรูปแบบเป็น json ก็ได้) คุณสมบัติเพลย์ลิสต์ต้องเป็นเส้นทางไปยังไฟล์เพลย์ลิสต์ JSPF ที่ถูกต้อง ซึ่งระบุลำดับแทร็กและตำแหน่งของไฟล์ MP3 และข้อมูลเมตาอื่น ๆ

การตั้งค่าแอพ

คุณสมบัติ	พิมพ์	คำอธิบาย
app.settings.cassettePath	เชือก	ตามค่าเริ่มต้น application.js จะโหลดเส้นทาง cassette.json ในเครื่อง คุณสามารถแทนที่เส้นทางไปยัง cassette.json ได้โดยการตั้งค่าตัวแปรร่วมนี้ก่อนที่จะโหลด application.js
app.settings.homePage	เชือก	ค่านี้ระบุว่าเพจใดควรโหลดตามค่าเริ่มต้น เส้นทางจะต้องลงทะเบียนในเราเตอร์ JS
app.settings.cleanURLs	บูลีน	หากเป็นเท็จ จะใช้แฮช # URL หากเป็นจริง History API จะจัดการ URL ที่ปลอดภัย

ปัญหาที่ทราบ:

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

ข้อจำกัด:

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

ตัวอย่าง cassette.json:

 {
  "lastBuild": {},
  "pages": {
     "releases" : {},
     "about" : {"location" : "pages/about.md"},
     "shows" : {"location" : "pages/shows.md"},
     "external-link" : {"title": "Soundcloud", "location" : "http://www.example.com", "type" : "external"}
  },
  "releases": {
    "example-release": {
      "title" : "Cosmic Voyage",
      "playlist" : "releases/example-release/tracklist.jspf",
      "artwork" : "releases/example-release/artwork.jpg",
      "notes" : "releases/example-release/notes.md"  
    },
    "example-release-two": {
      "title" : "Bird Life",
      "playlist" : "releases/example-release-two/tracklist.jspf",
      "artwork" : "releases/example-release-two/artwork.jpg",
      "notes" : "releases/example-release-two/notes.md"  
    }
  }
}

เส้นทางเริ่มต้น

เส้นทาง URL	คำอธิบาย
-	หากไม่ได้ป้อนเส้นทาง ระบบจะโหลดหน้าแรกเริ่มต้น
/[ชื่อหน้า]	ซึ่งจะแยกวิเคราะห์และแสดงมาร์กดาวน์สำหรับเพจตามที่กำหนดใน cassette.json
/เผยแพร่	รายชื่อหนังสือเผยแพร่ทั้งหมดพร้อมอาร์ตเวิร์กและชื่อ ไฮเปอร์ลิงก์ไปยังหน้าหนังสือเผยแพร่แต่ละรายการ
/release/[ชื่อรุ่น] /release/[ชื่อศิลปิน]/[ชื่อผลงาน]	แสดงข้อมูลทั้งหมดสำหรับการเผยแพร่ครั้งเดียว: อาร์ตเวิร์ก รายการเพลงที่เล่นได้ และโน้ต

การแก้ไขปัญหา

ปัญหา	ขั้นตอน
หน้าว่างหรือ CSS/JS หายไป	ตรวจสอบ URL ฐานของคุณอีกครั้งใน index.html หากคุณมีปัญหาในการค้นหาเส้นทางที่ถูกต้อง บางครั้งเส้นทางเซิร์ฟเวอร์สามารถอนุมานได้โดยใช้ตัวตรวจสอบ Chrome
ปัญหาคำขอข้ามต้นทาง (เนื้อหาระยะไกลไม่โหลด)	เมื่อจัดการกับคำขอข้ามต้นทางระยะไกล จะต้องส่งคืน JSONP ที่ถูกต้อง และคำขอจะต้องมีรูปแบบที่ถูกต้อง 1. คุณต้องผ่าน ?callback=? ใน URL เช่น http://example.com/cassette.json?callback=? 2: การตอบกลับจากเซิร์ฟเวอร์ต้องเป็น JSONP ไม่ใช่เฉพาะ JSON ปกติ โดยเฉพาะอย่างยิ่ง ปัญหาข้ามต้นทางอาจเกิดขึ้นเมื่อโหลด cassette.json, jspf, Notes.md และ Pages.md จากระยะไกล หรือคุณสามารถโหลดเนื้อหาทั้งหมดในเครื่องเพื่อหลีกเลี่ยงการตั้งค่าวิธีแก้ปัญหา JSONP
ไซต์ไม่ได้รับการจัดทำดัชนีโดยเครื่องมือค้นหา	นอกเหนือจากการตรวจสอบ robots.txt และแนวทางปฏิบัติที่ดีที่สุดอื่นๆ แล้ว นี่เป็นปัญหาที่ทราบเกี่ยวกับเฟรมเวิร์กที่ใช้ Javascript ในการแสดงผลเนื้อหาของหน้า วิธีแก้ปัญหาที่ง่ายที่สุดคือการใช้บริการเช่น prerender.io เพื่อแคชและให้บริการหน้า HTML ที่แสดงผล ฉันแนะนำให้ติดตั้งโทเค็น prerender.io ผ่าน Apache ต่อไปนี้เป็นข้อมูลสรุปว่า .htaccess ของคุณอาจมีหน้าตาเป็นอย่างไร (คุณจะต้องเปลี่ยน TOKEN_VALUE และ http://example.com สำหรับไซต์ของคุณ)

ทำไมฉันถึงทำสิ่งนี้?

ไซต์เพลงจำนวนมากค่อนข้างคงที่ แต่มีข้อกำหนดส่วนหน้าที่ยุ่งยาก UX เพลงที่ดีที่สุดช่วยให้ได้รับประสบการณ์การฟังเพลงที่ไม่ขาดตอนในขณะที่ทำงานอื่นๆ เช่น อ่านโน้ตเพลง เรียกดูเพลงอื่นๆ เป็นต้น โดยปกติแล้วจะหมายถึง AJAX ในการสร้าง CMS/ไซต์แบบคงที่แบบดั้งเดิม หรือสร้างโซลูชันที่สมบูรณ์ตั้งแต่เริ่มต้นโดยใช้ JS สิ่งนี้กลายเป็นเรื่องน่าปวดหัวอย่างรวดเร็วในการสร้างและบำรุงรักษา โดยเฉพาะอย่างยิ่งในระยะยาว ด้วยการสร้างเฟรมเวิร์กส่วนหน้าแบบแยกส่วน ช่วยให้แยกข้อกังวลได้ดีขึ้น และลดความพยายามในระยะยาวที่จำเป็นในการสร้างและบำรุงรักษาไซต์ นอกจากนี้ ด้วยการใช้ประโยชน์จาก JSPF และ cassette.json ซึ่งเป็นรูปแบบรายชื่อผลงานแบบพกพา ความสามารถในการพกพาข้อมูลจึงไม่ใช่สิ่งที่ต้องคิดในภายหลัง แต่มันถูกสร้างไว้ในแอปพลิเคชันตั้งแต่ต้น

ทำไมต้องใช้ไมโครไลบรารีของ JS ทำไมไม่ Angular, Ember ฯลฯ?

ฉันเลือกไมโครไลบรารีเนื่องจากข้อกำหนดในการเรนเดอร์แอปพลิเคชันเพลงแบบคงที่โดยทั่วไปนั้นค่อนข้างเรียบง่าย และฉันต้องการหลีกเลี่ยงการพึ่งพาเฟรมเวิร์ก Single-Page-Application (SPA) ของบุคคลที่สาม นอกจากนี้ เนื่องจากฉันใช้ไมโครไลบรารี จึงทำให้ง่ายต่อการเลือกสิ่งที่คุณต้องการ ตัวอย่างเช่น หากคุณไม่ชอบระบบเทมเพลต การกำหนดเส้นทาง หรือไลบรารีการรวมสองทางที่ฉันเลือก คุณสามารถแทนที่ด้วยไลบรารี/เฟรมเวิร์ก JS ที่คุณต้องการได้

ไมโคร-ไลบรารี

• Navigo.js - เราเตอร์
• Bind.js - การเชื่อมโยงสองทาง
• Marked.js - ตัวแยกวิเคราะห์ markdown
• Micromustache.js - การใช้งานย่อยของเอ็นจิ้นเทมเพลต {{mustache}}
• Soundmanager2.js - เอ็นจิ้นเสียงข้ามแพลตฟอร์ม
• Pushtape-player.js - เครื่องเล่นหน้าเสียง JS ที่ปรับแต่งได้พร้อมการควบคุมทั่วโลก
• Bootstrap ตารางเท่านั้น