svn commit: r1788399 - /sling/site/trunk/content/documentation/bundles/content-loading-jcr-contentloader.mdtext

[kw...@apache.org]

Author: kwin
Date: Fri Mar 24 10:00:44 2017
New Revision: 1788399

URL: http://svn.apache.org/viewvc?rev=1788399&view=rev
Log:
SLING-6701 clarify contentloader documentation with regards to target paths

Modified:
    sling/site/trunk/content/documentation/bundles/content-loading-jcr-contentloader.mdtext

Modified: sling/site/trunk/content/documentation/bundles/content-loading-jcr-contentloader.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/content-loading-jcr-contentloader.mdtext?rev=1788399&r1=1788398&r2=1788399&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/content-loading-jcr-contentloader.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/content-loading-jcr-contentloader.mdtext Fri Mar 24 10:00:44 2017
@@ -6,38 +6,39 @@ Apache Sling provides support for initia
 
 Bundles can provide initial content, which is loaded into the repository when the bundle has entered the *started* state. Such content is expected to be contained in the bundles accessible through the Bundle entry API methods. Content to be loaded is declared in the `Sling-Initial-Content` bundle manifest header. This header takes a comma-separated list of bundle entry paths. Each entry and all its child entries are accessed and entered into starting with the child entries of the listed entries.
 
-Adding this content preserves the paths of the entries as show in this table, which assumes a `Sling-Initial-Content` header entry of `SLING-INF/content`:
+Adding this content preserves the paths of the entries as shown in this table, which assumes a `Sling-Initial-Content` header entry of `SLING-INF/content` (with no further directives):
 
-| Entry | Repository Path |
-|--|--|
+| Source Entry Paths in Bundle | Target Repository Path |
+|---|---|
 | `SLING-INF/content/home` | `/home` |
 | `SLING-INF/content/content/playground/en/home` | `/content/playground/en/home` |
+| `SLING-INF/someothercontent/playground/en/home` | not installed at all, because not below the `Sling-Initial-Content` header entry | 
 
 Bundle entries are installed as follows:
 
 | Entry Type | Installation method |
-|--|--|
+|---|---|
 | Directory | Created as a node of type `nt:folder` unless a content definition file of the same name exists in the same directory as the directory to be installed. Example: A directory `SLING-INF/content/dir` is installed as node `/dir` of type `nt:folder` unless a `SLING-INF/content/dir.xml` or `SLING-INF/content/dir.json` file exists which defines the content for the `/dir` node. |
 | File | Unless the file is a content definition file (see below) an `nt:file` node is created for the file and an `nt:resource` node is created as its `jcr:content` child node to take the contents of the bundle file. The properties of the `nt:resource` node are set from file information as available. If the file is a content definition file, the content is created as defined in the file. See below for the content definition file specification. |
 
 It is possible to modify the intial content loading default behaviour by using certain optional directives. Directives should be specified separated by semicolon. They are defined as follows:
 
 | Directive | Definition | Default value | Description |
-|--|--|--|--|
-| `overwrite` | <code>overwrite:=(true&#124;false)<code> | `false` | The overwrite directive specifies if content nodes should be overwritten or just initially added.  If this is true, existing nodes are deleted and a new node is created in the same place. |
-| `overwriteProperties` | <code>overwriteProperties:=(true&#124;false)</code> | `false` | The overwriteProperties directive specifying if content properties should be overwritten or just initially added. |
-| `uninstall` | <code>uninstall:=(true&#124;false)</code> | `overwrite` | The uninstall directive specifies if content should be uninstalled when bundle is unregistered. This value defaults to the value of the `overwrite` directive. |
+|---|---|---|---|
+| `overwrite` | <code>overwrite:=(true&#124;false)<code> | `false` | The overwrite directive specifies if content nodes should be overwritten (at the target repository path, which is "/" by default) or just initially added.  If this is true, existing nodes are deleted and a new node is created in the same place. This directive should be used together with the `path` directive to limit overwriting. |
+| `overwriteProperties` | <code>overwriteProperties:=(true&#124;false)</code> | `false` | The overwriteProperties directive specifying if content properties should be overwritten or just initially added (at the target repository path, which is "/" by default). This directive should be used together with the `path` directive to limit overwriting. |
+| `uninstall` | <code>uninstall:=(true&#124;false)</code> | value from `overwrite` | The uninstall directive specifies if content should be uninstalled when bundle is unregistered. This value defaults to the value of the `overwrite` directive. |
 | `path` | <code>path:=*/target/location*</code> | `/` | The path directive specifies the target node where initial content will be loaded. If the path does not exist yet in the repository, it is created by the content loader. The intermediate nodes are of type `nt:folder`. |
 | `checkin` | <code>checkin:=(true&#124;false)</code> | `false` | The checkin directive specifies whether versionable nodes should be checked in. |
 | `ignoreImportProviders` | `ignoreImportProviders:=list of extensions` | `empty` | This directive can be used to not run one of the configured extractors (see below). |
 
-Examples of these directives uses could be (assumes a Sling-Initial-Content header entry of SLING-INF/content):
+Examples of these directives within `Sling-Initial-Content` header entries:
 
-| Entry | Behaviour |
-|--|--|
-| `SLING-INF/content/home;overwrite:=true;uninstall:=true` | Overwrites already existing content in */home* and uninstalls the content when the bundle is unregistered. |
-| `SLING-INF/content/home;overwriteProperties:=true` | Overwrites properties of existing content in */home*. |
-| `SLING-INF/content/home;path:=/sites/sling_website` | if */sites/sling_website* exists it loads the content into it. Otherwise, it loads the content into root node */*. |
+| `Sling-Initial-Content` header entry | Behaviour |
+|---|---|
+| `SLING-INF/content/home;overwrite:=true;path:=/home` | Overwrites already existing content in */home* and uninstalls the content when the bundle is unregistered. |
+| `SLING-INF/content/home;overwriteProperties:=true;path:=/home` | Overwrites properties of existing content in */home*. |
+| `SLING-INF/content/home;path:=/sites/sling_website` | This loads the content given in *SLING-INF/content/home* into */sites/sling_website*. |
 | `SLING-INF/content/home;checkin:=true` | After content loading, versionable nodes are checked in. |
 
 ## Loading initial content from bundles