The apostrophe-workflow module adds powerful workflow and localization capabilities to Apostrophe. As a workflow system it provides for a draft version of every document, so that changes do not immediately "go live." As a localization system it provides for documents to exist in several locales, allowing for easy internationalization.
We'll begin with the steps needed simply to add workflow to your project. Then we'll examine the changes needed for localization (also known as i18n or internationalization).
Then configure the apostrophe-workflow module in app.js with the rest of your modules. We'll start with a simple configuration just providing workflow. We will also turn on the very handy "Manage Workflow" dialog box by turning on the apostrophe-workflow-modified-documents module, which comes bundled inside apostrophe-workflow. You do not have to separately install it.
'apostrophe-workflow': {
// IMPORTANT: if you follow the examples below,
// be sure to set this so the templates work
alias: 'workflow',
// Recommended to save database space. You can still
// export explicitly between locales
replicateAcrossLocales: false
},
'apostrophe-workflow-modified-documents': {}
Turning off automatic replication across locales
For historical reasons, in the default configuration, documents automatically replicate between
locales (languages), starting out in the trash in other locales until they are made active there.
Our own clients have found this wastes a lot of database space. So, set replicateAcrossLocales: false
as shown above. Users can still export documents between locales as you'll see later on.
If you find this useful but need to occasionally make an exception and just completely copy a locale to another once, you can use the apostrophe-workflow:replicate-locale command line task, with --from and --to options, to do that on a one-time basis. If you have already done work in the to locale, we recommend running apostrophe-attachments:recompute-all-doc-references afterwards, to ensure attachments do not lose track of whether it is time to disable access.
Did you already start a large project with replicated documents? You can use the apostrophe-workflow:dereplicate command line task to remove documents from all other locales if they are outside the trash in only one locale. We recommend backing up your database first.
Adding parkedId to your parked pages
If you are using the park option with apostrophe-pages, and you have not already set a unique parkedId property for each page specified for that option, do so before you start using workflow. This will address problems that otherwise occur if slugs change due to locale prefixes.
Adding workflow to your database
Odds are, you already have a database. Either from an existing project, or for a new one, since Apostrophe creates the database on the very first run. So, follow these steps to add workflow to your database.
For existing projects, we recommend backing up your database first, to make it easier to change your mind. However, there is an apostrophe-workflow:remove task available if you choose to remove workflow later.
You should initially experiment with this module with a local copy of your site, not your live production content.
You can back up your database easily with the mongodump command line utility.
Once you add this module and restart your apostrophe process, all of your documents will exist in both draft and live versions. Editors will be able to the draft version while in "draft" mode. Everyone else, and editors in "live" mode, will see the live version and will not be able to edit it directly. The only way to make new content live is to "commit" the changes that have been made to the document.
If you have not added an admin user yet, you can do it now in the usual way:
# If you do not have preconfigured groups, add a group too
node app apostrophe-groups:add admin admin
# Now add the user
node app apostrophe-users:add admin admin
FOR EXISTING PROJECTS, YOU MUST ADD LOCALES TO EXISTING DOCUMENTS. This is NOT automatic for existing projects, you must run this task on a one-time basis:
This basic configuration provides you with a live/draft toggle on the page (lower left corner). Editing is not possible in the live mode. You will not see most types of pieces in the admin bar, and you will not see editing controls on the page. This is normal.
In the draft mode, editing works in a familiar way. Your changes are constantly saved, just like before, but they are only saved to the draft version of the document.
When you are satisfied, click "submit" to submit your work for review by someone else, or "commit" to commit it to the live version of the page yourself.
If work is submitted that you have permission to edit, you can view a list of those pages and pieces via the "Workflow" admin bar menu.
"Why am I asked to commit so many things?"
When you click "Commit" on the page, all of the documents that make up what you see on the page need to be committed in order to go live on the site. That includes the images in a slideshow, the blog posts in a blog widget, and so on. It may seem like a lot of work the first time. Just remember that you won't be asked to commit them again unless their drafts have been updated.
You can commit documents in bulk, too. The easiest way is via the "Manage Workflow" dialog box, accessed via the "Manage" option on the "Workflow" dropdown menu. If you don't see it, switch to draft mode first. If you still don't see it, make sure you enabled the apostrophe-workflow-modified-documents module as noted above in the installation instructions. Once you have access to this dialog box, you can use the "Select All" checkbox and the "Batch Commit" operation to expedite things.
Workflow for pieces
"Pieces," like blog posts or events, work just like before. However, just make sure you enter "draft" mode; until you do that most piece types won't show up on the admin bar, because you can only edit the draft version directly.
When you are finished editing a piece, use the "workflow" menu in the upper right corner of the dialog box to select "submit" or "commit."
Workflow for page settings
Workflow also applies to page settings, such as the title. You can easily toggle between displaying the draft and live versions of the title while in the page settings dialog box. And, you can submit or commit via the workflow dropdown menu in the upper right corner of the dialog box.
Using the localization feature
To enable localization, configure more than one locale in app.js:
'apostrophe-workflow': {
locales: [
{
name: 'default',
label: 'Default',
private: true,
children: [
{
name: 'en-gb',
label: 'England'
},
{
name: 'en-us',
label: 'United States'
},
{
name: 'fr',
label: 'France'
}
]
},
],
defaultLocale: 'en-gb',
// IMPORTANT: if you follow the examples below,
// be sure to set this
alias: 'workflow'
}
If you have worked with localization before you will recognize locale names like en-gb. These are arbitrary; you may choose any name. However, if you plan to use URL prefixes to distinguish between locales (see below), you must choose a hyphenated, lower-case name without punctuation. So we suggest that you always do that.
Private locales and default locale
What about the default locale? What does private do? Private locales cannot actually be accessed by the public. Although it isn't mandatory, we recommend setting up a private default locale for the "master copy" of your content, written in your team's most familiar language, and then exporting content to child locales.
If you use private locales, you must give the "view private locales" permission to any Apostrophe groups that should be able to see those locales when logged in. This is a simple permission that can be granted to a group via the "Groups" option on the admin bar or, if you are using hardcoded groups, via the "groups" option to the apostrophe-users module (the latter requires a restart to push the new permission). If you're using workflow, it's probably a good idea to comment out the groups option, which allows you to manage your groups through Apostrophe's interface instead.
Note that if you do not have a locale named default, you must set the defaultLocale option to the name of a locale you do have. If the default locale is private, a public locale should be set as defaultLocale instead (e.g., 'en-gb' above). Also note that if you started out with no locales for simple workflow, Apostrophe already created a default locale implicitly. Leaving that out of your locale configuration would give you no way to access the existing content.
The parent-child relationship between locales is just a convenience for quickly exporting content to them, as you'll see below. You can nest children as many levels deep as you wish.
Document structure for locales
When you restart your Apostrophe node process or run a command line task such as `apostrophe-migrations:migrate, Apostrophe will automatically add the new locales to all of the existing docs in the database.
You may also do this explicitly:
node app apostrophe-workflow:add-missing-locales
By default, docs copied to new locales via this task will be considered trash in all live locales, until an editor chooses to commit them. If you prefer that that they be immediately live everywhere, use this command instead:
Now access the site as an administrator. You will be able to click on the current locale name to switch to other locales.
Every document automatically exists in all locales, however it may or may not be published or in the trash in any given locale. This is useful since it allows you to have pages that are "only for France," for instance.
Note that a single document may have a different slug in different locales. The slugs may also be the same, but you'll typically want to enable locale-specific prefixes, locale-specific domain names or a combination of the two as described below.
Setting the lang attribute
Multilingual websites should set the lang attribute of the html element appropriately.
Apostrophe currently ships with an outerLayoutBase template that includes a locale block,
which can be used to easily override the lang attribute of the page. And this module ships with a
helper function to set lang for you.
So just write this in your
lib/modules/apostrophe-templates/views/layout.html template, or outerLayout.html if you have one:
By default, this helper converts a string like en-gb to en, and leaves a string like fr alone.
If this is not sufficient for your needs, you may set the lang property when configuring each
locale, and that value will be output directly.
Tags and localization: we recommend using joins instead
Tags in Apostrophe follow the typical MongoDB approach of a simple array property containing strings. They are localized like other fields. Thus if they are used to select content for display it is important to be consistent when translating tags to a particular locale.
When working with localization it may be preferable to avoid tags in favor of joins. A joinByOne or joinByArray relationship can be used to relate a document to various "categories," which are localized documents in their own right and therefore behave consistently across locales. apostrophe-workflow will ensure that exported joins referencing a category in one locale are correctly adjusted to point to the equivalent category in the other locale.
Building a locale picker on the front end
Here's how to code a locale picker on the front end:
{# Typically in `layout.html` #}
<ul>
{% for localization in apos.workflow.localizations() %}
<li><a href="{{ localization._url | build({ workflowLocale: localization.workflowLocale }) }}">{{ localization.label }}</a></li>
{% endfor %}
</ul>
This ul will populate with localized links to the current context page or piece. If the page or piece is unpublished or considered trash in a locale, there won't be a link for that locale.
If you use localization.label as shown here, you'll see the labels that you set when configuring your locales.
If you use localization.title instead, you'll see the title of the individual piece or page as it was translated or localized for that locale. The former is usually less confusing.
May be omitted if you are using the subdomains feature or the prefixes feature. If you are using neither, then a query parameter is necessary as the slugs could be the same across locales. However the query parameter is automatically removed after the new locale is stored in the user's session.
Exporting between locales
After committing a change, you will be invited to export that change to other locales. If you do so, it is applied as a "patch" to the other locale's draft (it is not made live right away).
This allows for editors fluent in the other locale to complete any necessary translation tasks before finally committing the changes for that locale.
If you find this option appears too frequently
Do you export rarely? If so, you may want to set the exportAfterCommit option of the apostrophe-workflow module to false, or set disableExportAfterCommit to true. The latter is useful if you are using the apostrophe-override-options module to creaqte an editable boolean field for this purpose.
If you do so, the "export" dialog box will not appear right after every commit. Instead the user must choose to access it. The option can be found on the "workflow" dropdown menu, accessed via "Page Settings" or via the editing dialog box for any piece type, including "global."
Not all patches can be exported
If the page has been altered greatly in structure, for example if the rich text widget on a page has been removed and replaced, making it effectively a separate widget altogether, then an edit to that widget will not take effect as a patch. It is a best practice to initially create all content in a "default" locale and then export it to others.
Forcing exports
If you need to, you can force an export of a document so that it is copied directly to the draft version in other locales. To do that, choose "Force Export" from the dialog box for the piece in question, or from the "Page Settings" dialog box for a page.
Even a forced export only alters the draft version of the other locales. Work must still be reviewed and committed there.
Forcing export of one widget
You can also force the export of a single widget. You can do that via the new export button, displayed along with the up and down arrows, edit pencil and trash icon. This will always push that widget to the draft version of the document in other locales, as long as it can be found there.
Switching locales via custom hostnames and/or prefixes
You'll want URLs to be different between locales so that there is no ambiguity when a user shares them.
You can do so by setting the hostnames and/or prefixes options. Notice that these are separate from the main locales array. This is done to make it easier to differentiate the hostnames between development, staging and production environments using a data/local.js file that is present only in the proper environment. Apostrophe merges the contents of that file with your main app.js Apostrophe configuration using _.merge(), which works best with objects and properties.
Notice that a hostname is specified for every locale, and if a hostname is shared by two or more locales, all of those locales must specify prefixes.
There does not have to be any similarity between the hostnames. They can be completely different.
Two or more locales may have the same prefix, as long as they have different hostnames.
Two or more locales may share a hostname, as long as no more than one does not have a prefix. That is, you may have a "fallback" locale for a hostname with no prefix configured, but you can't have more than one.
If one of several locales sharing a hostname has no prefix, you should review the addApiCalls option, to avoid situations where Apostrophe assumes accesses to a private API implemented by your site should count as a switch to the unprefixed locale.
Example
'apostrophe-workflow': {hostnames: {'fr': 'exemple.fr','default': 'example.com','us': 'example.com','us-en': 'example.com','us-es': 'example.com'},prefixes: {'us': '/us','us-en': '/en','us-es': '/es',// We don't need prefixes for fr because// that hostname is not shared with other// locales},locales: [{name: 'default',label: 'Default',private: true,children: [{name: 'fr'},{name: 'us',private: true,children: [{name: 'us-en'},{name: 'us-es'}]}]}],defaultLocale: 'default',// IMPORTANT: if you follow the examples below,// be sure to set thisalias: 'workflow'}
If all of the locales that share a hostname have a prefix, you can still configure one to be the default, in which case an access to the hostname with no prefix will redirect to that locale:
defaultLocalesByHostname: {// 'en-us' and 'en-gb' are both mapped to example.com, with// separate prefixes, but 'en-us' is the default'example.com': 'en-us'}
This will issue a 302 (temporary) direct status code. You can
override that if you wish:
missingPrefixRedirectStatusCode: 301
We recommend doing this only after some experience with your configuration,
as permanent redirects may be cached by browsers for a long time.
Default locales for individual hostnames
In addition to the global defaultLocale option, you can set up a defaultLocalesByHostname object to map hostnames to default locales. This is useful if the host has several prefixes but a request arrives with no prefix. If the global default locale is not the best choice for yourcompany.us, you can map it, for instance, to en-us:
hostnames: {'en-us': 'yourcompany.us','es-us': 'yourcompany.us','default': 'yourcompany.com'// ... and other unrelated hostnames ...},prefixes: {'en-us': '/en','es-us': '/es'},defaultLocalesByHostname: {'yourcompany.us': 'en-us'},defaultLocale: 'default'
Using addApiCalls: when a locale that shares a hostname has no prefix
When one of the locales sharing a hostname has no prefix, Apostrophe needs your help to distinguish between page URLs that should switch to that locale and API calls that should rely on the locale setting already in the user's session.
By default Apostrophe knows that any URL starting with /modules should not change the locale. Neither should /login or /logout, or anything with a file extension, to avoid accidental locale switches due to missing assets.
You can add additional rules like these by passing an array of them as the addApiCalls option to the module:
addApiCalls: [// simple string match'/my/private/api',// minimatch glob match, just one folder level'/my/apis/*',// regular expression/^\/nothing\/past\/here\/.*$/]
Adding prefixes to an existing database
Prefixes are automatically added to page slugs when Apostrophe is restarted or you run a command line task, such as apostrophe-migrations:migrate.
You can also request this explicitly:
node app apostrophe-workflow:add-locale-prefixes
This is a one-time action. Prefixes are automatically added to new pages and when editing the "page settings" of old ones.
If you change or remove the prefix for a locale, the change will take place for existing pages the next time you restart the site or run a task.
The editor may appear to allow removing the prefix from the slug, but it is always restored on save.
If you only care about subdomains
As a convenience, if all of your locales use subdomains which match the name of the locale, you may set subdomains: true and skip the hostnames option.
If you only care about prefixes
Similarly, if all of your locales use prefixes which match the name of the locale, you may set prefixes: true rather than passing an object that spells out the prefixes for each locale.
Of course, if you use the hostnames or subdomains option, your front end proxy must actually be configured to forward traffic for those hostnames.
One login across all hostnames
The workflow module provides single sign-on across all of the hostnames, provided that you use the locale picker provided by Apostrophe's editing interface to switch between them. The user's session cookie is transferred to the other hostname as part of following that link.
Locale-specific stylesheets
Basic support for locale-specific stylesheets is provided. You may, if you wish, specify a stylesheet name for a locale. The primary purpose of such a stylesheet is to define font face imports and other global items, so that the regular LESS CSS build of Apostrophe can then use a consistent font-family setting for all locales but will in fact receive the correct actual font.
You may also define a defaultStylesheet to be pushed to all locales that do not specify a stylesheet. This is useful in cases where a single @font-face or @import declaration will serve for almost all locales, but should be overridden completely for a few specific locales to avoid redundant downloads.
Since we specified stylesheet: 'cn' for the cn locale, the project-level file /lib/modules/apostrophe-workflow/public/css/cn.css will be served to the browser. For all other locales, /lib/modules/apostrophe-workflow/public/sss/default.css will be served, because defaultStylesheet was also set.
It will be delivered via a special Express route and the URL will target that route. The URL will be unique to the current asset generation and locale.
The file will not be part of a minified, CDN-delivered asset bundle. However, site-relative URLs (those beginning with /) will be rewritten to account for Apostrophe's prefix option and/or the use of an asset bundle in a CDN. Other types of relative URLs currently are not supported here. If you need to reference assets in the public folder of a module, use /modules/modulename, prefixing modulename with my- if it is in the project level public folder of an Apostrophe core or npm module.
This file will be pushed via a separate link element in
客服电话
APP下载
官方微信
请发表评论