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.
How it works
Imagine that you have a directory named B that contains a file named cow.html:
Later updates in B are seen in A, but separate changes in A can't be made; it's merely an alias
Not well-supported on all operating systems
Circular references are possible
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).
A directory (or file) that is seen through the clear barrier offered by a transparent directory (e.g.: cow.html).
Prior to modification: symlink-like behavior
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:
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.
Augmenting a transparent directory
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:
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/Dtransparent 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.
Gotcha: Stale transparent directories
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:
Obviously, deleting a transparent directory removes all it foreground objects (e.g.: A/D/hen.html).
Additions beneath a transparent directory
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:
A transparent object that overlays something that does not exist yet.
For example, A/C is a latent transparent directory because it will overlay B/C, once B/C is created.
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.
Transparent directories with opaque subdirectories
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:
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:
Within opaque directories, opaque subdirectories are created
Within transparent directories, transparent subdirectories are created
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:
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: