Перейти до змісту

API

Загалом відкритий веб-календар можна використовувати без обмежень. Ви можете використовувати цей API, щоб налаштувати календар на льоту.

Цей розділ може бути корисним, якщо застосовується одне з наведеного нижче:

  • Ви веб-розробник, який хоче вставити Open Web Calendar.
  • Ви хочете використовувати повну гнучкість, а не лише те, що відкрито на сторінці конфігурації.
  • Ви хочете використовувати JavaScript для динамічного створення дизайну та параметрів календаря.
  • Ви хочете розширити функціональність відкритого веб-календаря.
  • Ви хочете використовувати відкритий веб-календар як проксі-сервер для запиту подій JSON для вашої власноруч створеної стрічки подій.

Кінцеві точки

Основні параметри однакові в цих кінцевих точках:

  • /index.html - редагувати календар
  • /about.html - переглянути сторінку про
  • /calendar.html - переглянути календар
  • /calendar.spec - завантажити специфікацію
  • /calendar.ics - підписатися на файл ics
  • /calendar.events.json - ГНУЧКИЙ – отримуйте події як JSON. Зауважте, що ви МОЖЕТЕ використовувати це, але не можете бути впевнені, що схема JSON залишиться незмінною. Якщо ви цього хочете, додайте тести.

Для /calendar.events.json необхідні додаткові параметри:

  • timezone=UTC - часовий пояс, у якому потрібно відображати події
  • from=YYYY-MM-DD - початок періоду, в якому відбуваються події (включно)
  • to=YYYY-MM-DD - кінець періоду, в якому відбуваються події (виключно)

Параметри

Усі параметри конфігурації достатньо детально описано в default_specification. Це посилання. наприклад якщо ви знайдете параметр title в default_specification, у вас є кілька варіантів:

Змініть заголовок у параметрі запиту:

/index.html?title=calendar

Змініть назву в специфікації YAML:

title: calendar

Змініть назву в специфікації JSON:

{
  "title": "calendar"
}

Складання специфікації

Ви можете змінити поведінку та вигляд календаря за допомогою параметрів. Якщо один і той самий параметр указано в різних місцях, найвищий пріоритет матиме попереднє місце, указане нижче. Ось місця для визначення параметрів:

Параметри запиту

Усі параметри URL-адреси календаря містяться в специфікації. Параметри запиту мають найвищий пріоритет.

Приклади:

index.html?language=de
calendar.html?title=CALENDAR

specification_url

Якщо вказати цей параметр запиту, конфігурація редактора також завантажується з цієї URL-адреси. Параметри запиту все ще важливіші за те, що написано в цьому файлі. Вихідним форматом може бути YAML або JSON.

Приклади:

calendar.html?specification_url=https://github.com/niccokunzmann/open-web-calendar/raw/master/open_web_calendar/default_specification.yml

open_web_calendar.app.DEFAULT_SPECIFICATION

Це призначено для розробників і внутрішніх Python.

from open_web_calendar.app import DEFAULT_SPECIFICATION
DEFAULT_SPECIFICATION['title'] = 'calendar'

OWC_SPECIFICATION

Це необов’язкова змінна середовища. Будь ласка, прочитайте більше про це в Конфігурації сервера.

default_specification

Цей файл містить параметри за замовчуванням. Вони не повинні бути жорстко закодовані у вихідному коді. Усі параметри перераховані та задокументовані там, тому цей файл можна використовувати для довідки. Не змінюйте цей файл, натомість використовуйте змінну середовища OWC_SPECIFICATION.

Додавання параметрів

Якщо ви додаєте новий параметр як розробник:

  • Додайте параметр із значенням за замовчуванням до default_specification
  • Додайте реалізацію залежно від її використання в app.py або шаблонах файлів JavaScript. Специфікація вже доступна для використання в усіх них.
  • Додайте тести в features/configure-the-calendar.feature, щоб перевірити, чи календар відповідає функції.
  • Додайте тести в features/edit-the-calendar.feature, щоб переконатися, що параметр можна використовувати під час редагування календаря.

Уточнення в Календарі

app.py компілює специфікацію з заданих параметрів у get_specification(). У template ви можете отримати доступ до специфікації через змінну specification. Специфікація доступна для JavaScript як змінна specification.

Дивіться також:

Специфікація на сторінці покажчика

Специфікація за замовчуванням доступна до створення календаря за допомогою JavaScript у змінній configuration.default_specification. Існує функція getSpecification(), яка створює специфікацію з вхідних даних. Загалом слід використовувати змінну specification.

Архітектура

Нижче ви можете знайти зображення архітектури.

архітектура

Основою календаря є специфікація, подана в різних формах. Ця специфікація впливає на всі кроки.

Після того, як специфікація складена, файли календаря (ics) завантажуються з місць в Інтернеті.

З файлів календаря генеруються події.

Потім для відображення подій вибираються різні види.

Зрештою, це призводить до змін HTML і стилю веб-сайту календаря.

У реальній програмі ці кроки трохи переплутані, невпорядковані або опущені, але це просто пояснює основну початкову ідею обробки подій.