@midwayjs/view 3.0.0-beta.9 → 3.0.0

package/README.md

@@ -1,11 +1,227 @@
 # midway-view
 
-[![Package Quality](http://npm.packagequality.com/shield/@midwayjs/view.svg)](http://packagequality.com/#?package=@midwayjs/view)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/midwayjs/midway/pulls)
+Base view component for midway.
 
-this is a sub package for midway.
+## Install
+
+@midwayjs/view don't have build-in view engine, So you should choose a template engine like ejs, and install `@midwayjs/view-ejs`.
+View component will be auto install and enable by import `view-ejs`.
+
+```bash
+$ npm i @midwayjs/view-ejs --save
+```
+
+## Usage
+
+First, import component in `src/configuration.ts`.
+
+```typescript
+import { Configuration } from '@midwayjs/decorator';
+import * as view from '@midwayjs/view-ejs';
+import { join } from 'path'
+
+@Configuration({
+  imports: [
+    // ...
+    view
+  ],
+  importConfigs: [
+    join(__dirname, 'config')
+  ]
+})
+export class ContainerLifeCycle {
+}
+```
+
+Configure the mapping, the file with `.ejs` extension will be rendered by ejs.
+
+```typescript
+// src/config/config.default.ts
+export const view = {
+  defaultViewEngine: 'ejs',
+  mapping: {
+    '.ejs': 'ejs',
+  },
+};
+
+// ejs config
+export const ejs = {};
+```
+
+In controller, you can call `ctx.render`.
+
+```typescript
+import { Inject, Provide } from '@midwayjs/decorator';
+import { Context } from '@midwayjs/koa';
+
+@Controller('/')
+export class HomeController {
+
+  @Inject()
+  ctx: Context;
+
+  @Get('/')
+  async render(){
+    await this.ctx.render('hello.ejs', {
+      data: 'world',
+    });
+  }
+}
+```
+
+## Use multiple view engine
+
+@midwayjs/view support multiple view engine, so you can use more than one template engine in one application.
+
+If you want add another template engine like nunjucks, then you can add @midwayjs/view-nunjucks component.
+
+Configure the plugin and mapping
+
+```typescript
+// src/config/config.default.ts
+export const view = {
+  mapping: {
+    '.ejs': 'ejs',
+    '.nj': 'nunjucks',
+  },
+};
+```
+You can simply render the file with .nj extension.
+
+```typescript
+await this.ctx.render('user.nj');
+```
+
+## Write a view engine
+
+Create a view engine class first, and implement render and renderString, if the template engine don't support, just throw an error.
+
+```typescript
+// lib/view.ts
+import { Provide } from '@midwayjs/decorator';
+
+@Provide()
+export class MyView {
+
+  @Config('xxxx')
+  viewConfig;
+
+  async render(fullpath, locals) {
+    return myengine.render(fullpath, locals);
+  }
+
+  async renderString() { throw new Error('not implement'); }
+};
+```
+
+These methods receive three arguments, `renderString` will pass tpl as the first argument instead of name in `render`.
+
+`render(name, locals, viewOptions)`
+
+- name: the file path that can resolve from root (`/view` by default)
+- locals: data used by template
+- viewOptions: the view options for each render, it can override the view default config in `config/config.default.js`. Plugin should implement it if it has config.
+  When you implement view engine, you will receive this options from `render`, the options contain:
+  - root: it will resolve the name to full path, but seperating root and name in viewOptions.
+  - name: the original name when call render
+  - locals: the original locals when call render
+
+`renderString(tpl, locals, viewOptions)`
+
+- tpl: the template string instead of the file, using in `renderString`
+- locals: same as `render`
+- viewOptions: same as `render`
+
+### Register
+
+After define a view engine, you can register it.
+
+```typescript
+// src/configuration.ts
+import { Configuration, Inject, Provide } from '@midwayjs/decorator';
+import * as koa from '@midwayjs/koa';
+import * as view from '@midwayjs/view';
+import { MyView } from './lib/my';
+
+@Configuration({
+  imports: [koa, view],
+  importConfigs: [join(__dirname, 'config')]
+})
+export class AutoConfiguration {
+
+  @Inject()
+  viewManager: view.ViewManager;
+
+  async onReady(){
+    this.viewManager.use('ejs', MyView);
+  }
+}
+
+```
+
+You can define a view engine name, normally it's a template name.
+
+## Configuration
+
+### Root
+
+Root is `${appDir}/view` by default, but you can define multiple directory.
+
+```typescript
+export default appInfo => {
+  const appDir = appInfo.appDir;
+  return {
+    view: {
+      rootDir: {
+        default: `${appDir}/view`,
+        anotherDir: `${appDir}/view2`
+      }
+    }
+  }
+}
+```
+
+### defaultExtension
+
+When render a file, you should specify a extension that let @midway/view know which engine you want to use. However you can define `defaultExtension` without write the extension.
+
+```typescript
+// src/config/config.default.ts
+export const view = {
+  defaultExtension: '.html',
+};
+
+// controller
+import { Inject, Provide } from '@midwayjs/decorator';
+import { Context } from '@midwayjs/koa';
+
+@Controller('/')
+export class HomeController {
+
+  @Inject()
+  ctx: Context;
+
+  @Get('/')
+  async render(){
+    // render user.html
+    await this.ctx.render('user');
+  }
+}
+```
+
+### viewEngine and defaultViewEngine
+
+If you are using `renderString`, you should specify viewEngine in view config, see example above.
+
+However, you can define `defaultViewEngine` without set each time.
+
+```js
+// config/config.default.js
+export const view = {
+  defaultViewEngine: 'ejs',
+};
+```
 
-Document: [https://midwayjs.org](https://midwayjs.org)
 
 ## License
 

package/dist/config/config.default.d.ts

@@ -1,3 +1,22 @@
-declare const _default: (appInfo: any) => any;
+declare const _default: (appInfo: any) => {
+    /**
+     * view default config
+     * @member Config#view
+     * @property {String} [rootDir=${appDir}/view] - give a path to find the file, object.values() got array and find for view file
+     * @property {Boolean} [cache=true] - whether cache the file's path
+     * @property {String} [defaultExtension] - defaultExtension can be added automatically when there is no extension  when call `ctx.render`
+     * @property {String} [defaultViewEngine] - set the default view engine if you don't want specify the viewEngine every request.
+     * @property {Object} mapping - map the file extension to view engine, such as `{ '.ejs': 'ejs' }`
+     */
+    view: {
+        cache: boolean;
+        defaultExtension: string;
+        defaultViewEngine: string;
+        mapping: {};
+        rootDir: {
+            default: string;
+        };
+    };
+};
 export default _default;
 //# sourceMappingURL=config.default.d.ts.map

package/dist/config/config.default.js

@@ -1,13 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const path_1 = require("path");
-const extend = require("extend2");
-exports.default = appInfo => {
-    const originConfig = require('egg-view/config/config.default')(appInfo);
-    return extend(true, originConfig, {
-        view: {
-            root: (0, path_1.join)(appInfo.appDir, 'view'),
+exports.default = appInfo => ({
+    /**
+     * view default config
+     * @member Config#view
+     * @property {String} [rootDir=${appDir}/view] - give a path to find the file, object.values() got array and find for view file
+     * @property {Boolean} [cache=true] - whether cache the file's path
+     * @property {String} [defaultExtension] - defaultExtension can be added automatically when there is no extension  when call `ctx.render`
+     * @property {String} [defaultViewEngine] - set the default view engine if you don't want specify the viewEngine every request.
+     * @property {Object} mapping - map the file extension to view engine, such as `{ '.ejs': 'ejs' }`
+     */
+    view: {
+        cache: true,
+        defaultExtension: '.html',
+        defaultViewEngine: '',
+        mapping: {},
+        rootDir: {
+            default: (0, path_1.join)(appInfo.appDir, 'view'),
         },
-    });
-};
+    },
+});
 //# sourceMappingURL=config.default.js.map

package/dist/config/config.local.d.ts

@@ -1,3 +1,4 @@
-declare const _default: any;
-export default _default;
+export declare const view: {
+    cache: boolean;
+};
 //# sourceMappingURL=config.local.d.ts.map

package/dist/config/config.local.js

@@ -1,4 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = require('egg-view/config/config.local');
+exports.view = void 0;
+exports.view = {
+    cache: false,
+};
 //# sourceMappingURL=config.local.js.map

package/dist/configuration.d.ts

@@ -1,5 +1,6 @@
+import { MidwayApplicationManager } from '@midwayjs/core';
 export declare class ViewConfiguration {
-    app: any;
+    applicationManager: MidwayApplicationManager;
     onReady(container: any): Promise<void>;
 }
 //# sourceMappingURL=configuration.d.ts.map

package/dist/configuration.js

@@ -11,28 +11,58 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ViewConfiguration = void 0;
 const decorator_1 = require("@midwayjs/decorator");
-const mw_util_1 = require("@midwayjs/mw-util");
 const DefaultConfig = require("./config/config.default");
 const LocalConfig = require("./config/config.local");
 const viewManager_1 = require("./viewManager");
+const core_1 = require("@midwayjs/core");
+const contextView_1 = require("./contextView");
 let ViewConfiguration = class ViewConfiguration {
     async onReady(container) {
-        if (!this.app.config) {
-            this.app.config = this.app.getConfig();
-        }
-        (0, mw_util_1.completeAssign)(this.app.context, require('egg-view/app/extend/context'));
-        this.app.view = await container.getAsync(viewManager_1.ViewManager);
-        if (!this.app.toAsyncFunction) {
-            this.app.toAsyncFunction = method => {
-                return method;
-            };
-        }
+        this.applicationManager
+            .getApplications(['koa', 'egg', 'faas'])
+            .forEach((app) => {
+            Object.defineProperties(app.context, {
+                /**
+                 * Render a file, then set to body, the parameter is same as {@link @ContextView#render}
+                 * @return {Promise} result
+                 */
+                render: {
+                    value: async function (...args) {
+                        const contextView = await this.requestContext.getAsync(contextView_1.ContextView);
+                        return contextView.render(...args).then(body => {
+                            this.body = body;
+                        });
+                    },
+                },
+                /**
+                 * Render a file, same as {@link @ContextView#render}
+                 * @return {Promise} result
+                 */
+                renderView: {
+                    value: async function (...args) {
+                        const contextView = await this.requestContext.getAsync(contextView_1.ContextView);
+                        return contextView.render(...args);
+                    },
+                },
+                /**
+                 * Render template string, same as {@link @ContextView#renderString}
+                 * @return {Promise} result
+                 */
+                renderString: {
+                    value: async function (...args) {
+                        const contextView = await this.requestContext.getAsync(contextView_1.ContextView);
+                        return contextView.renderString(...args);
+                    },
+                },
+            });
+        });
+        await container.getAsync(viewManager_1.ViewManager);
     }
 };
 __decorate([
-    (0, decorator_1.App)(),
-    __metadata("design:type", Object)
-], ViewConfiguration.prototype, "app", void 0);
+    (0, decorator_1.Inject)(),
+    __metadata("design:type", core_1.MidwayApplicationManager)
+], ViewConfiguration.prototype, "applicationManager", void 0);
 ViewConfiguration = __decorate([
     (0, decorator_1.Configuration)({
         namespace: 'view',

package/dist/contextView.d.ts

@@ -0,0 +1,18 @@
+import { ViewManager } from './viewManager';
+import { IViewEngine, RenderOptions } from './interface';
+/**
+ * View instance for each request.
+ *
+ * It will find the view engine, and render it.
+ * The view engine should be registered in {@link ViewManager}.
+ */
+export declare class ContextView implements IViewEngine {
+    viewManager: ViewManager;
+    viewConfig: any;
+    ctx: any;
+    render(name: string, locals?: Record<string, any>, options?: RenderOptions): Promise<string>;
+    renderString(tpl: string, locals?: Record<string, any>, options?: RenderOptions): Promise<string>;
+    private getViewEngine;
+    private setLocals;
+}
+//# sourceMappingURL=contextView.d.ts.map

package/dist/contextView.js

@@ -0,0 +1,94 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextView = void 0;
+const viewManager_1 = require("./viewManager");
+const decorator_1 = require("@midwayjs/decorator");
+const assert = require("assert");
+const path_1 = require("path");
+/**
+ * View instance for each request.
+ *
+ * It will find the view engine, and render it.
+ * The view engine should be registered in {@link ViewManager}.
+ */
+let ContextView = class ContextView {
+    async render(name, locals, options) {
+        // retrieve fullpath matching name from `config.root`
+        const filename = await this.viewManager.resolve(name);
+        options = options !== null && options !== void 0 ? options : {};
+        options.name = name;
+        options.root = filename.replace((0, path_1.normalize)(name), '').replace(/[/\\]$/, '');
+        options.locals = locals;
+        // get the name of view engine,
+        // if viewEngine is specified in options, don't match extension
+        let viewEngineName = options.viewEngine;
+        if (!viewEngineName) {
+            const ext = (0, path_1.extname)(filename);
+            viewEngineName = this.viewManager.extMap.get(ext);
+        }
+        // use the default view engine that is configured if no matching above
+        if (!viewEngineName) {
+            viewEngineName = this.viewConfig.defaultViewEngine;
+        }
+        assert(viewEngineName, `Can't find viewEngine for ${filename}`);
+        // get view engine and render
+        const view = await this.getViewEngine(viewEngineName);
+        return await view.render(filename, this.setLocals(locals), options);
+    }
+    async renderString(tpl, locals, options) {
+        var _a;
+        options = options !== null && options !== void 0 ? options : {};
+        const viewEngineName = (_a = options.viewEngine) !== null && _a !== void 0 ? _a : this.viewConfig.defaultViewEngine;
+        assert(viewEngineName, "Can't find viewEngine");
+        // get view engine and render
+        const view = await this.getViewEngine(viewEngineName);
+        return await view.renderString(tpl, this.setLocals(locals), options);
+    }
+    async getViewEngine(name) {
+        // get view engine
+        const ViewEngine = this.viewManager.get(name);
+        assert(ViewEngine, `Can't find ViewEngine "${name}"`);
+        // use view engine to render
+        const engine = await this.ctx.requestContext.getAsync(ViewEngine);
+        // wrap render and renderString to support both async function and generator function
+        if (engine.render) {
+            engine.render = decorator_1.Utils.toAsyncFunction(engine.render);
+        }
+        if (engine.renderString) {
+            engine.renderString = decorator_1.Utils.toAsyncFunction(engine.renderString);
+        }
+        return engine;
+    }
+    setLocals(locals) {
+        return Object.assign({
+            ctx: this.ctx,
+            request: this.ctx.request,
+        }, this.ctx.locals, locals);
+    }
+};
+__decorate([
+    (0, decorator_1.Inject)(),
+    __metadata("design:type", viewManager_1.ViewManager)
+], ContextView.prototype, "viewManager", void 0);
+__decorate([
+    (0, decorator_1.Config)('view'),
+    __metadata("design:type", Object)
+], ContextView.prototype, "viewConfig", void 0);
+__decorate([
+    (0, decorator_1.Inject)(),
+    __metadata("design:type", Object)
+], ContextView.prototype, "ctx", void 0);
+ContextView = __decorate([
+    (0, decorator_1.Provide)()
+], ContextView);
+exports.ContextView = ContextView;
+//# sourceMappingURL=contextView.js.map

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { ViewConfiguration as Configuration } from './configuration';
+export * from './interface';
+export * from './contextView';
 export * from './viewManager';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -13,5 +13,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Configuration = void 0;
 var configuration_1 = require("./configuration");
 Object.defineProperty(exports, "Configuration", { enumerable: true, get: function () { return configuration_1.ViewConfiguration; } });
+__exportStar(require("./interface"), exports);
+__exportStar(require("./contextView"), exports);
 __exportStar(require("./viewManager"), exports);
 //# sourceMappingURL=index.js.map

package/dist/interface.d.ts

@@ -0,0 +1,25 @@
+export interface RenderOptions {
+    name?: string;
+    root?: string;
+    locals?: Record<string, any>;
+    viewEngine?: string;
+}
+export interface IViewEngine {
+    /**
+     * Render a file by view engine, then set to body
+     * @param {String} name - the file path based on root
+     * @param {Object} [locals] - data used by template
+     * @param {Object} [options] - view options, you can use `options.viewEngine` to specify view engine
+     * @return {Promise<String>} result - return a promise with a render result
+     */
+    render(name: string, locals?: Record<string, any>, options?: RenderOptions): Promise<string>;
+    /**
+     * Render a template string by view engine
+     * @param {String} tpl - template string
+     * @param {Object} [locals] - data used by template
+     * @param {Object} [options] - view options, you can use `options.viewEngine` to specify view engine
+     * @return {Promise<String>} result - return a promise with a render result
+     */
+    renderString(tpl: string, locals?: Record<string, any>, options?: RenderOptions): Promise<string>;
+}
+//# sourceMappingURL=interface.d.ts.map

package/dist/interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=interface.js.map

package/dist/viewManager.d.ts

@@ -1,9 +1,11 @@
-export declare class ViewManager {
+import { IViewEngine } from './interface';
+export declare class ViewManager extends Map {
     app: any;
-    innerManager: any;
-    get extMap(): any;
-    get config(): any;
-    init(): Promise<void>;
+    viewConfig: any;
+    config: any;
+    extMap: Map<any, any>;
+    fileMap: Map<any, any>;
+    init(): void;
     /**
      * This method can register view engine.
      *
@@ -18,15 +20,14 @@ export declare class ViewManager {
      * @param {String} name - the name of view engine
      * @param {Object} viewEngine - the class of view engine
      */
-    use(name: string, viewEngine: any): void;
+    use(name: string, viewEngine: new (...args: any[]) => IViewEngine): void;
     /**
      * Resolve the path based on the given name,
-     * if the name is `user.html` and root is `app/view` (by default),
-     * it will return `app/view/user.html`
+     * if the name is `user.html` and root is `view` (by default),
+     * it will return `view/user.html`
      * @param {String} name - the given path name, it's relative to config.root
      * @return {String} filename - the full path
      */
     resolve(name: string): Promise<string>;
-    get(key: any): any;
 }
 //# sourceMappingURL=viewManager.d.ts.map