nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

As we transition to the new Hyland Community, some post links may be temporarily disrupted as we finalize redirects. We apologize for the inconvenience and are working to resolve this as quickly as possible. Details.

4.0 Reusing existing Alfresco components for a customization

loftux

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?

Find more posts tagged with

Comments

ddraper

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

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

, 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>
&nbsp;&nbsp; <modules>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <module>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <id>Edit Metadata with Preview</id>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <description>Adding document preview to edit metadata page</description>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <components>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <component>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <region-id>edit-metadata</region-id>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <source-id>edit-metadata</source-id>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <scope>template</scope>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <sub-components>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <sub-component id="metadatapreview" index="200">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <url>/components/preview/web-preview</url>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <properties>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <nodeRef>{nodeRef}</nodeRef>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </properties>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </sub-component>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </sub-components>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </component>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </components>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </module>
&nbsp;&nbsp; </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

). So what is the default index for a component, SurfBug didn't show that (or i didn't look close enough)?

ddraper

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!

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

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

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

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">
&nbsp;&nbsp; <div class="yui-u first><div>‍‍

to "neutrialize" the component div, but ended up with a div mess that made Adobe Muse look good

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

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <div class="yui-u">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <@region id="document-actions" scope="template"/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <@region id="document-tags" scope="template"/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <@region id="document-links" scope="template"/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <@region id="document-metadata" scope="template"/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <@region id="document-permissions" scope="template"/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <@region id="document-workflows" scope="template"/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <@region id="document-versions" scope="template"/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <@region id="document-publishing" scope="template"/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </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

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

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

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!

erikwinlof

> 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?

Yes you are absolutely right, using a "document-panels" approach would have been the best solution. The reason we didn't is, as David said, that we wanted to make the effort of upgrading as easy as possible, at least where it was possible. Preserving the region id's meant that previous installations custom component-bindings for those regions still would work and wouldn't need to be reimplemented. That was the only reason, if we would have started form scratch using a "document-panels" would have been the best way. (That approach is actually what is used in the "out of the box templates" that was added to HEAD a couple of days ago: http://blogs.alfresco.com/wp/ewinlof/2011/10/12/create-pages-in-alfresco-share-using-new-out-of-the-box-templates/ )

This does unfortunately have the effect that you mention, that reordering the objects isn't as easy as changing the index. If I were to do such a customization I would still use the component bindings as Dave also mentioned. First remove the component:
<sub-components>
<sub-component id="default">
    <evaluations>
      <evaluation id="alwaysRemove">
        <render>false</render>
      </evaluation>
    </evaluations>
</sub-component>
</sub-components>

…and then add the component you removed into a new region. The reason I think its better to do it this way is that if you have multiple modules working at once, reordering the regions (rather than the components) could become very hard to predict where youre components actually end up.
Imagine module A adds a new component on index 0 for region "document-actions" region. If then module B goes along and reorders the regions using the freemarker directives) and places "document-actions" at the bottom module A's new component would suddenly not be placed
at the top of of the page, but instead somewhere in the bottom. Preserving the ordering of the regions however at least increases the odds of the components ending up at the correct places even though it still is impossible to say exactly where it will end up when multiple modules are in action.

> -maybe the new extension framework is not a fit here, and the "old way" is better?

Yes I think you're right. If you want to change the structure of the page, overriding the template sure sounds like the way to go, it is after all the templates only job to do exactly that.

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

Haha, I must say I like David doing the speach, looking forward to hear him answer all your tricky but very relevant questions 🙂

Anyway I'm not sure how much I've actually added to the discussion but its an interesting one so I wanted to jump in 🙂 Please go ahead and challenge us, and come up with more improvement ideas, so we can make it better.

Cheers, Erik

rjohnson

This is an old post now, but its contents proved invaluable to me when I was trying to do exactly what Loftux was trying to do.

The theme of the post changes just about post 5 where Loftux ask about positioning preview and edit form side-by-side and we get into a discussion about subcomponents and regions generating markup. After that the post is about document details panel re-ordering and the discussion of positioning of preview and edit form side-by-side dries up.

Well, I have a solution to positioning (at least with 4.2c onwards).

As at 4.2c (maybe earlier) the edit-metatdata.ftl contains @markup directives, and with this the best and simplest way to deal with positioning is to use @markup to replace the bd section with markup of you choosing.

I started from the point of having the preview displaying using @region to add the new metadata-web-preview region. From then in the file edit-metatdata.ftl I replaced

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

with

<@markup id="bd-new" target="bd" action="replace" scope="global">
   <div id="bd">
      <div class="share-form">
         <@region id="edit-metadata-mgr" scope="template" />
         <div class="yui-g">
            <div class="yui-u first">
            <@region id="metadata-web-preview" scope="global"/>
            </div>
            <div class="yui-u">
            <@region id="edit-metadata" scope="template"/>
            </div>
         </div>
      </div>
   </div>
</@markup>‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Bingo. Preview on the left, edit form on the right.

I hope this helps someone.

Thanks for this great post

Bob Johnson

douglascrp

Hello.

I'm trying to implement your idea on Share 5.1.f, but I couldn't find a way to make it work.

This is the thread I started on the issue