47pages-keystone 中文文档教程

Question

47Pages Fork

KeystoneJS 的 47Pages 分支是必要的，原因有两个：

• Keystone is still in a stage of relatively unstable development
• The 47Pages site requires additional functionality tailored to its unique needs

也就是说，本地化更改与上游 Keystone 存储库保持同步很重要，因为那里的开发不断改进。 我们希望能够将这些更改拉入我们的分叉分支，同时保持我们生产版本的稳定性并保留为 47Pages 所做的自定义更改。

Branching model

在本地克隆 keystone-47pages 并设置上游来源：

git clone git@github.com:git@github.com:47pages/keystone.git
git remote add upstream git@github.com:JedWatson/keystone.git

要开发，请检查最新的开发分支（例如 47pages-0617-4f48821）。 第一个数字是分支创建的月份和日期，以便于按时间顺序排序。 第二个数字是此分支已根据其重新定位的最新上游提交的短 SHA1 哈希。 在进行更改时将提交添加到此分支。

当您准备好合并到生产分支时，您必须首先针对上游分支变基 47pages-prod！ 这是为了确保我们的更改不会与官方存储库有太大差异。

git checkout master
git pull upstream master
git checkout 47pages-prod
git merge master

解决任何冲突。 检查从上游引入的更改是否一切正常。 请注意，与 47pages 相关的更改仅发生在以 47pages 为前缀的分支中 - 我们的 ma​​ster 应该始终是原始的。

然后，只需将开发分支中的更改合并到生产中即可。 此时应该没有冲突。

git merge 47pages-date-sha1
git push origin 47pages-prod

最后，为未来的变化创建新的开发分支。 如果出现问题，旧的开发分支可以保留下来回滚，但不应在其中进行新的开发。

git checkout master
git rev-parse --short HEAD
git checkout 47pages-prod
git checkout -b 47pages-newdate-newsha1

KeystoneJS 是一个强大的新的 Node.js 内容管理系统和基于 express 和 mongoose 这使得创建复杂的网站和应用程序变得容易，并为您提供了一个漂亮的、自动生成的管理 UI。

要开始，请查看 keystonejs.com！

About

Keystone 为您提供：

• A simple way to create a dynamic web site or app with well-structured routes, templates and models
• A beautiful Admin UI based on the database models you define
• Enhanced models with additional field types and functionality, building on those natively supported by Mongoose
• Out of the box session management and authentication
• An updates framework for managing data updates or initialisation
• Integration with Cloudinary for image uploading, storage and resizing
• Integration with Mandrill for sending emails easily
• Integration with Google Places for clever location fields
• Integration with Embedly for powerful video and rich media embedding tools

... 以及许多其他工具和实用程序，使创建复杂的网络应用程序变得更加容易。

使用我们的 Yeoman Generator 快速启动和运行 KeystoneJS，然后查看我们的入门指南和指南。 文档位于 keystonejs.com/docs/getting-started。

我们在 demo.keystonejs.com 有一个演示网站，您可以在其中试用 Keystone 管理 UI，并且您可以 阅读源代码 了解它是如何构建的。

如果您有想法或问题，请联系 KeystoneJS Google Group 或发送推文至 @KeystoneJS。

SydJS Website

Keystone 的主要贡献者位于澳大利亚悉尼，并且 KeystoneJS 是用 Javascript 编写的，因此使用它为悉尼 Javascript 社区创建一个站点是很自然的。

SydJS 网站 是比 Keystone 演示更复杂的项目的一个很好的例子，您可以 查看源代码 了解它是如何构建的。

我们还使用 Cordova、Backbone、Velocity.js 和 jQuery 编写了一个 SydJS Mobile App 来演示如何使用 Javascript针对 KeystoneJS 后端运行，为移动应用程序创建原生体验。 如需更多信息，包括我们的设计资源，请查看 SydJS Showbag。

如果您经营一个社区小组，请随时复制我们的网站和应用程序并将它们变成您自己的！ 如果您愿意，我们很乐意听取您的意见。

Contributing

KeystoneJS 有远大的愿景，社区的支持是实现它的重要组成部分。

我们乐于听到有关 Keystone 和您使用它的项目的反馈，并且很乐意在 KeystoneJS Google Group 上提供建议 如果你卡住了。

如果可以，请通过报告问题、讨论想法或提交包含补丁和新功能的拉取请求来做出贡献。 我们尽最大努力在一两天内响应所有问题和拉取请求，并定期向 npm 发布补丁。

如果您要贡献代码，请尝试模仿现有的代码标准 - 我们非常严格地遵循 AirBNB 的 Javascript 风格指南，使用制表符缩进的例外。

Documentation

Keystone 文档在线托管在 keystonejs.com。 如果您处于离线状态，或者想要贡献文档并预览您的更改，您可以通过在 ./docs 文件夹中运行 node docs 在本地提供它们（您将还必须先运行 npm install。这将在端口 8080 上启动文档站点。

Usage

查看 KeystoneJS 文档< /a> 了解如何使用 KeystoneJS。

Installation

开始使用 Keystone 最简单的方法是使用 Yeoman 生成器。

要安装它，请在终端中键入以下内容：

npm install -g yo
npm install -g generator-keystone

然后，创建一个新文件夹对于你的项目，在你的终端中输入以下内容：

yo keystone

这将根据你选择的选项创建一个新项目，并从 npm 安装所需的包。

安装完成后，运行此启动 Keystone 的命令：

node keystone

或者，要在现有项目中包含 Keystone 或从头开始（没有 Yeoman），请在 de 中指定 keystone: "0.2.x" 在您的 package.json 文件中添加 pendencies 数组，然后从您的终端运行 npm install。

然后通读文档和示例项目以了解如何使用它。

Example application script (keystone.js)

在默认模式下运行，Keystone 会处理使用 Express 配置应用程序、连接到 MongoDB 数据库以及启动 Web 服务器所需的一切。

以下是您的 keystone.js（或 app.js 等）文件的示例：

var keystone = require('keystone');

keystone.init({

    'name': 'My Project',
    'brand': 'Project',

    'favicon': 'public/favicon.ico',
    'less': 'public',
    'static': 'public',

    'views': 'templates/views',
    'view engine': 'jade',

    'auth': true,
    'user model': 'User',
    'cookie secret': '--- your secret ---',

    'auto update': true,

    'emails': 'templates/emails',
    'mandrill api key': '--- your api key ---',
    'email rules': { find: '/images/', replace: (keystone.get('env') != 'production') ? 'http://localhost:3000/images/' : 'http://www.keystonejs.com/images/email/' },

    'cloudinary config': { cloud_name: '--- your cloud name ---', api_key: '--- your api key ---', api_secret: '--- your api secret ---' }

});

keystone.import('models');

keystone.set('routes', require('./routes'));

keystone.start();

Configuration

配置变量可以在对象中传递给 keystone.init 方法，或者可以在 keystone.start 之前的任何时间设置 使用 keystone.set(key, value) 调用。 这允许更灵活的执行顺序（例如，如果您在您的 路由，您可以在配置列表后设置路由，如上例所示）。

请参阅 KeystoneJS 配置文档，了解可用的详细信息和示例 配置选项。

要了解如何使用这些设置以及 Express 应用程序如何初始化，请参阅 Keystone.prototype.start <代码>/index.js。

Database field types

Keystone 建立在 mongo 提供的基本数据类型之上，允许您轻松添加丰富的、 应用程序模型的功能字段。

您可以在模型上获得辅助方法来轻松处理每种字段类型（例如 格式化日期或数字、调整图像大小、获取可用选项的数组 用于选择字段，或使用 Google 的 Places API 来改进地址）以及一个漂亮的， 用于编辑数据的响应式管理 UI。

有关各种字段类型的详细信息和示例，请参阅 KeystoneJS 数据库文档， 以及如何在您的应用程序中设置和使用数据库模型。

Keystone 的字段类型包括：

• Boolean
• Text
• Textarea
• Email
• Url
• Html
• Color
• Date
• Datetime
• Key
• Number
• Money
• Select
• Markdown
• Name
• Password
• Location
• CloudinaryImage
• CloudinaryImages
• LocalFile
• S3 File
• Embedly

Keystone 还有关系字段，用于管理一对多和多对多 不同模型之间的关系。

Running KeystoneJS in Production

当您将 KeystoneJS 应用程序部署到生产环境时，请务必将您的 ENV 环境变量设置为 production。 您可以通过在 .env 文件中设置 NODE_ENV=production 来完成此操作，该文件由 dotenv。

设置您的环境可以启用某些功能，包括模板缓存、更简单的错误报告和 html 缩小，这些功能在生产中很重要，但在开发中很烦人。

Linking Keystone for Development and Testing

如果你想针对 KeystoneJS 的 master 分支（或针对你自己的分支）进行测试或开发，而不是在 npm 上发布的版本，你只需要检查一下然后使用 npm link 将其链接到您的项目。 在 Mac OS 上，这是这样完成的：

• Checkout KeystoneJS locally, e.g. to ~/Development/KeystoneJS
• From the KeystoneJS directory, run sudo npm link (you will need to enter your system password)
• From your project directory, e.g. ~/Development/MySite (the one with your package.json file in it) run npm link keystone. This will create a link between ~/Development/MySite/node_modules/keystone and ~/Development/KeystoneJS.

然后 require('keystone') 通常在您的应用程序中 - 将使用开发副本。 请注意，运行 npm update 将忽略已发布的新版本的 keystone。

要返回使用来自 npm 的已发布版本的 KeystoneJS，请从您的项目目录运行 npm unlink keystone，然后运行 ​​npm install。

Advanced Usage

也可以将 keystone 集成到现有的 express 应用程序中，而无需使用 start 方法。 这对您的应用程序的假设较少，并提供了很大的灵活性。

在定义任何列表之前，您可以向 Keystone 的 connect 函数提供一个 mongoose 或 express 实例。 connect 返回 this 因此您可以在 require 调用中执行此操作。

keystone.static(app) 将 Keystone 的静态路由处理中间件添加到 Express 应用程序。 最好在应用程序的其他静态资产之后、任何动态逻辑（例如 cookie 解析、会话身份验证、正文解析等）之前执行此操作

keystone.routes(app); 将 Keystone 的动态路由添加到Express 应用路由器。 这可以在您的应用程序的路由定义之前或之后完成，尽管如果它们在之后出现，您可以明确锁定或用您自己的路由替换 Keystone 路由（所以要小心）。

Mounting Keystone as a sub-app or creating a node module out of your Keystone project

您可能还只想将 Keystone 作为一个子应用程序安装在更大的 express 应用程序中，并且仍然让 Keystone 运行其完整的配置和设置例程，但不启动其自己的 http 服务器（即 embedded 模式）。

…或者您可能还想将 Keystone 项目转换为可以通过 npm link 或 npm install 轻松嵌入的节点模块。

下面的详细示例将涵盖创建节点模块以及将 Keystone 应用程序作为子应用程序安装在更大的基于 Express 的应用程序中。

假设你有一个解决方案分解成这样的结构

    /client
    /content
    /server

......其中 /client 是一些超级棒的大型单页客户端应用程序，用 AngularJS 或 Polymer, /server 是一个强大的后端驱动通过 StrongLoop 或其他基于 Express 的东西提供数据，也许是 / 的构建版本client，最后是 /content 是一个 Keystone 应用程序，您只想将其用于出色的 CMS 建模、查询和自动管理界面。 换句话说，您认为 Keystone 擅长内容相关的数据管理和电子邮件内容，但并不真正喜欢它的前端内容（管理应用程序除外）。

在此示例中，所有三个项目都是自己的节点应用程序，具有自己的 package.json 文件。 此示例中的 /content 应用程序可能是您使用 Keystone 的 yeoman 生成器 的结果，然后从 /routes 和 /templates 中删除大部分内容，只使用 /models 和 /updates 以及电子邮件的东西。

然后，您希望将 /content 应用程序作为链接模块集成到 /server 中，并将其作为子应用程序安装在路径 /content。

**您的 /content/keystone.js 文件看起来像这样： **

// Simulate config options from your production environment by
// customising the .env file in your project's root folder.
require('dotenv')().load();

// Require keystone
var keystone = require('keystone');

// Initialise Keystone with your project's configuration.
// See http://keystonejs.com/guide/config for available options
// and documentation.

keystone.init({

    'name': 'Your App Name',
    'brand': 'Your App Name',

    'emails': 'templates/emails',

    'auto update': true,

    'session': true,
    'auth': true,
    'user model': 'User',
    'cookie secret': 'your cookie secret'

});

// Load your project's Models

keystone.import('models');

// Setup common locals for your emails. The following are required by Keystone's
// default email templates, you may remove them if you're using your own.

keystone.set('email locals', {
    logo_src: '/images/logo-email.gif',
    logo_width: 194,
    logo_height: 76,
    theme: {
        email_bg: '#f9f9f9',
        link_color: '#2697de',
        buttons: {
            color: '#fff',
            background_color: '#2697de',
            border_color: '#1a7cb7'
        }
    }
});

// Setup replacement rules for emails, to automate the handling of differences
// between development a production.

// Be sure to update this rule to include your site's actual domain, and add
// other rules your email templates require.

keystone.set('email rules', [{
    find: '/images/',
    replace: (keystone.get('env') == 'production') ? 'http://www.your-server.com/images/' : 'http://localhost:3000/images/'
}, {
    find: '/keystone/',
    replace: (keystone.get('env') == 'production') ? 'http://www.your-server.com/keystone/' : 'http://localhost:3000/keystone/'
}]);

// Load your project's email test routes

keystone.set('email tests', require('./routes/emails'));

// Configure the navigation bar in Keystone's Admin UI

keystone.set('nav', {
    'posts': ['posts', 'post-categories'],
    'galleries': 'galleries',
    'enquiries': 'enquiries',
    'users': 'users'
});

module.exports = keystone;

注意最后一行。 无需通过 keystone.start() 启动 keystone 服务器，您只需导出 keystone 对象即可。 这将使您可以轻松地将此模块嵌入到另一个应用程序中。

您可能还想制作一个与 keystone.js 处于同一级别的 app.js 文件，它所做的只是需要这个导出的对象并启动服务器。 如果您仍然想破解您的模型并以孤立的方式测试它们，这将很有用。

app.js：

var keystone = require('./keystone');

keystone.start();

可嵌入 Keystone 项目的最后一步设置是稍微修改 package.json 文件以包含 main 值。 这是下一步工作所必需的。

package.json：

{
  "name": "your-app-content",
  "version": "0.0.0",
  "private": true,
  "dependencies": {
    "keystone": "~0.2.6",
    "async": "~0.2.9",
    "underscore": "~1.5.2",
    "dotenv": "0.0.3"
  },
  "engines": {
    "node": ">=0.10.22",
    "npm": ">=1.3.14"
  },
  "main": "keystone.js",
  "scripts": {
    "start": "app.js"
  }
}

现在要在开发过程中将 Keystone 项目作为 node_module 嵌入到您的 /server 应用程序中，只需运行 npm link< /code> 来自 /content 项目的根文件夹，然后是 /server 应用根文件夹中的 npm link your-app-content (注意：在执行第二个 npm link 时，将 your-app-content 替换为 /content 应用在其 中的实际名称package.json 文件）。

所有这些工作的下一步是在服务器应用程序中使用 keystone.mount。

/server 中的 app.js 示例：

var express = require('express'),
    app = express();

app.keystone = require('your-app-content');

//...do your normal express setup stuff, add middleware and routes (but not static content or error handling middleware yet)

app.keystone.mount('/content', app, function() {
    //put your app's static content and error handling middleware here and start your server
});

假设您使用端口 3000 来运行上面的示例，您可以然后打开浏览器访问 http://localhost:3000/content/keystone 以访问您的 Keystone 管理界面（由您自己的更高级别的应用程序托管）。

像我们上面那样直接在您的应用程序上引用 keystone 对象意味着您现在可以在您的应用程序中使用来自您的 Keystone 模型的所有强大的查询工具，也许在一些非常安全的 ACL 管理路由或其他类似的有趣东西之后。

最后，如果您正在在您的 Keystone 项目中使用 dotenv 将您的配置存储在 .env 文件中，您还需要创建一个.env 文件位于 /server 项目的根级别。

现在你有了一个功能齐全的可嵌入 KeystoneJS 模块，你可以在后端、前端和内容的开发和测试之间实现良好的关注点分离。

Thanks

KeystoneJS 是一个免费的开源社区驱动项目。 感谢我们的许多贡献者和users 让它变得很棒。

感谢以下公司和项目，我们在 KeystoneJS 的制作过程中使用或从中获得灵感：（

• Node.js
• Thinkmill
• ExpressJS
• MongoDB
• Mongoose
• jQuery
• Underscore
• Bootstrap
• Amazon
• Heroku
• Google
• Cloudinary
• Embedly
• Yusuke Kamiyamane

License

麻省理工学院许可）

版权所有 (c) 2014 Jed Watson

特此免费授予任何获得许可的人 此软件和相关文档文件的副本（ “软件”），不受限制地处理软件，包括 但不限于使用、复制、修改、合并、发布、 分发、再许可和/或出售软件的副本，以及 允许向其提供软件的人这样做，但须遵守 下列条件：

上述版权声明和本许可声明应 包含在软件的所有副本或重要部分中。

本软件按“原样”提供，不提供任何形式的保证， 明示或暗示的，包括但不限于 适销性、特定用途的适用性和非侵权性。 在任何情况下，作者或版权持有人均不对任何 索赔、损害赔偿或其他责任，无论是在合同行为中， 侵权行为或其他由以下原因引起、由其引起或与之相关的行为 软件或软件的使用或其他交易。