cancel
Showing results for 
Search instead for 
Did you mean: 

4.0 Reusing existing Alfresco components for a customization

loftux
Star Contributor
Star Contributor
I've read David Drapers excellent posts on the new extensibility features coming in 4.0.
There is one scenario I cannot figure out how to do. I want to reuse existing components, one could be to implement the categories tree in Site documentlibrary, my particular test case was to add the preview to the edit-metadata page.
What I did was
-added site-data/extension/edit-metadata-preview.xml with content
<extension>
   <modules>
      <module>
         <id>Edit Metadata with Preview</id>
         <description>Adding document preview to edit metadata page</description>
         <customizations>
            <customization>
               <targetPackageRoot>org.alfresco</targetPackageRoot>
               <sourcePackageRoot>se.loftux</sourcePackageRoot>
            </customization>
         </customizations>
         <components>
            <component>
               <region-id>metadata-web-preview</region-id>
               <source-id>edit-metadata</source-id>
               <scope>template</scope>
               <sub-components>
                  <sub-component id="metadatapreview" index="25">
                     <url>/components/preview/web-preview</url>
                     <properties>
                        <nodeRef>{nodeRef}</nodeRef>
                     </properties>
                  </sub-component>
               </sub-components>
            </component>
         </components>
      </module>
   </modules>
</extension>
- added templates/se/loftux/edit-metadata.ftl with content
<@region id="metadata-web-preview" target="edit-metadata" action="after" scope="template" />
-deployed the extension module.

The customization ftl is picked up, but what I get when rendering is: <div id="unbound-region-metadata-web-preview">
So something is wrong with my component declaration. What am I missing?
12 REPLIES 12

ddraper
World-Class Innovator
World-Class Innovator
Hi,

There's a few things that you've got slightly wrong here - but since the blogs haven't actually covered these issues it's not surprising !

First of all, the extension mechanism (i.e. what you specify in an extension configuration file) does NOT allow you to define a new Component, only extensions to an existing Component. This means that you'll need to define your Component in a separate file, for example - create a file called "global.metadata-web-preview" containing the following and place it in the "alfresco.site-data.components" package/directory:

<component>
   <region-id>metadata-web-preview</region-id>
   <source-id>global</source-id>
   <scope>global</scope>
   <url>/components/preview/web-preview</url>
   <properties>
      <nodeRef>{nodeRef}</nodeRef>
   </properties>
</component>

You'll also notice that I've made this a "global" scope component. Although you're extending a template to add the "metadata-web-preview" region you are not able to defined a "template" scope component (a template scope component is defined in the XML configuration associated with the template). This means that you'll need to also change the scope setting in your template extension, e.g.

<@region id="metadata-web-preview" target="edit-metadata" action="after" scope="global" />

Once you've done this your new region will be able bind to your new Component and you'll see the preview (I've actually done this myself just to check!)

The other way in which you could have achieved this was to define a new Sub-Component within the "edit-metadata" Component. That way you could have done everything within your extension configuration file and not needed the template customization to add a new region.

Hope this helps - let me know if not!

Regards,
Dave

loftux
Star Contributor
Star Contributor
Thanks Dave,
this cleared up a few things.
What I wanted to do is to create as few new files as possible. There are already quite a number of files to wire up a page  :wink: , so if you could achieve it with config only that would be great. I realise that this example would need more files anyway, beacuse you typically would want the preview on the right of your form.
As you said, adding as a subcomponent to edit-metadata shows preview with only config.
<extension>
   <modules>
      <module>
         <id>Edit Metadata with Preview</id>
         <description>Adding document preview to edit metadata page</description>
         <components>
            <component>
               <region-id>edit-metadata</region-id>
               <source-id>edit-metadata</source-id>
               <scope>template</scope>
               <sub-components>
                  <sub-component id="metadatapreview" index="200">
                     <url>/components/preview/web-preview</url>
                     <properties>
                        <nodeRef>{nodeRef}</nodeRef>
                     </properties>
                  </sub-component>
               </sub-components>
            </component>
         </components>
      </module>
   </modules>
</extension>
If I had index="25" the preview rendered before the form, changed to 200 it is rendered after (now know what the index is for  Smiley Happy ). So what is the default index for a component, SurfBug didn't show that (or i didn't look close enough)?

ddraper
World-Class Innovator
World-Class Innovator
The index is shown in SurfBug but ONLY if it is non-default. I made this decision because although the default default is 50 (two intentional defaults there) it could be changed and I wanted SurfBug to indicate a default value by NOT displaying anything (because the default index could be manually set)… hope that makes sense - I've possibly overused the word "default" in that last sentence!  Smiley Happy

I think the Blog post does mention index briefly but doesn't go into a lot of detail… it was something of a balance trying to keep the articles concise but contain enough depth. I'll probably start writing some more in-depth articles as I get more feedback - and of course this is only a temporary substitution for the official documentation that will get released with Alfresco Enterprise.

The configuration you've included looks correct and you've indicated it's working, so I just want to check if there's anything else I can help with?

I really appreciate your feedback on the Blogs - it's good to know people are trying this stuff out !!

Regards,
Dave

loftux
Star Contributor
Star Contributor
Yes, that works. So now we have two different ways of adding the preview. The next step would be to add some positioning.
<div class="yui-gc">
   <div class="yui-u first>Existing edit-metadata component goes here</div>
   <div class="yui-u>New preview component goes here</div>
</div>
I know how I would do the "old way"
- add the new component to site-data/template-instances/edit-metadata.xml
- update templates/org/alfresco/edit-metadata.ftl to include new component and positioning (Since there is yui positioning in forms, I know it may not work with the above suggested positioning)

So as a theoretical example, how would you go about to do this customization? Not asking for an exact solution, just think it is an interesting use case.
-maybe the new extension framework is not a fit here, and the "old way" is better?

ddraper
World-Class Innovator
World-Class Innovator
One way you could do this would be to add the additional <div> elements in via Sub-Components. For example…

Sub-Component 1 could add:
<div class="yui-gc">
   <div class="yui-u first>
…before the default Sub-Component for edit metadata, and then Sub-Component 2 could add…
</div>
   <div class="yui-u>
Sub-Component 3 would reference the preview WebScript and then Sub-Component 4 could add…
   </div>
</div>
…to close off the DIV elements (obviously you'd need to create the WebScripts for adding the opening and closing DIV elements).


You could also achieve the same thing via customizations (e.g. adding in new <@region> directives to the template). If you wanted to have custom CSS you could insert this via a .head.get.ftl WebScript file in one of your new WebScripts, or there is another mechanism that I haven't blogged about yet that allows you to add additional dependencies in an extension as follows:

<customizations>
    <customization>
        <targetPackageRoot>org.alfresco</targetPackageRoot>
        <sourcePackageRoot>org.thirdparty.extension</sourcePackageRoot>
        <dependencies>
            <css>/res/dependencies/addition_styles.css</css>
        </dependencies>
    </customization>
</customizations>

I should hopefully get around to blogging about this dependency extension mechanism soon,

Hope this helps!

Regards,
Dave

loftux
Star Contributor
Star Contributor
Thanks,
I actually tried your suggestion with sub-components, but since a component also renders a a div, it closes the yui opening div. Also tried doing
</div><div class="yui-gc">
   <div class="yui-u first><div>
to "neutrialize" the component div, but ended up with a div mess that made Adobe Muse look good  Smiley Very Happy
Next will be to try the customization way.

Here is another scenario:
I want to reorder the action and info panels in document-details, my preference is that document-metadata comes first.
We have in document-details.ftl
         <div class="yui-u">
            <@region id="document-actions" scope="template"/>
            <@region id="document-tags" scope="template"/>
            <@region id="document-links" scope="template"/>
            <@region id="document-metadata" scope="template"/>
            <@region id="document-permissions" scope="template"/>
            <@region id="document-workflows" scope="template"/>
            <@region id="document-versions" scope="template"/>
            <@region id="document-publishing" scope="template"/>
         </div>
Each is declared as its own component. If we instead would in template-instance/document-details.xml would have just one component "document-panels" with each of the above components as a sub-component, am I right to assume that I could just have re-ordered them with index declaration in my extension module?
Now it isn't, so is there another way for a simple re-order?

Lots of questions here, if you dont find time to answer now, I'll bring them to Devcon.

ddraper
World-Class Innovator
World-Class Innovator
I haven't tried the Sub-Component approach, but I'd made the assumption that because the Component and Sub-Component Chrome <div> elements are paired that it would be possible to insert the additional <div> elements required… I would have hoped this was possible and will try it out later and add another post.

However, regarding to the re-ordering of the document details template… if you just want to move a single region then it should be possible to use a template customization to remove the original region and then add it back in in a different location. Again, I have to confess that I haven't had the opportunity to try this out yet but thought I'd make the suggestion if you wanted to try it out before I get the chance. Providing you remove the region before you add it back again I think this should work but you're coming up with some reasonably complex use cases that we hadn't necessarily considered.

We did consider adding support for indices on the <@region> directive, but one of the objectives of the extensibility work was to not destabilize the existing Share code with significant re-writes. This meant that we couldn't rewrite Share to either add indices to the <@region> directives in the existing templates or use Sub-Components… instead we opted for Surf to be able to handle the conversion of the "legacy" code to the new style.

Happy to answer any questions either on the forums or at DevCon (I'll be at both San Diego and London)… all of the use cases you're providing are very useful!

Regards,
Dave

loftux
Star Contributor
Star Contributor
Some re-ordering tests done,
with a customization in se/loftux/document-details.ftl
<@region id="document-metadata" target="document-metadata" action="remove" scope="template" />
<@region id="document-metadata" target="document-tags" action="before" scope="template" />
metadata is moved as you would expect before tags and after actions.
However, if I want to move it first and do
<@region id="document-metadata" target="document-metadata" action="remove" scope="template" />
<@region id="document-metadata" target="document-actions" action="before" scope="template" />
metadata not only moves before "document-actions", but moves another step in the components hierarchy and after comments, thus breaking out of div placements tags. So the before "document-actions" actually becomes after "comments", and the "document-metadata" renders below the comments, not in the right pane.  Not sure if I would say this is a bug.

But this works!
<@region id="document-metadata" target="document-metadata" action="remove" scope="template" />
<@region id="document-metadata" target="document-tags" action="before" scope="template" />
<@region id="document-actions" target="document-actions" action="remove" scope="template" />
<@region id="document-actions" target="document-tags" action="before" scope="template" />
This change would have been far easier with just swapping places of the components in the original ftl, but I definitely see the advantages where you can deploy/undeploy (in this case if you don't like my re-ordering, just un-deploy), or that you can use evaluators for when you extension will kick in.

ddraper
World-Class Innovator
World-Class Innovator
Thanks for testing that out… it does sound like there might be a bug in there, I'll do some investigation when I next get a chance.

The other advantage of doing it this way is that you can use a module evaluator to only apply the change in specific circumstances (e.g. specific sites, users, etc). I have to admit this wasn't something that I'd necessarily expected anyone to do, but it's good that you've found another use for it! Smiley Happy