sim

Sim - Node.js-фреймворк, предназначенный для быстрой разработки веб-сайтов.

npm install sim
24 downloads in the last week
30 downloads in the last month

Sim Framework

Описание

Sim - Node.js-фреймворк, предназначенный для быстрой разработки веб-сайтов.

Создание проекта

sim <name>

URL

URL-адреса сайта указываются в файле urls.json, расположенном в корневой директории проекта.

Содержимое данного файла представляет собой JSON-объект и может иметь следующее содержимое:

{
    "/": "index",
    "/about/": "main/about",

    "/offer/#{id}/": "shop/offer",
    "/user/${username}/": "profile/user",

    "/secret/": "a>admin/secret",
    "/togoogle/": "->http://google.ru",

    "admin": {
        "/": "index",
        "/about/": "main/about"
    },

    "staff": {
        "/": "index",
        "/about/": "main/about"
    },

    "redirect": {
        "/": "/index/",
        "/about/": "/main/about/"
    },
}

Ключами данного объекта являются URL-строки страницы, значениями — относительные пути к директории страницы от каталога pages.

Каждый путь может начинаться с модификатора. Доступны следующие модификаторы:

  • u>: Делает страницу доступной только для зарегистрированных пользователей. В противном случае перенаправляет на страницу /login/.
  • a>: Делает страницу доступной только для администраторов (пользователей с флагом isAdmin). В противном случае генерирует ошибку 404.
  • s>: Делает страницу доступной только для персонала (пользователей с флагом isStaff). В противном случае генерирует ошибку 404.
  • ->: Перенаправляет запрос на другой URL.

Если значением свойства является объект, данное свойство представляет группу URL. Доступны следующие группы:

  • user: Страницы, доступные только для зарегистрированных пользователей. В противном случае запрос перенаправляется на страницу /login/.
  • admin: URL данной группы представляют страницы, доступные только для пользователей с флагом isAdmin. В противном случае генерируется ошибка 404.
  • staff: Страницы, доступные только для пользователей с флагом isStaff. В противном случае генерируется ошибка 404.
  • redirect: Представляет URL-перенаправления.

Статические страницы

Статическая страница представлена файлом index.html, расположенным в директории страницы. Если в директории страницы присутствуют одновременно файлы index.html и index.jade, предпочтение отдается файлу шаблона (index.jade).

Шаблоны

GET-шаблон страницы представлен файлом index.jade или get.js, расположенным в директории страницы. Если в директории страницы присутствуют одновременно файлы index.html и index.jade, предпочтение отдается файлу шаблона.

POST-шаблон страницы располагается в файле post.jade.

Обработка запросов GET и POST

Обработка запросов GET и POST осуществляется файлами get.ajf и post.ajf, которые находятся в директории страницы и имеют формат AJF. Если для данной страницы отсутствует один из данных файлов (при наличии другого), для отсутствующего типа запроса генерируется ошибка 404.

Каждый обработчик может содержать один или несколько шагов, каждый из которых отделеляется от других пустой строкой. Первый шаг выполняется в области видимости, глобальной для обработчика, то есть все объявленные в первом шаге переменные доступны и для других шагов. Все остальные шаги выполняются в локальной области видимости и изолированы от других шагов.

Внутри обработчика доступны следующие переменные:

  • _: Библиотека "underscore".
  • sim: Объект фреймворка.
  • lists: Объект, содержащий списки базы данных.
  • request: Объект HTTP-запроса.
  • response: Объект HTTP-ответа.
  • user: Объект пользователя.
  • context: Объект контекста шаблона.
  • url: Объект, содержащий параметры URL-запроса.
  • get: Объект, содержащий данные запроса GET.
  • post: Объект, содержащий данные запроса POST.
  • $next(args... || undefined): Значение данной переменной зависит от текущего шага. В последнем шаге данная переменная имеет то же значение, что и $done. Во всех шагах, кроме последнего данная переменная содержит функцию, вызывающую следующий шаг.
  • $render(object || string || undefined): Содержит функцию обратного вызова (callback), которая приводит к рендерингу шаблона в случае передачи в аргументе объекта или вызове без аргументов, или к возвращению ответа в виде строки, если в качестве аргумента передана строка.
  • $done(): Независимо от переданных аргументов вызывает $render без аргументов.
  • redirect(url): Осуществляет перенаправление по URL.

Если шаг начинается со строки вида > name1, name2, ..., nameN, то текущий шаг может принимать аргументы name1, name2, ..., nameN.

Стили

Содержимое стилей страницы включает в себя файл styles.css в директории страницы, а также файлы styles.css всех родительских директорий, вплоть до директории pages.

Скрипты

JavaScript-код страницы находится в файле script.js и имеет формат jb-модуля, то есть может содержать инструкции include('filename.js') и import('filename.js').

Слоты

Слот — это функция, выполняемая на стороне сервера и вызываемая непосредственно из клиентского кода.

Слоты находятся в директории slots каталога проекта. Каждый файл данной директории представляет node.js-модуль, каждая функция которого является слотом.

Слот принимает те же аргументы, что были переданы при вызове слота из клиентского кода (в последнем аргументе обязательно должна передаваться функция обратного вызова).

Создание слота (файл <moduleName.js> директории slots каталога проекта):

exports.<slotName> = function (args..., callback) {
    ...
    callback();
};

Вызов слота:

server.<moduleName>.<slotName>(args..., callback);

База данных

Для долгосрочного хранения данных используется MongoDB. Функциональность реализована в модуле sim.db. Коллекции базы данных представлены объектами списков, каждый из которых представлен файлом директории models каталога проекта.

Получение объекта списка:

var sim = require('sim');

var users = sim.db.lists.users;

Файл списка

Каждый файл списка представляет собой Node.js-модуль, содержащий следующие свойства:

  • name: Имя списка.
  • collectionName: Имя коллекции в базе данных.
  • list: Объект, содержащий методы списка.
  • item: Объект, содержащий методы объекта списка.

Методы модуля

  • connect(callback): Если соединение с базой данных не производилось, устанавливает соединение и передает объект базы данных. Иначе просто вызывает callback.
  • getCollection(name, callback): Получает объект коллекции.
  • setURL(url): Устанавливает URL соединения с базой данных.
  • addList(listName, collectionName, list, item): Добавляет список в модуль.
  • loadFromDir(dirname): Загружает списки из указанной директории и добавляет их в модуль.
  • getLists(): Возвращает объект, свойства которого представляют все списки, имеющиеся в модуле.
  • on(event, handler): Подписка на события базы данных.
    • error(err)
    • info(message)
  • emit(event, args...)

Стандартные методы списка

Каждый созданный список наследует следующие методы:

  • add(obj, callback): Добавляет объект в список.
  • add(arr, callback): Принимает массив объектов и добавляет их в список.
  • remove(obj, callback): Удаляет объект из списка.
  • all(callback): Получает все объекты списка.
  • filter(obj, callback): Находит объекты в списке.
  • empty(callback): Удаляет все объекты из списка.
  • get(obj, callback): Находит один объект, соответствующий переданному объекту.
  • save(obj, callback): Если переданный объект имеет свойство _id или code, существующий объект сохраняется в базе данных. Иначе добавляется новый объект.

Стандартные методы объекта

Каждый объект наследует следующие методы:

  • remove(callback): Удаляет объект из списка.
  • save(callback): Сохраняет объект.

Пользователи и авторизация

Авторизация обеспечивается модулем sim.auth.

Функции модуля

  • createSession(user, callback): Создает сессию для пользователя и возвращает ключ сессии.
  • getUserBySession(sessionKey, callback): Если сессия найдена и пользователь существует, возвращает пользователя, иначе — null.
  • getUser(username, password, callback): Возвращает пользователя, если указанные данные верны. Иначе возвращает null.
  • login(options, callback): Осуществляет вход пользователя. Возвращает объект пользователя или null.
    • username: Имя пользователя.
    • password: Пароль.
    • response: Объект HTTP-ответа.
  • removeSession(sessionKey, callback): Удаляет сессию.
  • logout(response, callback): Осуществляет выход пользователя.
  • auth(request, callback): Возвращает объект авторизованного или анонимного пользователя.

Пользователи

Текущий пользователь может быть аутентифицированным или анонимным. Для аутентифицированных пользователей идентификатором является имя пользователя, указанное при регистрации, для анонимных — IP-адрес машины.

Стандартные поля пользователя:

  • isAuth: Логическое значение, определяющее, аутентифицирован пользователь или нет.
  • isAdmin: Логическое значение, определяющее, является ли пользователь администратором сайта. Для анонимного пользователя всегда false.
  • isStaff: Логическое значения, определяющее, является ли пользователь персоналом сайта. Для анонимного пользователя всегда false.
  • username: Строка, представляющая имя аутентифицированного пользователя, или null для анонимного пользователя.
  • ip: Строка, представляющая ip-адрес анонимного пользователя, или null для аутентифицированного пользователя.
  • password: sha1-строка, представляющая зашифрованный пароль аутентифицированного пользователя, или null для анонимного пользователя.

Стандартные методы пользователя:

  • checkPassword(password): Проверяет пароль пользователя и возвращает true, если переданный пароль совпадает с паролем пользователя.
  • setPassword(password): Устанавливает пароль пользователя.

E-mail

Для отправки e-mail необходимо использовать модуль sim.email.

Методы модуля:

  • config(options): Устанавливает конфигурацию модуля.
    • from: От кого.
    • server: Адрес SMTP-сервера. Если не указано, используется домен из поля from.
    • username: Имя пользователя сервера. Если не указано, используется поле from.
    • password: Пароль сервера.
  • sendText(options, callback): Отправляет текстовый e-mail. В случае ошибки возвращает err, иначе null. Объект options может содержать все свойства, передаваемые методу config, плюс:
    • to: Кому.
    • subject: Тема письма.
    • content: Текстовое содержимое письма.
    • files: Массив абсолютных имен прикрепляемых файлов.
  • sendHTML(options, callback): Отправляет HTML-письмо. Объект options может содержать все свойства, передаваемые методу config, плюс:
    • to: Кому.
    • subject: Тема письма.
    • title: Название письма (краткое описание содержимого).
    • content: HTML-содержимое письма.
    • files: Массив абсолютных имен прикрепляемых файлов.
  • on(eventName, callback):
    • error(err)
    • sended(data)

Cookies

Для взаимодействия с cookies используется модуль sim.cookies.

Методы модуля:

  • set(response, key, value, isLong): Устанавливает cookie. Если последний аргумент - true, cookie устанавливается на неограниченно долгое время, иначе - только на сеанс.
  • get(request, key): Получает значение cookie.
  • remove(response, key): Удаляет значение cookie.
npm loves you