Entries filed under 'documentation'

Posted by Kas Thomas SEP 09, 2011

Posted in cq5, development, documentation and fise Comments 4



Customizing the Clickstream Cloud

Last time, I reviewed the basics of the powerful Clickstream Cloud feature of Adobe WEM (formerly CQ5), which is the feature whereby, if you type Ctrl-Alt-C, you get a popup summary of various bits of contextual information about the user, the user's browser, and the page the user is currently visiting (see illustration further below).


As with almost everything else in WEM, the Clickstream Cloud can be customized relatively easily, because the code for the Cloud is easily accessible (and modifiable) in the repository.

If you go in the repository under /libs/cq/personalization/clientlib/source/shared (best done in CRXDE Lite: just aim your browser at http://localhost:4502/crx/de/index.jsp#/crx.default/jcr%3aroot/libs/cq/personalization/clientlib/source/shared), you'll see a half dozen *.js files that govern the Clickstream Cloud's basic behavior, and if you look under /libs/cq/personalization/clientlib/source/clickstreamcloud, you'll find the *.js files that contain code for the various session stores that manage the information fields displayed in the cloud dialog. There's also a js.txt file at /libs/cq/personalization/clientlib/js.txt that governs how all these *.js files are loaded.

As a very simple example of customization of the Clickstream Cloud, let us suppose that you wanted to add a timestamp to the cloud dialog under "Surfer information" as shown below:



Notice the part, under Surfer Information, where it says "Thu Sep 08 2011 17:09:45," etc. This information was added as a result of custom code.

There are a couple of ways to do this. One way would be to alter the setSurferInfoInitialData() function in config.json.jsp (which is located in a somewhat obscure place, namely /libs/cq/personalization/components/clickstreamcloud/command/config/). You might be very tempted to do this since that's the function where the user's IP address, for example (which appears under Surfer Information), is set. But making a change in this function would actually be a bad thing to do, for a number of reasons. First, you're dealing with a core WEM file. And you're making hard-coded changes to it. There's no guarantee that this file will stay unmodified (or even continue to exist) in future versions of WEM, and by putting custom code in it, you've created a maintenance nightmare.

A better alternative is to create your own separate file, perhaps called custom.js, and place it under /libs/cq/personalization/clientlib/source/clickstreamcloud/. The content of custom.js is simply:
 
CQ_Analytics.CCM.addListener("configloaded", function() {
              CQ_Analytics.SurferInfoMgr.setProperty( "timestamp", new Date() );
 }, CQ_Analytics.SurferInfoMgr);

To ensure that custom.js loads at runtime, you do need to make a change to the aforementioned js.txt file (namely, the one at /libs/cq/personalization/clientlib/js.txt). Just add the line "clickstreamcloud/custom.js" to the end of the file.

Now you should be able to go to a new page (or reload the current page) in WEM, type Crtl-Alt-C, and see the timestamp information in the Surfer Information portion of the Clickstream Cloud dialog.

What's neat is that if you now click the Edit link in the upper right portion of the Cloud dialog, then click the Surfer Information tab of the dialog that pops up, you'll see timestamp info among the editable fields of the dialog:



For more information on the Clickstream Cloud API (including how you can create your own custom session store), see the documentation here.


Posted by Kas Thomas APR 19, 2011

Posted in cq5 and documentation Comments 4



Adobe CQ documentation now available as PDF

From time to time, people ask us if our product documentation is available in PDF. I pleased to be able to say that the answer is yes. Thanks to the recent work of Chris Zumbrunn and other members of the documentation team, we can now offer a single, consolidated PDF document (2258 pages in length) comprising all of the available documentation for CQ 5.4 and CRX 2.2 (with the exception of Java API documentation, which is still HTML-only).


The PDF documentation is here (approximately 60 megabytes).


Of course, while it's very handy to be able to have a searchable, page-numbered, printable (in A4 format) copy of the documentation at your fingertips, it's important to remember that CQ documentation is constantly undergoing revision and refinement, which means the online (HTML) documentation at docs.day.com will always be the most current, up-to-date source of information on CQ and CRX. Always check the online docs when you want the latest information.


Posted by Greg Klebus OCT 31, 2010

Posted in documentation and ignite Comment 1



Customers Helping us Improve LDAP Authentication on docs.day.com

During the Q&A session with Roy Fielding and product management at Ignite Chicago, nicely written-up by CMS Wire's Irina Guseva, I have received a couple of questions related to user/group/permission management in CQ5/CRX instances configured for LDAP authentication. While all the requested functionality is in the product, and the respective configuration and UI options are described in the LDAP documentation, I realized that we were missing a more generic overview of what the LDAP integration shipped with our products can actually do.

I asked our documentation team to have a look at this, and they quickly provided an extended introduction and overview of LDAP integration. Please have a look at LDAP Authentication on docs.day.com, and leave comments there if you are still missing some information.

Some of the questions hopefully answered by the new introduction include:


• Q: (How) can I synchronize users/groups sourced from LDAP / Active directory with my CQ5 / CRX instance? A: Users and their groups (including configurable filtering and metadata matching) are automatically synchronized to your repository upon user's login. Additionally, you have the ability to manually synchronize user profiles (without forcing users to authenticate).
• Q: How can I assign CMS permissions to the users coming from LDAP? A: We usually recommend assigning LDAP groups to CMS-managed groups (in CQ5), and then managing permissions for the CQ5 groups. LDAP groups usually reflect organizational structure, whereas CQ5 groups usually reflect CMS usage structure.
• Q: Is it possible to do group matching from an AD group to the same group in CQ? A: As explained above, LDAP-sourced groups in CQ5 usually reflect the orgchart, and the CQ5-managed groups (like author, contributor, etc) reflect the CMS usage. You can have LDAP-sourced users belong to CQ5 CMS groups by assigning their LDAP groups to be members of the CQ5 groups.
• Q: How can I assign permissions - the way you describe above - without forcing my users to log in to the system (what I call the "bootstraping problem"). A: use a few LDAP user names to manually synchronize their profiles. This will pull the necessary LDAP groups to CQ5, and will allow for assigning them to respective CQ5 "CMS" groups, which will give the LDAP users their CMS-side rights.

Thanks to Hal Danziger, (@halwebguy) CTO at New York Media  for asking the questions. I also received a similar question from someone from University of Cincinnati, but could not find the person's name afterwards, sorry.


Posted by Lars Trieloff JAN 25, 2008

Posted in documentation, jcr and modelling Comment 1



Content Modeling for JCR

Since content-centric applications are content-driven, modeling the content structure is the most crucial part when documenting the architecture of your application. A big part of the general architecture is usually determined by the framework you chose to use: If you are using Sling, it is Content-Behavior-Appearance, if you are using Apache Cocoon, it is content pipelining, and so on. What makes your application special is the content structure or the content model. As understanding the content structure is a crucial part for communicating the architecture of your application, you should spend considerable amount of time on designing, documenting and communicating the content structure to other developers. In JCR content has two general properties that deserve documentation: one the one hand there is the location of nodes in the content tree. The most straight-forward approach of documenting this is simply expressing the tree structure in a diagram as the one below or using a JCR repository browser like the CRX explorer that comes with Day's CRX repository or the open source tool JCR Explorer.



There are multiple downsides connected with this approach: One the one hand, these autogenerated tree models communicate importance and relation of portions of the content tree poorly, as they can only express parent-child relationships, and to a certain degree node types. Secondly as the tree grows, it becomes increasingly complex and confusing to the observer. If you really care about communicating your content structure, then drive structure documentation, do not let it happen.

The second aspect of content modeling for JCR is the node type. JCR has a complex node typing system that allows multiple inheritance, mixins, child-nodes and references. For real-world application documentation three approaches can be found:

• using standard CND notation - this is the most obvious approach as you have to write the CND files anyway and it provides a very compact notation that is able to express every aspect of the node type. Unfortunately, this CND notation is optimized for writes, not readability or comprehensibility. In order to make it easy to understand, the following two approaches are being used.
• automatically generated HTML nodetype documentation, using a tool like Jackrabbit-NTdoc , which basically takes the node type definitions and automatically translates them into a number of HTML pages that are browsable similar to Javadoc and document every aspect that can be found in the node type definition.
• ad-hoc graphical notations. These notations often are inspired by UML or entity relationship diagrams, but seldom reused or documented. While they are more readable than the CND notation or browsable HTML documentation, the lack of standardization and meta-documentation makes them hardly portable.

A main advantage of these graphical notations however is that you as the architect can decide what is important, what is related and what is obvious and does not need to be documented at a high level. This again shows that you should drive your content model documentation and not let it happen.

The notation proposed below uses a combination of a graphical treemap notation for describing the content tree and a UML-class-diagram inspired notation for documenting node types, node type inheritance and node references. A main advantage of this notation is, besides re-use of existing notations like UML or Fundamental Modeling Concepts (FMC) that it offers a connection between tree structure and node type.



The upper part of the chart features an example content tree in treemap notation. Speaking in FMC terms, this content tree is a set of nested places and this nesting can be driven by the architect in order to express relation (places are next to each other), containment (one place in another) and importance (place is bigger). You can even "zoom in" parts of the chart to explain content structure more in-depth. A good example for variable content can be found in /apps/wiki/themes where any number of themes can be stored, but two "default" and "extra" are mentioned as examples.

This treemap structure is both visually compelling and compact, so it can be combines with the UML-inspired node type notation at the bottom of the chart. This notation uses UML class diagrams to express node types (bold font, shaded background) and Mixins (italic font, white background). Node types can have three types of relations: inheritance, containment and reference. For inheritance the default solid line with a hollow triangle arrowhead at the super type is used. For child nodes and associations a basic "association" line without arrowheads is used. For the cardinality of relationships: as there is only one parent node or referencing node, only the cardinality indicator at the child or referenced node type is used. Here we use a simple-regular-expressions inspired syntax where * means: any number of node, + means at least one node, n means exactly n nodes, and so on.

Using a dotted line you can map node types to places in the treemap where this node type can be used.

To sum it up, the proposed notation is a tool that helps understanding and communicating content-centric software systems. It is not intended to be used to automatically generate code or to be generated automatically from code, instead it is a second description of your software system that lives beside the code of your system (as the primary description) and is suited for technical communication with humans.

Posted by Teresa Mulvihill DEC 12, 2007

Posted in documentation and standards Comment 1



DocBook vs. DITA: Will the real standard please stand up?

I have been a documentation specialist for over eleven years and a steadfast supporter of DocBook for over six years. I'd tried my hand at DITA and gave it up as a fad; lots of bells and whistles, but too complicated to integrate. And couldn't DocBook do everything DITA promised anyway?

So when Allette Systems contacted me to speak on XML standards in Sydney Australia, I jumped at the chance to prove to the documentation world just how wonderful DocBook is and how DITA falls short. Fortunately, my in-depth research opened my eyes to the benefits and limitations of both. Are these two seemingly rival standards really that different? My presentation answers this question with comparative examples, and allows you, the audience, to decide for yourselves.

| View | Upload your own