Obsolete Pages{{Obsolete}}
The official documentation is at: http://docs.alfresco.com
{{AVMWarning}}
AVM
A transparent directory (or file) in Alfresco acts like a 'sheet of glass' that can be written upon without affecting the object being viewed. You can either look through it and see the object on the other side, or you can write directly upon it, and see your own data instead. Thus, until you make modifications, a transparent directory (or file) is similar to a UNIX-style symbolic link; however, after making modifications, you're manipulating a detached, private copy of the original.
Imagine that you have a directory named B that contains a file named cow.html:
Traditionally, in order to make the contents of this directory available somewhere else (e.g.: in a directory named A), you'd have two distinct options:
Alfresco will allow you make directories (and files) act like windows that can written upon without affecting the object being viewed. If A is a transparent directory, we can indicate this by making the folder icon that represents it 'clear looking'. Let's also attach a miniature image of the B folder next to A icon, to indicate that A is layered on top of B.
Because A is a transparent layer on top of B, you can see the contents of B within A. To indicate that cow.html in A is only visible because it is being seen through a transparent 'window', it's shown using a blue-colored font (mnemonic: objects shown in blue are in the background, like blue mountains in the distance).
Definition:
As you'd expect, if you were to add a new file to B, such as moo.txt, you'd see it show up in A immediately:
Note that transparent directory A now contains two background objects: cow.html and moo.txt.
So far, A just behaves very much like a UNIX-style symlink to B.
If we attempt to change the contents of A/moo.txt, Alfresco will instead create a local copy for modification. To illustrate this, transformation, moo.txt now appears in a black font within A:
A/moo.txt and B/moo.txt will have separate version histories from this point forward.
Definition:
In the previous example, cow.html is still a background object in A. If we were to delete it, here's what we'd see:
Notice that deleting cow.html in A has not altered cow.html in B. Nothing you do to a background object can alter what it once allowed you to see.
Examine the previous diagram, and then try to picture what would happen if B/zebras.jpg and B/C/platypus.html were added. Now look at the figure below:
Similar to what we've seen in previous examples, adding a file like B/zebras.jpg causes the background file A/zebras.jpg to appear. What's new in this example is that the creation of B/C causes a background subdirectory to appear: A/C. Here again, when we don't directly modify the transparent directory A, it behaves very much like a symink to B.
Unlike a symlink, transparent directories can contain additional files (and directories) that the object they're viewing does not contain. For example, if duck.html were added to A from the previous example, we'd get this:
Because duck.html is a foreground object in A, it appears in a black font.
In the previous example, suppose the foreground file B/C/platypus.html is renamed to B/C/egg.html. Notice what happens to the background file A/C/platypus.html below:
Because A is like a 'window' on top of B, A/C/platypus.html becomes A/C/egg.html automatically.
Let's start a fresh example. Suppose that directory B contains the files cow.html, moo.txt, and C/egg.html. If A is a transparent directory that is layered on top of B, we'd see something like this:
Notice that within A: cow.html, moo.txt and egg.html are background files, and C is a background directory. To reinforce what has already been discussed, if we were to modify the background file A/moo.txt, it would become the foreground file A/moo.txt:
If B/C is renamed to B/D, then background subdirectory A/C is automatically renamed to A/D too; put another way, background subdirectories and background files have similar behavior when it comes to tracking renames that occur in a lower layer.
Notice that A now contains a background directory named D.
When a background object within a transparent directory is modified, it becomes a foreground object. We've seen this for files (e.g.: A/moo.txt became A/moo.txt), but it's also true for subdirectories. For example, within transparent directory A, if we were to add a file to the background subdirectory D (e.g.: hen.html), we'd be modifying A/D. Therefore it must become a foreground subdirectory A/D. Alfresco makes A/D transparent by default, so that you'll continue to track changes in B/D:
The distinction between background subdirectory A/D and transparent subdirectory A/D might seem a bit moot at first because Alfresco makes A/D an overlay on B/D automatically. Thus, when B/D/goat.html is added, it also appears as the background object A/D/goat.html:
Unless someone renames B/D (i.e.: the underlying directory), this somewhat subtle distinction will continue to be moot.
Just like a symlinked directory can point to a directory that is no longer present, a transparent directory (e.g.: A/D) can be an overlay on top of a directory that has been renamed or deleted (e.g.: below, B/D was renamed to B/E). The icon for the transparent directory D is shown in red to indicate this:
Because A/D was an overlay on B/D, but B/D is gone now, the background files within A/D (i.e.: A/D/egg.html and A/D/goat.html) have vanished as well.
Definition:
Just like any other kind of directory, a transparent directory can be deleted, For example, if A/D were deleted, you'd see something like this:
Obviously, deleting a transparent directory removes all it foreground objects (e.g.: A/D/hen.html).
Earlier, it was shown how files in the directory beneath a transparent directory appear as background files. It was also shown how an attempt to modify a 'background file' creates a foreground file, which hides the background file from view. However, consider the previous figure; transparent directory A already has a file named moo.txt. What happens if a file named moo.txt is added to the underlying directory B? As you can see, the foreground file A/moo.txt still hides B/moo.txt; the fact that B/moo.txt was created later doesn't matter:
Similarly, because A is a transparent layer on top of B, if the subdirectory A/C is created, Alfresco defaults to making it an overlay on B/C, even if B/C doesn't exist yet. To make this example, a bit more interesting, if we were to also create a file named hen.html within A/C, the result would be:
Definition:
Note that A/C is not stale because B/C has never existed; A/C is merely latent. Nothing is 'broken', so A/C does not appear in red. It's merely pre-configured to maintain the parallel directory structure that already exists between A and B. At this point, if B/C were created containing the file egg.html, the result would be:
Notice how the background file A/C/egg.html has appeared automatically. It does not matter that the transparent directory A/C was created prior to the directory it overlays (i.e.: B/C).
Notice also that Alfresco can tell the difference between a transparent directory overlaying something that has been moved (or deleted), and a transparent directory overlaying something that simply has not been created yet. It can do this because renames and deletions are recorded. Thus, it's easy for the user (and merge scripts) to tell whether an transparent overlay is out of sync with its underlying layer, or simply growing in new directions in advance of its underlying layer.
By default, when a subdirectory is created within a transparent directory, it too is a transparent directory (e.g.: A/C in the previous example was an overlay on B/C). However, if you wish, you can also create A/C as a normal (opaque) directory; as such, no background directories or files will appear within it:
In the figure above, A/C is represented by a solid yellow folder, not a 'clear' or 'see-through' folder icon. At this point, if B/C were created, and egg.html were placed inside of it, we'd have:
Note that A/C still only contains hen.html; no background file A/C/egg.html, appears. Alfresco's default behavior is simple to remember:
As you have seen, each of these default behaviors may be overridden.
If a transparent directory is like a 'sheet of glass' over another directory, a transparent file is like a 'fiber optic cable' to another file. As long as you don't attempt to modify the contents of a transparent file, it behaves very much like a UNIX symlink. Transparent files provide much finer-grained control than transparent directories do. For example, a directory might contain a set of transparent files referencing the contents of more than one directory.
In the figure below, X/yak.txt is a transparent overlay on top of Y/yak.txt, and X/zoo.txt is a transparent overlay on top of Z/zoo.txt:
However, if you attempt to modify the contents of a transparent file, it becomes a normal/opaque file. To illustrate this, if we write to X/yak.txt, the clear box around it (along with its associated annotation) is removed:
Writing to a transparent file is quite different from merely renaming it. For example, if X/zoo.txt were just renamed to X/zebra.txt, it would remain a trasparent overlay on Z/zoo.txt. Changes to the contents of Z/zoo.txt would be visible immediately within X/zoo.txt. Notice in the figure below that X/zebra.txt still points to Z/zoo.txt:
Let's rename X/zebra.txt back to X/zoo.txt again:
Just like with a symlink, it's also possible to create a transparent file whose target is missing due to a rename or deletion. For example, in the figure below, Z/zoo.txt has been renamed to Z/zebra.txt:
Notice how X/zoo.txt is now a stale transparent file; the object it once overlayed (Z/zoo.txt) no longer exists. Hence, it's shown using a red font to highlight the problem.
Transparent layers in Alfresco are reminiscent of Unionfs; however there are some critical differences: