Get the Tools You Need
Setting up a Folder Structure
During Development Deploy Files and Folders – not a JAR!
Create a quick shell or ant script to copy your working files and folder structure to your tomcat Share classes folder. You can then work on your assets easily and quickly deploy them all to a running Alfresco server. The previous post describes how to package them up for run-time deployment as a single JAR – but that isn’t needed during development, and in fact isn’t really desirable – having the files and folders expanded out ensures quicker deployment and ensures the various config options discussed below will work correctly.
Share is configured by various Spring config files and Alfresco format config files. These are easy enough to override. There’s really only one file you need to worry about for most situations. The default config override file that Share is already set-up to look for is called share-config-custom.xml and should be placed in your $TOMCAT_HOME$/shared/classes/alfresco/web-extension folder. Here you can override various configuration settings and several of the most useful ones for development and debugging will be discussed here. If you do want to override Spring beans, then Share will look for a file called custom-slingshot-application-context.xml and it should be placed in the same folder. Generally unless you are modifying Surf internals you won’t need to override the Spring beans.
A default installation of Alfresco will include a .sample version of these files in the above location, they can also be found in the source tree: HEAD/root/projects/slingshot/config/alfresco/web-extension
<!-- Global config section -->
<!-- Developer debugging setting - DEBUG mode for client scripts in the browser -->
<!-- LOGGING can be toggled at runtime when in DEBUG mode (Ctrl, Ctrl, Shift, Shift).
This flag automatically activates logging on page load. -->
Alfresco.logger.debug("some string value");
The log4j info, warn, error and fatal levels can be used if required.
SpringSurf Development Mode
This is an example of the config required for share-config-custom.xml:
<config evaluator="string-compare" condition="WebFramework">
<!-- Autowire Runtime Settings -->
<!-- Pick the mode: development, preview, production -->
logger object API:
boolean logger.isDebugEnabled() - returns true/false to indicate if debug logging output via log4j is active,
this can be used to ensure performance isn't degraded when console logging is inactive.
void logger.log(string message) - output a log message to the console
To turn on logging for your application, modify the log4j.properties file and set the following class to debug:
Note that the same logging class name is used by the Alfresco repository and SpringSurf – it is maintained for backward compatibility.
On a production deployed instance of Share or any instance where all the various debug settings noted above are not applied, most caching and refresh issues can be quickly resolved without restarting the app-server. The Refresh WebScripts option in the Share WebScript index page can be used to clear the caches for all components and compiled scripts. It also means that additional WebScripts can be deployed or removed at runtime without restart. Use the browser to navigate to /<yourserver>/share/service/index – this will display the WebScripts index page. Click the Refresh Webscripts button to clear the caches and refresh the list of available WebScripts.
Separate Alfresco and Share Server Instances
Since Alfresco 3.0, the Share client is a stand-alone web-application and the share.war can be deployed on a separate TomCat instance to the Alfresco repository, on another server entirely if required. This is recommended for development and production. For development, it enables the Share application to be restarted quickly (a few seconds on a modern laptop or server) without interfering with the main Alfresco repository instance. For production, it allows proxies and clustering to be implemented.
The configuration to do this is simple, but first it requires the set-up of a new TomCat instance, with appropriate tweaks as recommended for an Alfresco server such as; JVM memory settings, server URIEncoding set to UTF-8, web-extension folder etc. The easiest way to do this is to take a copy of the Alfresco installed TomCat instance and remove the alfresco.war. If you are running the new TomCat instance on the same machine as the Alfresco repository instance then modify the port settings in tomcat/conf/server.xml to ensure Share can be started at the same time as Alfresco. Developers at Alfresco generally use port 8080 for Alfresco and port 8081 for Share.
By default the Share web-application will attempt to communicate with the Alfresco server via HTTP on port 8080. There should be no additional configuration required if you use those settings. However if your Alfresco instance is not running on this port then the following example of configuration for share-config-custom.xml can be used to modify the endpoint settings, change the endpoint-url values as appropriate:
<!-- Overriding endpoints to reference a remote Alfresco server -->
<config evaluator="string-compare" condition="Remote">
<name>Alfresco - unauthenticated access</name>
<description>Access to Alfresco Repository WebScripts that do not require authentication</description>
<name>Alfresco - user access</name>
<description>Access to Alfresco Repository WebScripts that require user authentication</description>
<description>Alfresco Feed - supports basic HTTP authentication via the EndPointProxyServlet</description>
Hopefully this list of tips should help speed up development and improve your experience when customising and working with Alfresco Share components. In the next post we will explore the architecture of SpringSurf components, templates and page rendering.