Wednesday, October 28, 2009

Configuring Alfresco Share's "Change Type" Dialogue

A quick summary of the configuration of "Change Type" Document Action.

***************************************************
Environment:

Testing on Alfresco Labs 3.2
Application server: tomcat 6.0.18
OS: Ubuntu 9.04 x64
Linux kernel: 2.6.28-11-server

***************************************************


Code Trace


The values for the "Change Type" document action are driven from a slingshot webscript. The code trace goes as follows:

1. Share executes the change-type webscript from /share/service/script/org/alfresco/modules/documentlibrary/change-type.get

2. Within the js for the above webscript, there is a remote call to the types webscript from /alfresco/service/slingshot/doclib/types/node/{store-type}/{store_id}/{id}

3. The configuration file for this webscript is types.get.config.xml. The configurations are entered into an overridden version of this file. In the future, this configuration will be rolled into a centralized Share configuration file.

It appears that only static references are currently allowed, but it would be nice to see either some sort of model-based attribute that can allow for inherited values or webscript-based dynamic include.

an example modification would be the addition of:

<type name="ts:doc">
<subtype name="ts:webasset"/>
</type>

"ts:doc" = the qualified content type name
"ts:webasset" = the qualified target type name

Although it may be obvious, when the document being viewed matches the qualified content type, the available subtypes will populate the "Change Type" drop-down list.

It doesn't appear that the name could be re-labeled into a more human-readable form. The code only takes the name attribute of the subtype element and passes that directly into the freemarker template which replaces the ":" with "_". Hopefully there will be a labeling system implemented in the future as well. If not, it wouldn't be a complex modification to the ootb javascript to allow for the inclusion of the text value of the subtype element. That would allow a label to be included as follows:

<subtype name="ts:webasset">ThoughtSpring Web Asset</subtype>

Code Deployment


I have created my own copy of types.get.config.xml within my Alfresco development project. I deployed this file to the Alfresco server's tomcat classloader, which is where (ideally) all Alfresco customizations will live.

I'm using an ant scp task to copy my file to the following directory:

/shared/classes/alfresco/extension/templates/webscripts/org/alfresco/slingshot/documentlibrary

At this point, you'll need to restart Alfresco to allow tomcat to load the file.

Monday, October 19, 2009

Creating a custom WCM form widget in Alfresco using Dojo -- part 4

The third implementation example of my creation of a new dojo form widget. This is a summarized example.

Please feel free to add any comments and suggestions.

***************************************************
Alfresco-based resources:
http://wiki.alfresco.com/wiki/Forms_Authoring_Guide - Details on incorporating widgets into an xsd
http://wiki.alfresco.com/wiki/Creating_XForms_Widgets - Details on creating XForms Widgets


***************************************************
Environment:

Testing on Alfresco Labs 3.2
using the embedded dojo version 0.4.1
Application server: tomcat 6.0.18
OS: Ubuntu 9.04 x64
Linux kernel: 2.6.28-11-server
Using a custom xsd, created to group together multiple elements and leverage custom widgets
***************************************************
Implementation Example 3:

This example adds the real flavor to the custom widget: the custom logic. Up until now, we have created a placeholder for the new widget & prepared our development environment (e.g., logging et al).

During this example we will add jquery as well as dependent elements to our wcm form.

1) jQuery Integration
2) Using ajax to retrieve repository values via a custom webscript
3) Iterating across widgets to tie together parent and child elements
4) Issues around setValue and how to ensure the required flag is set

1) jQuery Integration

I decided to leverage jQuery simply because there are a number of jQuery related features I could see becoming valuable within the context of a WCM form. Besides appending jQuery UI elements, the toolkit's encapsulated functionality drastically reduces the overhead of ajax.

There are a few issues of which to be aware during the jQuery integration. First, the default jQuery namespace shortcut (i.e., "$") has the tendency of conflicting with other customizations and/or toolkits. The proper jQuery namespace should be unique in all cases, but the shortcut must be renamed as there are conflicts with Alfresco's MooTools toolkit.

2) Using Ajax to retrieve repository values via a custom webscript

A custom webscript takes xml content from a specific node and then returns a JSON object. The callback function will expect the JSON object and iterate over it. The naming of the objects in the JSON result will conform to the widget's names.

3) Iterating across widgets to tie together parent and child elements

In order to apply the correct values to the correct widgets, the script must dynamically determine the mapping. When a match is found, the value must be applied.

4) Issues around setValue and how to ensure the required flag is set

When applying the value to the dependent widget, make sure to pass the 'true' argument in the setValue method. If you don't pass that argument, the requirement flag won't be satisfied for the widget, if it is set.

Please contact me if you require specific implementation information.

***************************************************
Existing JIRA issues regarding this process:

https://issues.alfresco.com/jira/browse/ALFCOM-332 -- states that the ootb xforms.js must be touched instead of having an external overriding copy as would be the usual method of overridding and extending.

Monday, October 5, 2009

Creating a custom WCM form widget in Alfresco using Dojo -- part 3

The second implementation example of my creation of a new dojo form widget.

Please feel free to add any comments and suggestions.

***************************************************
Alfresco-based resources:
http://wiki.alfresco.com/wiki/Forms_Authoring_Guide - Details on incorporating widgets into an xsd
http://wiki.alfresco.com/wiki/Creating_XForms_Widgets - Details on creating XForms Widgets


***************************************************
Environment:

Testing on Alfresco Labs 3.2
using the embedded dojo version 0.4.1
Application server: tomcat 6.0.18
OS: Ubuntu 9.04 x64
Linux kernel: 2.6.28-11-server
Using the WCM form created from Dr. Q's Web Form tutorial (http://drquyong.com/myblog/?p=116), the "advanced-press-release" form
***************************************************

Implementation Example 2:

For the next example, I wanted to verify appended code in the xforms.js file. This time I will duplicate an existing javascript class and rename it.

Step 1: Update xforms.js
Step 1.1: Create a backup copy of /scripts/ajax/xforms.js
Step 1.2: In a modified copy of the file, copy the entire javascript class for ComboboxSelect:

alfresco.xforms.ComboboxSelect1 = alfresco.xforms.AbstractSelectWidget.extend({
......
});

Step 1.3: Paste the same block of code under the existing class; rename the class:

alfresco.xforms.ComboboxSelect2 = alfresco.xforms.AbstractSelectWidget.extend({
......
});

Step 1.3: Overwrite /scripts/ajax/xforms.js with the modified copy

Step 2: Update web-client-config-wcm.xml
Step 2.1: Update the widget created in the previous example to point to our new javascript class:



Step 2.2: Overwrite /WEB-INF/classes/alfresco/web-client-config-wcm.xml with the modified copy

Step 3: Restart Alfresco

Step 4: Verify update
Step 4.1: Open Form in web project
Step 4.2: Expand the Keyword section of the form
Step 4.3: Click on the + symbol to add a Keyword node to the form
Step 4.4: Verify that the form renders as a drop-down list with four or less elements, then we can be confident that the code is working.

*** Blocked: When I attempt to verify, I cannot get the widget to show in the form. Clicking on the + button does appear to add an element to the Keyword group, but that element is blank. Also, clicking on the + for the Keyword group causes all events to freeze on the form. None of the other + or - buttons on the form work at this point.

[updated 10/12/09]
*** Unblocked: Although I did restart the app server (i.e., tomcat) multiple times, alfresco didn't render the control. However, the next day the widget was working correctly. I believe it was a caching issue on the browser itself. It took a full shutdown & restart of my laptop (and subsequently, my browser) to re-cache all files.

My current explaination is that the xforms.js was cached on the local browser. So, when the xforms/chiba engine rendered the webform into our new javascript class, the included javascript file was outdated & didn't contain the new class.

***************************************************

[updated 10/12/09]
The following are some OOTB defined loggers:

#This is the logger for alfresco web scripts; specifically, the logger.log() function
log4j.logger.org.alfresco.repo.jscript.ScriptLogger=debug
#This is the logger for dojo widgets; specifically, the alfresco.log() function
#note that this logger alters the appearance of the web form by appending each widget's div id to the label
log4j.logger.org.alfresco.web.forms=debug

#Other loggers of note; I will attempt to update these as necessary
log4j.logger.org.alfresco.web.scripts.AlfrescoScriptDebugger=off
#An X11 server-side javascript debugger which will allow code breaks and stepping through code during run-time.
log4j.logger.org.alfresco.repo.web.scripts.AlfrescoRhineScriptDebugger=off
log4j.logger.org.alfresco.web.scripts=warn
log4j.logger.org.chiba.xml.xforms=info
log4j.logger.org.alfresco.web.forms.xforms.XFormsBean=info
log4j.logger.org.alfresco.repo.jscript=info
log4j.logger.org.alfresco.web.config.forms=info
log4j.logger.org.alfresco.repo.forms=info
log4j.logger.org.alfresco.web.forms.xforms.XSLTRenderingEngine=info
log4j.logger.org.alfresco.web.scripts.ScriptLogger=warn

***************************************************
Existing JIRA issues regarding this process:

https://issues.alfresco.com/jira/browse/ALFCOM-332 -- states that the ootb xforms.js must be touched instead of having an external overriding copy as would be the usual method of overridding and extending.