In Share, when I need to alter default functionality I start with looking into the page I need to change, and then find out how this page is called, and if I can add parameters or need to change javascript. In this case it is page/site/{site}/edit-metadata that I somehow need to tell to use a different form. This page use template-instances/edit-metadata.xml, and in there is a form component

<!-- Edit Metadata Form -->
<component>
  <region-id>edit-metadata</region-id>
  <url>/components/form</url>
  <properties>
    <itemKind>node</itemKind>
    <itemId>{nodeRef}</itemId>
    <mode>edit</mode>
    <submitType>json</submitType>
    <showCaption>true</showCaption>
    <showCancelButton>true</showCancelButton>
  </properties>
</component>

The form is rendered using the webscript /components/form, now I need to find out if there is a way to pass in a form id. I then look in folder site-webscripts/org/alfresco/components/form/ to find out how the form generation works, form.get.html.ftl includes form.lib.ftl and in there I can see that you can pass formId as an argument. I can now either alter template-instances/edit-metadata.xml, or use the new Surf extensibility functionality (from version 4.0). With a surf extension i add to site-data/extension a file called myextension.xml with content

<extension>
	<modules>
		<module>
			<id>ReplaceForm</id>
			<description>Show edit metadata for specific form</description>
			<components>
				<component>
					<scope>template</scope>
					<region-id>edit-metadata</region-id>
					<source-id>edit-metadata</source-id>
					<sub-components>
						<sub-component id="default">
							<evaluations>
								<evaluation id="hide">
									<render>false</render>
								</evaluation>
							</evaluations>
						</sub-component>
						<sub-component id="edit-metadata-new" index="25">
							<url>/components/form</url>
							<properties>
								<itemKind>node</itemKind>
								<itemId>{nodeRef}</itemId>
								<formId>{formId}</formId>
								<mode>edit</mode>
								<submitType>json</submitType>
								<showCaption>true</showCaption>
								<showCancelButton>true</showCancelButton>
							</properties>
						</sub-component>
					</sub-components>
				</component>
			</components>
		</module>
	</modules>
</extension>

I will not go into details about surf extension, instead watch the Alfresco Webinar about Surf extension with David Draper and read the slides. What happens when this customization is applied is that the default component is replaced by one that can take formId as url parameter. You can easily test this (when above extension is applied) by navigating to page edit-metadata and in the end of the url add &formId=doclib-simple-metadata. You will se the form that is normally just used for the popup edit metadata dialog in the full page edit.

So now I need a way to call this page with the formId parameter. The edit-metadata page is opened using a document library action, so I need to append the formId parameter if (and only then) the aspect in question is used. From version 4.0 this is in configuration that you can easily alter. The default config for actions is found in share/WEB-INF/classes/alfresco/share-documentlibrary-config.xml. From there I came up with this config that you can put in share-config-custom.xml

  <config evaluator="string-compare" condition="DocLibActions">
    <!-- Action definitions -->
    <actions>
      <action id="document-edit-metadata" type="pagelink" label="actions.document.edit-metadata">
        <param name="page">edit-metadata?nodeRef={node.nodeRef}</param>
        <permissions>
          <permission allow="true">Write</permission>
        </permissions>
        <evaluator negate="true">evaluator.doclib.action.isLocked</evaluator>
        <override>document-edit-properties</override>
      </action>
      <action id="document-edit-metadata-diarie" type="pagelink" label="actions.document.edit-metadata">
        <param name="page"><![CDATA[edit-metadata?nodeRef={node.nodeRef}&formId=diarie]]></param>
        <permissions>
          <permission allow="true">Write</permission>
        </permissions>
        <evaluator>evaluator.isDiarieNotLocked</evaluator>
        <override>document-edit-metadata</override>
        <override>document-edit-properties</override>
      </action>
    </actions>

    <!-- Action Group definitions -->
    <actionGroups>
      <actionGroup id="document-browse">
        <action index="130" id="document-edit-metadata" />
        <action index="130" id="document-edit-metadata-diarie" />
      </actionGroup>
      <actionGroup id="document-details">
        <action index="120" id="document-edit-metadata-diarie" />
      </actionGroup>
    </actionGroups>
  </config>

It does two things, first I replace the popup metadata edit in browse mode, I want the full page. So that is why the default config for action ‘document-edit-metadata’ is added. I cannot only add this action to Action group definitions, because then you will see both, that is why I redefine the action, but now with an override to hide document-edit-properties if used. Next is to add my new action ‘document-edit-metadata-diarie’ that has the formId parameter. Note that it needs enclose the parameter in CDATA to be valid xml. If the evaluator returns true, then use this one and override the others. So next we need to define the evaluator.isDiarieNotLocked. Default evaluators can be found in share/WEB-INF/classes/alfresco/slingshot-documentlibrary-context.xml. Put yours in a mycustom-context.xml file in the class-path.

  <bean id="evaluator.hasdiariefordaspect" parent="evaluator.doclib.action.hasAspect">
    <property name="aspects">
      <list>
        <value>lx:diarieFord</value>
      </list>
    </property>
  </bean>
  <bean id="evaluator.isNotLocked" parent="evaluator.doclib.action.chainedMatchOne">
    <property name="evaluators">
      <list>
        <ref bean="evaluator.doclib.action.notEditable" />
      </list>
    </property>
    <property name="negateOutput" value="true" />
  </bean>
  <bean id="evaluator.isDiarieNotLocked" parent="evaluator.doclib.action.chainedMatchAll">
    <property name="evaluators">
      <list>
        <ref bean="evaluator.hasdiariefordaspect" />
        <ref bean="evaluator.isNotLocked" />
      </list>
    </property>
  </bean>

So my evaluators does this, evaluator.hasdiariefordaspect checks that is has the required aspect, evaluator.isNotLocked evaluates if it can be edited and is not locked (this one propbably can be defined in a smarter way, but it works), then finally put together in evaluator.isDiarieNotLocked where we need both previous evaluators to be true. If you want to learn more about Share Document library extension read Mike Hatfields blog.

And finally we have customized Share to use a specific form for edit metadata when the document has the selected aspect applied. With only configuration files!

Note that my approach lets user with a bit of knowledge add whatever form id they want in the url, and thus potentially edit hidden metadata. In this use case it was not considered an issue.

This is a very nice feature, that just works. But there are some problems with this. First there is no indication in Share forms that this happens, there should at least be visual indication that it is. Second problem is that the title and description properties are not just used for documents, they are user for many other components in Alfresco. I have done some testing, and I have found that Site name and description, Blog posts title, Discussion topic title, Data List name and description, and Data List entry name and description will show different texts depending on locale if it has been edited with different locale. Again this only happens if edited with a different locale, probably not happening so many times that a Discussion is edited with different locales, but that Site Managers from different countries change Site title and description is not unlikely.

It was a client of mine that first noticed this behavior, and I filed a bug ALF-3756 in July 2010. My initial reaction was that users should not see different things, and that is was because user user different browsers, and that this should be fixed. As it turns out, it is not because of different browsers, it is because of different locale preference set in different browsers. It was recently fixed in HEAD, so happily testing this out, nothing had changed and the behavior is the same. So i filed a regression bug ALF-11166, but after thinking of the multilingual behavior, it may be that it is not a bug after all, and this is why I’m writing this post.

I’ve thought of ways to fix this, one could be that you change the property definition of cm:title and cm:description in the data model from d:mltext to d:text. Some limited testing shows that this work, a property will stay multilingual (d:mltext) until next edit, then it is saved as d:text, and all user see the same thing regardless of locale. Changing the default model is nothing I recommend, and I only did very limited testing just to see what happened. And this is probably not the way to fix this, because it removes a nice feature. Alfresco is very locale (I18N for the hardcore) aware, you can localise almost everything, and from 4.0 property lists (constraints) can be localized. So the very fact that you can have a Site title and description in different locale is a good thing.

So the proper fix for this is to visually indicate what is going on in all forms and dialogs. It can be implemented in steps if not the full approach can be taken at once

1. Create a control with flag corresponding to the locale used, so that you visually see what locale is currently being edited.
2. Change the control so that you can list other values to see base language and the current values for other locales. That way you can keep track of translations and keep them in sync.

I created (or actually updated existing text controls) and then it looks like this for multilingual properties

Full details on how I did this is in the issue ALF-11166. Its a simple first step with just editing the control freemarker templates, a more complete solution would be as I outlined the possibility to list all added values for different languages. Let me know what you think.

Functionality

• All standard functionality in CKEditor.
• Loading of custom configuration files
• Insert images directly form Alfresco Share site

For form in Alfresco Share it is easy to create new controls. In this case you just tell Share form to use the new control

<appearance>
   <field id="cm:content">
      <control template="/org/alfresco/components/form/controls/ckeditor.ftl">
         <control-param name="forceEditor">true</control-param>
      </control>
   </field>
</appearance>

The actual control including source code can be downloaded from Share Extras project. More on how to configure forms on Alfresco Wiki
To install, copy the file ckeditor-form-control-0.1.jar to tomcat/webapps/share/WEB-INF/lib. Then change the form definitions as outlined above or copy the file ckeditor-config-custom.xml (remove .sample file ending) to tomcat/shared/classes/alfresco/web-extension and restart.

If you would like to use custom configuration file you can tell the control what config file to load with

<control-param name="settingsfile">components/editors/ckeditor/my-config.js</control-param>

The path should start without / and point to the location where you put your file. If you create a nice config file I can include it as an option file if you send it to me. Planning to add som custom config files in the future. More on how to configure CKEditor

To browse for images, click “browse on server” and you will get a list of thumbnails. I based it on the Images dashlet, so of course you can click on an image to get a large preview. To select an image, click on the filename.

<config evaluator="aspect" condition="my:customaspect">
	<forms>
		<form>
			<appearance>
				<field id="my:customtextfield" set="mycustomset" mandatory="true">
					<control template="/org/alfresco/components/form/controls/autocomplete.ftl">
						<control-param name="ds">/share/service/ds/autocomplete/alfrescoperson />
					</control>
				</field>
			</appearance>
		</form>
	</forms>
</config>

Now you have the looks of you aspect defined, now you will have to add when to display your custom aspect.

>
<config evaluator="node-type" condition="my:customtype">
	<forms>
		<form>
			<field-visibility>
				<show id="sys:node-dbid" />
				<show id="my:customaspect" />
				...

It will display if you add that aspect to your document for that particular custom type. As you can see it should not go into the appearence tag in node-type evaluator. For properties specific for that document type on the other hand, appearance should be placed there. As you can see I also use a custom set to group and to put a label for the aspect above (mycustomset). You will have to assign it under the aspect-evaluator. What you will have to do is for each document type create an appearance tag for the custom set you want to use.

<set id="mycustomset" appearance="bordered-panel" label="Company Inc. - My Custom Type" />

I have used the label to clearly identify what type of document you current document is (My Custom Type in this case).
As you can see i’ve used sys:node-dbid, that is the internal number sequence Alfresco assigns a document, and works perfectly as a dokument-id. However, we need a better label than the default one. You can get that by adding to your node-type evaluator for you custom type

<appearance>
       <field id="sys:node-dbid" read-only="true" set="mycustomset" label="Document ID" />

The forms enginge uses the data models message resource bundle to know what labels to put for each metadata field. So create this file together with you model file if you want you property sheet to be multi-lingual. It should be possible to create resource bundles that is used by the forms engine so that you dont need to hardcode for example “Document ID” as I did. I have yet to find out where to put those files, have to come back to that.
The end result could be something like this: