This chapter presents the main concepts and features of Export to Disk publishing, including the approval process as its relates to Export to Disk publishing. When reading this chapter, keep in mind the approval and publishing contexts. While they tend to be discrete — for example, approval templates, pubkeys, and starting points apply to only one context, but not the other—approval and publishing systems depend on each other and therefore interact to some extent.
This chapter contains the following sections:
Compared to mirror publishing, in which dependencies in both the approval and publishing stages are determined by the asset model, Export to Disk publishing is an entirely template-driven process, in both the approval and publishing stages. If the approval template and publishing templates differ with respect to the dependencies they specify—a condition we do not recommend—the likelihood of publishing unapproved content increases.
Coding templates is the responsibility of the developer. However, the WebCenter Sites administrator (and any other users who publish) must understand which templates to invoke and what outcome to expect in order to prevent adverse effects on publishing sessions.
This chapter begins by explaining the most commonly used terms in Export to Disk publishing, then delves into the workings of the approval system. It concludes with a series of examples illustrating how various relationships among assets and templates determine approval and publishing results.
Note:
The terminology presented here refers only to Export to Disk publishing. Terms such as publish key, dependencies, and references, have completely different meanings in mirror publishing and are beyond the scope of this document.This section contains the following topics:
In the Export to Disk publishing context, a page is typically an HTML file that is exported to a disk. (The file is not to be confused with a Page asset type.) Each exported page is represented by a Section 14.1.2, "Publish Key."
A publish key (or pubkey) is strictly a publish-time term. A pubkey represents an atomic publishing unit, which in the case of Export to Disk publishing is an exported file (equivalent to a Section 14.1.1, "Page," not to be confused with a Page asset type).
A pubkey is defined by two constructs: an asset, and a publish-time template (not to be confused with an Section 14.2.1, "Approval Template").
The initial pubkeys in Export to Disk publishing are the Section 14.3.2, "Starting Points," defined by the user who initiates the publishing session. All other pubkeys are discovered and logged during publishing.
A publish queue is a list of pubkeys awaiting publication. For a pubkey to be added to the publish queue, its Section 14.1.4, "Primary Asset" must be approved.
The primary asset participates in the definition of a pubkey. In layman's terms, its ID and type become the cid and c parameters for the template. A primary asset must be approved before its page or pages can be exported.
Note:
If it is determined that a page's primary asset is not approved, the page will not be exported. This can lead to the creation of a broken link on the publishing destination, depending on which approval and publishing templates were used.Ultimately, it is the developer's responsibility to code approval templates such that they can validate the dependencies that are expected to exist on the target destination.
Exporting a page first requires approval of the page's primary asset. Approval of the primary asset is contingent on the approval states of its dependent assets, which are dictated by the primary asset's approval template. The dependent assets' dependencies are further dictated by their own approval templates.
Note:
Because the approval template is not necessarily the one used to render the asset, it is possible to publish assets without passing them through the approval system. This implication and others are discussed and illustrated in Section 14.5, "Behavior and Functionality" and Section 14.6, "Approval and Publish-Time Templates: What Happens When They Differ?"Also note that compositional dependencies (involving non-primary assets of a page, as explained on Section 14.3, "Export to Disk Publishing") need not be approved in order to appear on an exported page (to filter out unapproved assets, see the <render:filter> tag in the Oracle Fusion Middleware WebCenter Sites: Tag Reference for more information).
This section contains the following topics:
The purpose of approval in Export to Disk publishing is to allow the developer to define dependencies in a way as to ensure that the correct content is published and it is published intact.
Compared to mirror publishing, in which asset dependencies in both the approval stage and publishing stage are determined by the asset model, Export to Disk publishing is entirely template-oriented. As a result, approval behavior (as well as publish-time behavior) is very much defined by the developer who writes the approval templates (as well as the publish-time templates). WebCenter Sites then uses the approval template to discover an asset's dependencies. If an asset is published against the approval template, its approval dependencies are likely to be the same as its Section 14.3.3, "Compositional Dependencies."
Approval templates are assigned by use of the Set Default Templates feature in the publishing destination form.
If a default template is not explicitly chosen, the approval system will choose the asset's default template.
If neither the approval nor default template is specified, the asset will be approved without an approval template (i.e., it will have no approval dependencies).
If the approval template is shared among sites, the approval system will choose the site entry corresponding to the current site.
The approval queue handles asset modification events to keep approval tables up to date. For example, if an asset is approved for publication, but you then change it, the approval queue will handle this by unapproving the asset—rejecting it from the publish queue.
You never work directly with the approval queue. The queue runs every five minutes by default. However, if you invoke a feature that uses approval functionality (such as the Publishing tab), the approval queue is forced to run before the screen is rendered to keep approval information up to date.
When you approve an asset, its Section 14.2.1, "Approval Template" is used to determine its approval dependencies. The following tags create approval dependencies:
<asset:load>
<asset:loadall>
<assetset:setasset>
<assetset:setlistedassets>
<render:logdep>
<render:getpageurl>
<render:gettemplateurl>
<render:gettemplateurlparameters>
If you approve asset A whose template (or any element called by the template) references asset B using one of the tags above, an approval dependency is created from A to B. This generally means that when you want to approve A, you must also approve B.
Types of Approval Dependencies
Approval dependencies are created and used at approval-time, not to be confused with publish-time dependencies (even though they can be the same). Approval for Export to Disk publishing involves two types of approval dependencies:
Template dependencies
Reference dependencies
Template dependencies are created when an asset's approval template uses another asset to define the content. For example, if asset A's approval template loads asset B, then A has a template dependency on B. In more practical terms, if you have an approval template for a Page asset that shows an Article asset, the Article asset is used on the Page, so the dependency is of a template kind. The following tags generate template dependencies:
<asset:load>
<asset:loadall>
<assetset:setasset>
<assetset:setlistedassets>
<render:logdep>
Reference dependencies are generated when a link is created from one page to another. They are registered as reference dependencies between the primary assets of the two pages. For example, if we create a hyperlink from the approval template of asset A to a page where asset B is the primary asset, the approval system will register this as asset A's reference dependency on B. Tags that generate this kind of dependency are:
<render:getpageurl>
<render:gettemplateurl>
<render:gettemplateurlparameters>
Template dependencies (in Export to Disk publishing) are by default exact dependencies — if you want to approve A you must approve B if B has been changed. Reference dependencies are always exists dependencies—if you approved and published B once, you are not required to approve it again in order to re-publish A.
The exception is when you set deptype="none" on any of the tags. In that case, no approval dependency at all is created by that tag. This means no record is created for it during approval; in all other contexts, such as Export to Disk publishing and live sites, the deptype attribute is ignored.
Three main components play a role in the Export to Disk publishing process:
The purpose of the publish-time template is to render content as files. Typically, publish-time templates are identical to the approval templates. However, when they differ, content can be published without first being approved. Bypassing the approval system requires the developer to provide a means by which publishable content can be validated.
The starting point is the pubkey (or pubkeys) where export begins, which is at publish-time. Typically, starting points are selected to link to most, if not all the pages on your site. (The page may not necessarily be the home page; for example, it could be a sidebar with many links. The choice is yours.) The Export to Disk publishing system will crawl your site, beginning with the starting points, and will keep logging new pubkeys as it discovers them.
Compositional dependencies are the dependencies of a generated page on the assets that were used to generate that page. They are determined by the logic in that page's Section 14.3.1, "Publish-Time Template." Compositional dependencies dictate what is rendered on the exported page as prescribed by the template, completely ignoring any deptype attributes. The same tags that created template and reference dependencies in the approval template also create compositional dependencies at publish-time. The tags are listed in Section 14.2.3, "Approval Dependencies."
How Do I Select an Approval Template?
The approval template (if specified) is the only template ever used by the approval system to validate a given asset. This template may or may not be used at publish-time, depending on what the starting point is set to. The best advice is to set approval templates that most closely represent the asset's intended dependencies.
What if the template that contains the most representative set of dependencies is not the template that you want to publish the asset with? Set it as the approval template for assets of that type, and use any desired template(s) as starting point(s).
Are Data Model Dependencies Accounted For in Any Way?
Associations, attributes, and so on, are not used in Export to Disk publishing. The only dependencies that matter are those established by templates.
Why Do We Track Publish-Time Compositional Dependencies?
After you export a page, its content is frozen. However, the assets used to generate that page may evolve, making the affected pages obsolete.
Because it records dependencies, WebCenter Sites is able to remind you which pages need updating, assuming you will want to republish those pages. WebCenter Sites gives you two republishing options: automatic refresh and manual refresh.
With automatic refresh, pages are queued automatically for the next publishing session, without your having to approving compositional dependencies that have changed.
If you choose this option, you will not have to approve the modified assets in order for the page to be queued for publishing; in other words, the article page will be republished as soon as you change the image asset. To set up automatic refresh, specify exists or no dependencies between the article and the image; this disables the approval system from prompting you to approve the assets.
With manual refresh, you review the updated pages before publishing them.
If you choose this option, the affected pages will be Held until approved; in other words, you must reapprove the article page every time the image changes. For this to work, you need to set up exact dependencies.
Following is a compilation of simple scenarios which demonstrate Export to Disk publishing behavior:
The participating asset types are Page and HelloArticle (from HelloAssetWorld). The templates are Ttemplate, RTemplate, and dummyTemplate.
For clarity, the asset IDs have been hard-coded into the templates. Normally, assets would be loaded somehow instead of being hard-coded, so developers would need to leverage the deptype='none' attribute in their tags if they do not wish to set up additional dependencies. See Section 14.7, "Sample Templates" for the template code.
Setup: Page P asset uses Ttemplate for both approval and publishing. Ttemplate loads HelloArticle A, therefore establishing a template dependency.
Starting Point: P+Ttemplate
Pubkeys (exported files): P+Ttemplate
Approval Dependencies: Page P has template dependencies on Ttemplate because of <render:logdep>, and on HelloArticle A because of <asset:load>. Because Ttemplate does not create any links, there are no reference dependencies.
Publish Dependencies: Starting Point is the only pubkey; therefore only one file will be exported.
Note that the exported page does not have any publish-time compositional dependencies because it is never actually used by the template. There is only reason why P had to be approved—P is the exported page's primary asset. So, the only compositional dependencies determined at publish-time are the exported page's dependencies on A and Ttemplate.
Table 14-1 Template Dependencies
| Action | Approval Status | Publish Status | Comments |
|---|---|---|---|
|
Initial |
Approved: |
Published: |
|
|
Edit |
|
Not affected by change. |
Since there are no compositional dependencies on |
|
Edit |
|
After approval, page is published again |
Template dependency on |
Setup: Page P asset uses Rtemplate for both approval and publishing. Rtemplate references HelloArticle A, which is in turn rendered by dummyTemplate.
Starting Point: P+Rtemplate
Pubkeys (exported files): P+Rtemplate, A+dummyTemplate
Approval Dependencies: Page P has the routine <render:logdep> template dependency on its Rtemplate. In addition, it establishes a reference dependency on A because of <render:getpageurl> (but not on dummyTemplate, because dependencies between pages are logged only between their primary assets). Note that dummyTemplate does not participate in an approval dependency because it is not referenced by any tags.
Publish Dependencies: The relevant tags are <render:logdep> and <render:getpageurl>. These dictate the publish-time compositional dependencies as Rtemplate and A. As before, note that Page P does not have a compositional dependency because it is not used by any of the templates. When export encounters <render:getpageurl>, it detects that another page is involved, so it creates the A+dummyTemplate pubkey on-the-fly, and runs dummyTemplate to generate its contents. Note that dummyTemplate does not officially have a compositional dependency because it is not used by any tags—it participates only as a pubkey member; so, if dummyTemplate is changed, the approval/publishing cycle will not recognize the change. For this reason, we advise not altering <render:logdep>, which appears on every newly created template.
Table 14-2 Reference Dependencies
| Action | Approval Status | Publish Status | Comments |
|---|---|---|---|
|
Initial |
Approved: |
Published: |
|
|
Edit |
|
Not affected by change. |
Since there are no compositional dependencies on |
|
Edit |
|
|
|
Generally, using the same template for approval and for publishing does not create problems, because approval dependencies match compositional dependencies. Problems start to occur when you use a different template for approval than for publishing. This can happen in several situations. For template code, see Section 14.7, "Sample Templates."
This section contains the following topics:
Asset A uses T1 for approval. T1 does not reference any assets. Asset A uses T2 for publishing. T2 references asset B using <asset:load>. T2 loads asset B, which was never approved, but B will nevertheless be on the exported A+T2 page.
Does this mean you can publish assets that were never approved?
Yes! Some users prefer this, only to avoid approving assets before publishing. Approval can be a taxing operation because exact dependencies cause primary assets to be given Held status if the dependent assets change. As a result, pages of those primary assets cannot be exported. However, a better way to handle such situations is to make good use of the deptype attribute with exists or none values to avoid unwanted approval dependencies.
Now, what happens after asset B is published and then we change B? In this case, there is no approval dependency between asset A and asset B, but there is a compositional dependency. This means that whenever asset B is changed, the affected pages will be automatically re-published. (Because there are no dependencies, the automatic refresh option is chosen). So, A+T2 will be placed in the publish queue automatically as soon as asset B is saved—not approved. For information about republication options, see "Why Do We Track Publish-Time Compositional Dependencies?".
Asset A uses T1 for approval. T1 references asset B using <asset:load> under an exact dependency. Asset A uses T2 for publishing. T2 does not reference asset B.
In this case, there is an approval dependency between asset A and asset B, but there is no compositional dependency. This means that whenever asset B is changed, asset B has to be approved before asset A can be approved, even though the published page does not make any use of asset B.
Asset A uses T1 for approval. T1 does not reference any assets. Asset A uses T2 for publishing. T2 references asset B using <asset:getpageurl>.
In this case, there are no approval dependencies, so A is the only approved asset. During publishing of A+T2, we realize there is another page to be created, with B as primary asset. Now, remember that primary assets must be approved before their page is exported. However, B is not approved, so its page will not be exported. A+T2 is exported, but has a broken link.
Unknown dependencies and Export to Disk publishing. Situations become complicated when you start using <render:unknowndeps>. This tag removes compositional dependencies, and it records unknown dependencies to the pubkey. Assets thus remain in the publish queue permanently (meaning they are refreshed with every publish cycle). This behavior is expected, because if unknown dependencies exist (that is, dependencies may change at any moment, such as query results), the system cannot determine which assets a given asset depends on. To be on the safe side, the system always republishes the assets.
Many exact dependencies. While this is not always avoidable, keep in mind that when a primary asset has exact dependencies on other assets, a change to any of the dependent assets will cause the approval system to change the primary asset's status to Held. The primary asset's page is not publishable unless approved again. If the modified asset is used by many pages, they will all need re-approval. You may consider setting the deptype to exists, and make the dependent pages automatically publishable—but the modified asset must be ready when the publishing session begins.
Note:
The preferred way to customize export URLs (without usingsimplename) is to use PREFERREDFILE and PREFERREDDIR as parameters to <render:getbloburl> and <render:getpageurl> to specify arbitrary names. For example:
<render:getbloburl blobtable='MungoBlobs' blobcol='urldata' blobkey='id' blobwhere='1088466917821' outstr='pagelogoURL' csblobid='1088466917821'> <render:argument name='PREFERREDFILE' value='myBlob.out'/> <render:argument name='PREFERREDDIR' value='myDir'/> </render:getbloburl>
This code exports the blob whose id is 1088466917821 to myDir/myBlob.out.
This section lists the template implementations used in the examples in Section 14.5, "Behavior and Functionality" and Section 14.6, "Approval and Publish-Time Templates: What Happens When They Differ?" Taglib and import definitions have been skipped.
Ttemplate:
<%-- Record dependencies for the Template --%>
<ics:if
condition='<%=ics.GetVar("tid")!=null%>'><ics:then><render:logdep
cid='<%=ics.GetVar("tid")%>' c="Template"/></ics:then></ics:if>
<asset:load name='myArticle' type='HelloArticle'
objectid='1156878442427'/>
Rtemplate:
<%-- Record dependencies for the Template --%>
<ics:if
condition='<%=ics.GetVar("tid")!=null%>'><ics:then><render:logdep
cid='<%=ics.GetVar("tid")%>' c="Template"/></ics:then></ics:if>
<render:getpageurl outstr="myURL" pagename='HelloAssetWorld/
dummyTemplate' cid='1156878442427' c='HelloArticle'/>
Got URL: <a href='<%=ics.GetVar("myURL")%>'> Click here</a><br/>
dummyTemplate:
completely blank, no logDep.