0.4:

    - datatable columns can now be configured to be shown or hidden
    - an extra field has been added to the config dialog to pass additional server side query parameters.
        See the wiki documentation (http://wiki.alfresco.com/wiki/Auditing_(from_V3.4)#Advanced_Query) and the web script description.
    - datatable css fix for google chrome, and various css tweaks
    - Added help link opposite the config link



git-svn-id: https://share-extras.googlecode.com/svn/trunk/Sandbox/Audit Dashlet@728 a3f5c567-fd0f-3a89-9b71-a290c5a5f590

Author: romainguinot

README.txt

@@ -3,60 +3,73 @@ Audit Application dashlet for Alfresco Share
 
 Author: Romain Guinot
 
-This project defines a custom dashlet to display events for a given audit application. 
+This project defines a custom dashlet to display events for any given audit application. 
 
-The dashlet will need to have auditing application(s) already configured, and to be useful some events captured. 
+The dashlet will need to have auditing application(s) already configured, and, to be useful, some events captured.
 See http://wiki.alfresco.com/wiki/Auditing_(from_V3.4) on how to define audit applications and some samples. 
 
+From 3.4.4, also see http://wiki.alfresco.com/wiki/Content_Auditing and http://wiki.alfresco.com/wiki/Audit_Filter.
+
 Installation
 ------------
 
-The dashlet has been developed to install on top of an existing Alfresco
-3.4 installation.
+The dashlet has been developed to install on top of an existing Alfresco 3.4 installation.
+
+* Users : Prebuilt jar
+
+    A prebuilt jar is provided. You only need to copy it to <tomcat-home>/shared/lib.
 
-An Ant build script is provided to build a JAR file containing the 
-custom files, which can then be installed into the 'tomcat/shared/lib' folder 
-of your Alfresco installation.
+* Developers : Building the jar
 
-To build the JAR file, run the following command from the base project 
-directory.
+    For developers, an Ant build script is provided to build a JAR file containing the
+    custom files, which can then be installed into the 'tomcat/shared/lib' folder
+    of your Alfresco installation.
 
-    ant clean dist-jar
+    To build the JAR file, run the following command from the base project
+    directory.
 
-The command should build a JAR file named sample-audit-dashlet.jar
-in the 'dist' directory within your project.
+	ant clean dist-jar
 
-To deploy the dashlet files into a local Tomcat instance for testing, you can 
-use the hotcopy-tomcat-jar task. You will need to set the tomcat.home
-property in Ant.
+    The command should build a JAR file named sample-audit-dashlet.jar in the 'dist' directory within your project.
 
-    ant -Dtomcat.home=C:/Alfresco/tomcat clean hotcopy-tomcat-jar
+    To deploy the dashlet files into a local Tomcat instance for testing, you can
+    use the hotcopy-tomcat-jar task. You will need to set the tomcat.home
+    property in Ant.
 
-Once you have run this you will need to restart Tomcat so that the classpath 
-resources in the JAR file are picked up.
+	ant -Dtomcat.home=C:/Alfresco/tomcat clean hotcopy-tomcat-jar
 
-As an alternative, you may also copy the exploded files in your classpath, but they must have the classpath tree than the one in the jar. 
-If using development/debug mode for the web framework, you will not need to restart tomcat, but you may have to clear your 
-browser's cache. 
+    Once you have run this you will need to restart Tomcat so that the classpath resources in the JAR file are picked up.
+
+    As an alternative, you may also copy the exploded files in your classpath, but they must have the classpath tree
+    than the one in the jar. If using development/debug mode for the web framework, you will not need to restart tomcat,
+    but you may have to clear your browser's cache.
 
 Using the dashlet
 -----------------
 
-Log in to Alfresco Share and navigate to a site or user dashboard. Click the 
-Customize Dashboard button to edit the contents of the dashboard and drag 
-the dashlet into one of the columns from the list of dashlets.
+Log in to Alfresco Share and navigate to a site or user dashboard. Click the  'Customize Dashboard' button to edit the contents
+of the dashboard and drag the dashlet into one of the columns from the list of dashlets.
 
  * Configuration : 
 
     Click Configure to choose an existing audit application. Results will appear as you type and will be matched 
     against the live list of audit applications as reported by /api/audit/control. 
 
-    For convenience, application names are prepended with a space. So by typing a leading space in the search box, 
-    you will see the full list of applications in the suggestions. May be useful if you don't know what application name to search for. 
+    For convenience, the list will pop out when opening the configure dialog with no applications currently configured.
+    Could be useful if you don't know what application name to search for.
+
+    The number of data rows (audit events) per page is configurable by the 'Entries per page' parameter.
 
-    If you want you can also select an additional value filter to limit the results.
-    This server-side filter correspond to the "value" parameter optionally passed to the audit query. 
-    (See http://wiki.alfresco.com/wiki/Auditing_(from_V3.4)#Advanced_Query). This filtering is done server-side
+    Additional server side filters are configurable :
+      UI Name          		Description                                              Audit API corresponding parameter
+      -----------------------------------------------------------------------------------------------------------
+    - value filter		filter on the audit value (exact match,optional)		'value'
+    - limit			maximum number of audit entries retrieved (optional)		'limit'
+    - Additional Query params	other possible query parameters (optional)			from/to time, from/to id, user
+
+    (See http://wiki.alfresco.com/wiki/Auditing_(from_V3.4)#Advanced_Query). This filtering is done server-side.
+
+    The columns to display are also configurable (show/hide).
 
  * Search box
 
@@ -93,6 +106,13 @@ the dashlet into one of the columns from the list of dashlets.
 
 Changelog
 ---------
+0.4:
+    - datatable columns can now be configured to be shown or hidden
+    - an extra field has been added to the config dialog to pass additional server side query parameters.
+	See the wiki documentation (http://wiki.alfresco.com/wiki/Auditing_(from_V3.4)#Advanced_Query) and the web script description.
+    - datatable css fix for google chrome, and various css tweaks
+    - Added help link opposite the config link
+
 0.31:
     - build.properties more consistent with other projects
     - distributed jar had a wrong french bundle filename
@@ -122,4 +142,3 @@ Changelog
 0.2 : search box / query filtering 
 
 0.1 : inital release
-

build.properties

@@ -1,3 +1,3 @@
-build.version=0.31
+build.version=0.4
 project.name=sample-audit-dashlet
 jar.name=${project.name}-${build.version}.jar

build.xml

@@ -92,11 +92,11 @@
 
    <!-- Create required prerequisite directory structure -->
    <target name="prepare" description="Create initial build structures">
-       <mkdir dir="${build.dir}" />
+      <mkdir dir="${build.dir}" />
       <mkdir dir="${dist.dir}" />
    </target>
 
-    <!--
+   <!--
         Assemble the configuration and resource files in a JAR file structure. This mechanism 
         was introduced in Alfresco 3.3 and allows Share extensions containing web scripts, Surf 
         configuration and static assets to be added to the servlet container as shared libraries.
@@ -106,8 +106,8 @@
         
         This target excludes the files custom-slingshot-application-context.xml, share-config-custom.xml
         and similar files as only one of these should be present on the classpath.
-    -->
-    <target name="build-jar" description="Assemble configuration and resource files in a JAR file structure">
+   -->
+   <target name="build-jar" description="Assemble configuration and resource files in a JAR file structure">
         <mkdir dir="${build.jar.dir}" />
         <copy todir="${build.jar.dir}" includeEmptyDirs="false">
             <fileset dir="${config.dir}" includes="${config.includes}" excludes="${config.excludes}" >
@@ -124,28 +124,48 @@
         <yuicompress fromdir="${res.dir}" todir="${build.jar.dir}/META-INF" excludes="**/*-min.js" warn="yuicompress.warn">
             <include name="**/*.js" />
         </yuicompress>
-    </target>
-   
-   <!-- Build the JAR file -->
-    <target name="dist-jar" depends="clean, prepare, build-jar" 
-      description="Build a JAR file containing configuration and resource files">
-      <jar destfile="${dist.dir}/${jar.name}">
-         <fileset dir="${build.jar.dir}" />
-      </jar>
+
+        <jar destfile="${dist.dir}/${jar.name}">
+            <fileset dir="${build.jar.dir}" />
+        </jar>
    </target>
-   
+
+   <!-- Distribute the JAR file -->
+   <target name="dist-jar" depends="clean, prepare, copy-en-l10n-bundles, build-jar, write-sha1sums"
+           description="Distribute the JAR file">
+   </target>
+
+   <target name="copy-en-l10n-bundles" description="Copy the default l10n bundles to the _en locale suffix">
+         <delete>
+            <fileset dir="${config.dir}/alfresco/site-webscripts">
+               <include name="**/*_en.properties" />
+            </fileset>
+        </delete>
+        <copy todir="${config.dir}/alfresco/site-webscripts/org/alfresco/components/dashlets">
+            <fileset dir="${config.dir}/alfresco/site-webscripts/org/alfresco/components/dashlets"/>
+            <mapper type="regexp"
+                 from="^([^_]*).properties$"
+                 to="\1_en.properties"/>
+        </copy>
+        <copy todir="${config.dir}/alfresco/site-webscripts/org/alfresco/modules/dashlets">
+            <fileset dir="${config.dir}/alfresco/site-webscripts/org/alfresco/modules/dashlets"/>
+            <mapper type="regexp"
+                 from="^([^_]*).properties$"
+                 to="\1_en.properties"/>
+        </copy>
+   </target>
+
    <target name="write-sha1sums">
-	<delete file="${dist.dir}/SHA1SUM" quiet="true"/>
-	<tstamp>
+	 <delete file="${dist.dir}/SHA1SUM" quiet="true"/>
+	 <tstamp>
 	    <format property="current.time" pattern="MM/dd/yyyy hh:mm aa"/>
-	</tstamp>
-	
-	<checksum file="${dist.dir}/${jar.name}" format="MD5SUM" algorithm="sha1" property="sha1.jar" readbuffersize="65536"/>
-	<!--Note : we use a readbuffersize of 65536 to generate the same checksums as GNU coreutils (sha1sum, md5sum, ...) -->
+	 </tstamp>
 
-	<echo message="# Generated on ${current.time} ${line.separator}" file="${dist.dir}/SHA1SUM"  append="true"/>
-	<echo message="${sha1.jar}  ${jar.name}${line.separator}" file="${dist.dir}/SHA1SUM"  append="true"/>
+	 <checksum file="${dist.dir}/${jar.name}" format="MD5SUM" algorithm="sha1" property="sha1.jar" readbuffersize="65536"/>
+	 <!--Note : we use a readbuffersize of 65536 to generate the same checksums as GNU coreutils (sha1sum, md5sum, ...) -->
 
+	 <echo message="# Generated on ${current.time} ${line.separator}" file="${dist.dir}/SHA1SUM"  append="true"/>
+	 <echo message="${sha1.jar}  ${jar.name}${line.separator}" file="${dist.dir}/SHA1SUM"  append="true"/>
     </target>
 
     <!--

config/alfresco/site-webscripts/org/alfresco/components/dashlets/audit-application-data.get.desc.xml

@@ -1,6 +1,6 @@
 <webscript>
    <shortname>Audit Application Data Component</shortname>
    <description>Audit Application Data Component</description>
-   <url>/components/dashlets/audit-application/entries?application={application}&amp;valueFilter={valueFilter}&amp;limit={limit}</url>
+   <url>/components/dashlets/audit-application/entries?application={application}&amp;valueFilter={valueFilter}&amp;limit={limit}&amp;additionalQueryParams={additionalQueryParams}</url>
    <format default="json">extension</format>
 </webscript>

config/alfresco/site-webscripts/org/alfresco/components/dashlets/audit-application-data.get.js

@@ -1,20 +1,30 @@
 function main()
 {
-   var application = args.application;   // audit application name (as reported by /api/audit/control
-   var valueFilter = args.valueFilter; // optional : "value" filter on the audit entries. match all
-   var limit = args.limit; //  optional : max entry count retrieved by the repo query
+   var application = args.application;	// audit application name (as reported by /api/audit/control
+   var valueFilter = args.valueFilter; 	// optional : "value" filter on the audit entries. match all
+   var limit = args.limit;		//  optional : max entry count retrieved by the repo query
+
+   // optional : free field to add in other server-side filters (e.g fromTime, ...)
+   var additionalQueryParams = args.additionalQueryParams;
 
    if (application != null)
    {
-      var additionalFilterQuery = valueFilter ? "&value=" + stringUtils.urlEncode(valueFilter) : "";
-      if(logger.isLoggingEnabled()) 
+      var valueFilterQuery = valueFilter ? "&value=" + stringUtils.urlEncode(valueFilter) : "";
+      if(logger.isLoggingEnabled())
 	  logger.log("  application:" +application+ " - " + "valueFilter:" +valueFilter);
 
       var maxEntryCount = limit ? "&limit=" + stringUtils.urlEncode(limit) : "";
+      
+      // decode the '&' param separators from the optional additional params passed in by the dashlet.
+      var optionalAdditionalQueryParams = additionalQueryParams ? ("&" + additionalQueryParams.replace(/\uFFFF/g,'&')) : "";
 
-      var sortOrder =  "&forward=" + false;
+      if(logger.isLoggingEnabled())
+	  logger.log("  optionalAdditionalQueryParams: '" +optionalAdditionalQueryParams+ "'");
+      
+      var sortOrder =  "&forward=" + false; // most recent first
 
-      var uri = "/api/audit/query/"+stringUtils.urlEncode(application)+"?verbose=true" + additionalFilterQuery + sortOrder + maxEntryCount;
+      var uri = "/api/audit/query/"+stringUtils.urlEncode(application)+"?verbose=true"
+		  + valueFilterQuery + sortOrder + maxEntryCount + optionalAdditionalQueryParams;
 
       var connector = remote.connect("alfresco");
       var result = connector.get(uri);
@@ -23,7 +33,7 @@ function main()
 
       if (result.status == status.STATUS_OK)
       {
-	 var rawresponse=result.response+""; // cast rawresponse back into a js string)
+	 var rawresponse = result.response+""; // cast rawresponse back into a js string
 	 //if(logger.isLoggingEnabled()) logger.log("rawresponse:\n"+rawresponse);
 
          // the json outputted by the audit template does not quote user and application keys in the ouput

config/alfresco/site-webscripts/org/alfresco/components/dashlets/audit-application-data.get.json.ftl

@@ -11,7 +11,9 @@
 	    "values":
 	    {
 		<#list e.values?keys as key>
-		    "${key?replace('.*/', '', 'r')}":"${e.values[key]}"
+		    <#-- keep only the audit key for readability -->
+		    <#-- and remove spurious/invalid linebreaks (see ALF-11190) -->
+		    "${key?replace('.*/', '', 'r')}":"${e.values[key]?replace('(\n|\r\n|\r)',' ','r')}"
 		    <#if key_has_next>,</#if>
 		</#list>
 	    }

config/alfresco/site-webscripts/org/alfresco/components/dashlets/audit-application.get.html.ftl

@@ -7,7 +7,12 @@
 	    "application": "${args.application!''}",
 	    "valueFilter": "${args.valueFilter!''}",
 	    "limit": "${args.limit!''}",
-	    "rowsPerPage" : "${args.rowsPerPage!'10'}"
+	    "rowsPerPage" : "${args.rowsPerPage!'10'}",
+            "additionalQueryParams" : "${args.additionalQueryParams!''}",
+            "show_id_column" : "${args.show_id_column!'show'}",
+            "show_user_column" : "${args.show_user_column!'show'}",
+            "show_time_column" : "${args.show_time_column!'show'}",
+            "show_values_column" : "${args.show_values_column!'show'}"
 	}).setMessages(${messages});
 
     <#-- dashlet resizer does not dynamically adjust the number of rows displayed on the page re: pagination -->
@@ -28,21 +33,30 @@
     <#-- audit only allows admin to query audit entries. therefore the dashlet is only usable by admin users. -->
     <#if userHasConfigPermission && userIsAdmin>
     <div class="toolbar" id="${el}-toolbar">
-	<a class="theme-color-1" href="#" id="${el}-configure-link">${msg("audit.dashlet.link.configure")}</a>
+         <span class="yui-button-align">
+            <span class="first-child">
+		<a class="theme-color-1" href="#" id="${el}-configure-link">${msg("audit.dashlet.link.configure")}</a>
+	    </span>
+	 </span>
+         <span class="align-right yui-button-align">
+            <span class="first-child spaced-more-left">
+		<a class="theme-color-1" href="${msg("audit.dashlet.link.help.url")}" id="${el}-help-link" target="_blank">${msg("audit.dashlet.link.help")}</a>
+	    </span>
+	 </span>
     </div>
 
     <#assign currentHeight=default_height>
     <#if args.height??><#assign currentHeight=args.height></#if>
 	<div class="body" style="height: ${currentHeight}px;" id="${el}-body">
-	    <div class="message" id="${el}-message"></div>
+	    <div class="message spaced-left" id="${el}-message"></div>
 
-	    <div class="markup" id="${el}-searchbox">
+	    <div class="markup spaced-left" id="${el}-searchbox">
 		<#-- search box to filter audit values from YUI --> 
 		<label id="${el}-searchWithinResultsFilterLabel" for="${el}-searchWithinResultsFilter">${msg("audit.dashlet.searchWithinResults",0)} :</label> 
 		<input type="text" id="${el}-searchWithinResultsFilter">
 	    </div>
 
-	    <div class="entries customScrollableList" id="${el}-entries"></div>
+	    <div class="entries custom-scrollable-list" id="${el}-entries"></div>
 	</div>
 
     <#else>

config/alfresco/site-webscripts/org/alfresco/components/dashlets/audit-application.get.properties

@@ -1,6 +1,8 @@
 audit.dashlet.header.default=Audit Dashlet
 
 audit.dashlet.link.configure=Configure
+audit.dashlet.link.help=Help
+audit.dashlet.link.help.url=http://code.google.com/p/share-extras/wiki/SampleAuditDashlet
 
 audit.dashlet.notConfigured=No application is configured
 audit.dashlet.notFound=The application could not be found
@@ -12,11 +14,11 @@ audit.dashlet.filteredResults={0} results ({1} filtered out)
 audit.dashlet.invalidSearch=Invalid search expression
 audit.dashlet.adminPrivilegesRequired=You need to be an admin user to query audit entries
 
-audit.dashlet.th.id=ID
-audit.dashlet.th.application=Application
-audit.dashlet.th.user=User
-audit.dashlet.th.time=Timestamp
-audit.dashlet.th.values=Audited Values
+audit.dashlet.field.label.id=DB ID
+audit.dashlet.field.label.application=Application
+audit.dashlet.field.label.user=User
+audit.dashlet.field.label.time=Timestamp
+audit.dashlet.field.label.values=Audited Values
 
 # Pagination
 audit.dashlet.firstPageLinkLabel=<< first

config/alfresco/site-webscripts/org/alfresco/components/dashlets/audit-application.get_en.properties

@@ -0,0 +1,28 @@
+audit.dashlet.header.default=Audit Dashlet
+
+audit.dashlet.link.configure=Configure
+audit.dashlet.link.help=Help
+audit.dashlet.link.help.url=http://code.google.com/p/share-extras/wiki/SampleAuditDashlet
+
+audit.dashlet.notConfigured=No application is configured
+audit.dashlet.notFound=The application could not be found
+audit.dashlet.loading=Loading ...
+audit.dashlet.noEntries=No matching entries found
+audit.dashlet.searchWithinResults=Search within the {0} results
+audit.dashlet.valuefilteredOn=filtered on
+audit.dashlet.filteredResults={0} results ({1} filtered out)
+audit.dashlet.invalidSearch=Invalid search expression
+audit.dashlet.adminPrivilegesRequired=You need to be an admin user to query audit entries
+
+audit.dashlet.field.label.id=DB ID
+audit.dashlet.field.label.application=Application
+audit.dashlet.field.label.user=User
+audit.dashlet.field.label.time=Timestamp
+audit.dashlet.field.label.values=Audited Values
+
+# Pagination
+audit.dashlet.firstPageLinkLabel=<< first
+audit.dashlet.previousPageLinkLabel=< prev
+audit.dashlet.nextPageLinkLabel=next >
+audit.dashlet.lastPageLinkLabel=last >>
+audit.dashlet.pageReportTemplate={startRecord} - {endRecord} of {totalRecords}