In my previous blogs I've been introducing some of the new extensibility features that are currently available in the current Alfresco Community source and that will be available in Alfresco Enterprise 4.0. In many of these blogs I've demonstrated the use of a new Spring Surf debug tool called 'Surf Bug' without providing much additional information about it. In this blog I'm going to describe Surf Bug in greater detail.
When I first started working on the Alfresco Share user interface the most immediate challenge was identifying the various components that comprise each page. It's was something of an art to find the source file in which the actual HTML on any given page is defined - and that was after you understood how a Spring Surf page is built!
This posed a major challenge for anyone extending a page in Alfresco Share as the first task was always identifying the files that actually needed extending. In order to assist with this problem we have introduced 'SurfBug' which (as its name suggests) took its inspiration from the FireFox add-on 'FireBug' and when enabled is designed to highlight Components or Sub-Components that comprise the current page and provide information on the files and properties that define them.
SurfBug is a part of Spring Surf rather than Alfresco Share and as such is actually available to any Spring Surf application. It is enabled by the 'surfBugStatus' WebScript (i.e. accessed through '<application context>/service/surfBugStatus').
Enabling SurfBug and refreshing a page will overlay red boxes on the screen indicating the location of the Components or Sub-Components on the page (the information shown is based upon the Surf application configuration - if the Component interfaces is being fulfilled by the 'org.springframework.extension.surf.type.AdvancedComponentImpl' class (which is the default) then Sub-Component information will be shown. When you mouse click on a box, a pop-up will be displayed that hopefully provides all the information about the Sub-Component that you could possibly need.
Things To Note
SurfBug is not guaranteed to show every Sub-Component on the page if the DOM elements for that page have been manipulated in certain ways (e.g. you won't see highlights for the Sub-Components that make the pop-up panels for site creation, file upload, etc) and since the highlights are absolutely positioned on the page (to avoid affecting the DOM structure) they are not guaranteed to be in pixel perfect position - the rough position of a highlight and the information contained in its pop-up should hopefully be sufficient though!
You should also not attempt to drive an applications user interface with SurfBug enabled. The most effective way we've found of using it is to navigate to the page you're interested in, toggle SurfBug on from another tab in your browser and then refresh the application page. If you need to move onto another page - simply toggle SurfBug back off, reload the page, navigate and switch back on.
One other important point is that Surf Bug gets enabled for the entire application - NOT just for the user that enables it. It's intended to be used in development, not production. It's 'admin' protected so regular users won't be able to switch it on, but if it gets enabled then every user will see the highlights until it's switched off again.
The following table provides a breakdown of the information that SurfBug provides:
The ID of the Page being displayed
The ID of the Template being displayed
Typically this is the path of the FreeMarker template used to render the Spring Surf Template referenced by the Page.
The ID of the Component that the Sub-Component belongs to.
The runtime path of the file containing the configuration for the Component
Generated unique id of the component
The id of the region the template into which the component has been bound
The id of the object at which the component is defined (this will typically be a Page id, a Template id or will be 'global')
The scope at which the Component has been defined (this will typically be 'global', 'page' or 'template').
Any custom properties that have been configured for the component. These are not used by Spring Surf to perform any rendered but may be used by the Component itself if it is parameterized in any way (this may be the case for Components backed by JSPs, WebScripts or FreeMarker).
The id of the Sub-Component - this is always prefixed by the parent Component id and a '#' indicates the start of Sub-Components identification
The runtime paths of all the files that have provided input into this Sub-Component (a Sub-Components property, index and evaluation configuration can all be updated by zero or more extension modules). If no extensions have been applied then this will only contain a single path.
The specifically set index of the Sub-Component within the Component. This is the final index after all extensions have been applied. If nothing is shown it means that the default is being used.
The processor that has been used to render the Sub-Component. If this Sub-Component has been generated from legacy configuration then this could be either WebScript, WebTemplate or JSP (or some custom processor) - but AdvancedComponents only currently support WebScript processors and if the Sub-Component is not legacy generated then this will be blank.
The URI used to render the Sub-Component. This is the URI that is generated as a result of processing all Evaluations across all extensions - so is not necessarily the value configured in the source configuration file.
This is the id of the first successful Evaluation and therefore the one that returned the 'Evaluated URI' field. If this is blank it means that no Evaluations were performed on the Sub-Component.
If the Sub-Component was rendered by a WebScript then this will show the runtime path of the WebScript descriptor file. The other WebScript files (template, controller, etc) will be co-located.
This provides a link to the WebScript information which will be opened in a new tab/window.
The properties for the Sub-Component as returned by a successful Evaluation. Properties can be overridden by Evaluations to change how a Sub-Component is rendered.
A list of the extensibility directives that have been applied to the Sub-Component.