# simple-ejs

**Repository Path**: qihexiang/koa-ejs-lite

## Basic Information

- **Project Name**: simple-ejs
- **Description**: EJS模板引擎的简单封装
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2021-01-31
- **Last Updated**: 2021-02-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# simple-ejs

一个简单的 `ejs` 封装，本来设计用于取代 `koa-ejs` 模块，但也可以用在几乎任何框架中。

> 这不是一个非常严谨的项目，如果要用在生产环境中，请务必完全了解其代码后再使用。

## 缘由

`koa-ejs` 模块将配置生成的`render`函数在运行时绑定到Koa框架的`app.context`属性上用于访问，这种方式对于TypeScript支持并不良好（在编译检查时， `ctx.render()` 的类型为 `any` ，其实不然），如果使用了 `koa-router` 之类的路由插件，路由中调用的中间件则无法获知`ctx.render()`的存在，导致编译失败。

除此之外，如果项目中存在多种需要不同配置的EJS的情形， `koa-ejs` 模块也无法提供很好的支持，因为传递选项构建 `ctx.render()` 函数的过程只能进行一次，如果使用原生的 `ejs` 模块，过程又过于复杂，不宜在每个中间件中单独实现。

简而言之，我需要一个能够正确推断出类型、灵活的不需要绑定到 `ctx` 对象上的渲染器。

## 如何使用

安装：

```bash
yarn add simple-ejs
```

示例：

```typescript
import Koa from 'koa'
import Router from 'koa-router'
import { Render } from 'simple-ejs'
import { join } from 'path'

const app = new Koa()
const router = new Router({
    prefix: '/ejs'
})
// 生成渲染器
const ejs = new Render({
    prefix: join(process.cwd(), 'views'),
    extendName: '.ejs'
    rmWhitespace: true,
    cache: true
})

router.get('/:username', async (ctx, next) => {
    const username = ctx.params.username
    const data = {
        title: `hello, ${username}`,
        paragraphs: [
            `This is a page rendered by ejs.`,
            `This page is provided by Koa and koa-ejs-lite.`,
            `Server side info: Node ${process.version} running on ${process.platform}`
        ]
    }
    // 使用渲染器
    ctx.body = await ejs.render('index', data)
})

app.use(router.routes())

export default app
```

## API

- `Render`：可以从模块中直接导出的类，实例化后得到渲染器对象 `ejs`。
    - @param option 扩展自 `ejs`的Option类，增加了两个参数：
        - `prefix: string` EJS文件存放的路径
        - `extendName?: string` 限定EJS文件扩展名，默认值为 `'.ejs'`，若不限定，设置为 `''`
- `ejs`：实例化的 `Render` 对象，包含一个可访问属性，即 `render` 异步函数
    - `render(filename: string, data: Data): Promise<string>` ：
        - @param `filename: string` 输入文件名，可带或不带扩展名，如果扩展名与预先指定的扩展名不一致，实际访问时会被追加上指定的扩展名
        - @param `data: Data`：即 `ejs` 的 `Data` 类，即 `Object` 类实例。

由于最终的 `render` 函数是异步的，所以无论是再Koa还是Express框架中使用时，都必须在异步中间件中进行调用，并且注意错误处理，例如：

```typescript
// Express
app.use('/:page/:username', async (req, res) => {
    const page = req.params.page
    const username = req.params.username
    try {
        const html = await ejs.render(page, { username })
        res.send(html)
    } catch(err) {
        errorLog(err)
        res.sendFile(__dirname + '/static/404.html')
    }
})
```

```typescript
// Koa
app.use(async (ctx,next) => {
    try {
        ctx.body = await ejs.render('index', { status: db.status() })
    } catch(err) {
        errorLog(err)
        ctx.status = 404
        ctx.body = '<h1>404 Not Found</p>'
    }
})
```