How to define a custom Site layout

[alejandrogarcia]

Hi folks,

I'm currently involved in a project which requires a high customization of Share. One of the thing I have been able to achieve is to create my custom site preset definition.

Nevertheless, it is not enough with only changing the site's default pages, dashboard and dashlets. I also need to show in the dashboard a menu or group of options on the left, very similar to the menu that the repository or document library have. At the same time, I would need to change the dashlets distribution and preserve the site's functionality that allows the user to customize the site.

I guess what I have described in the last paragraph can be achieved by defining your own 100% custom site dashboard, creating both a custom template-instance and FTL files.

I currently have created the next elements:

1. Custom site preset:

<?xml version='1.0' encoding='UTF-8'?>
<presets>
   <!– Well known preset used to generate the default Collaboration Site dashboard –>
   <preset id="custom-dashboard">
      <components>         
         <!– title –>
         <component>
            <scope>page</scope>
            <region-id>title</region-id>
            <source-id>site/${siteid}/dashboard</source-id>
            <url>/components/title/collaboration-title</url>
         </component>
         <!– navigation –>
         <component>
            <scope>page</scope>
            <region-id>navigation</region-id>
            <source-id>site/${siteid}/dashboard</source-id>
            <url>/components/navigation/collaboration-navigation</url>
         </component>
         
         <!– workgroups –>
         <component>
            <scope>page</scope>
            <region-id>workgroups</region-id>
            <source-id>site/${siteid}/dashboard</source-id>
            <url>/components/custom/workgroups</url>
         </component>
         
         <component>
            <scope>page</scope>
            <region-id>component-1-1</region-id>
            <source-id>site/${siteid}/dashboard</source-id>
            <url>/components/dashlets/colleagues</url>
            <properties>
               <height>504</height>
            </properties>
         </component>
         <component>
            <scope>page</scope>
            <region-id>component-2-1</region-id>
            <source-id>site/${siteid}/dashboard</source-id>
            <url>/components/dashlets/docsummary</url>
         </component>
         <component>
            <scope>page</scope>
            <region-id>component-2-2</region-id>
            <source-id>site/${siteid}/dashboard</source-id>
            <url>/components/dashlets/activityfeed</url>
         </component>
      </components>
      <pages>
         <page id="site/${siteid}/dashboard">
            <title>Collaboration Site Dashboard</title>
            <title-id>page.siteDashboard.title</title-id>
            <description>Collaboration site's dashboard page</description>
            <description-id>page.siteDashboard.description</description-id>
            <template-instance>custom-dashboard</template-instance>
            <authentication>user</authentication>
            <properties>
               <sitePages>[{"pageId":"documentlibrary"}]</sitePages>
            </properties>
         </page>
      </pages>
   </preset>
</presets>
‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

2. Custom template-instance:

<?xml version='1.0' encoding='UTF-8'?>
<template-instance>
   <template-type>my/package/custom-dashboard</template-type>
   <description>Custom Dashboard</description>
   <properties>
      <gridClass>yui-gd</gridClass>
      <gridColumn1>5</gridColumn1>
      <gridColumn2>5</gridColumn2>
   </properties>
</template-instance>
‍‍‍‍‍‍‍‍‍‍‍‍

3. Custom custom-dashboard.flt:

<#include "/org/alfresco/include/alfresco-template.ftl" />
<#import "/org/alfresco/import/alfresco-layout.ftl" as layout />
<@templateHeader "transitional" />

<@templateBody>
   <@markup id="alf-hd">
   <div id="alf-hd">
      <@region id="header" scope="global" />
      <@region id="title" scope="page" />
      <@region id="navigation" scope="page" />
   </div>
   </@>
   <@markup id="alf-full-width">
   <div id="alf-full-width">
      <@region id="full-width-dashlet" scope="page" />
   </div>
   </@>
   <@markup id="bd">
      <div id="bd">
         <#–
            LEFT PANEL
         –>
         <div class="yui-t1" id="alfresco-documentlibrary">
            <div class="yui-b" id="alf-filters">
               <@region id="workgroups" scope="page"/>
            </div>
         </div>
         <#–
            LEFT PANEL
         –>
         
         <@layout.grid gridColumns gridClass "component" />
      </div>
   </@>
</@>

<@templateFooter>
   <@markup id="alf-ft">
   <div id="alf-ft">
      <@region id="footer" scope="global" />
   </div>
   </@>
</@>
‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

And I also have created a webscript component for the menu on the left that I have explained before. It has been created by taking as an example /components/documentlibrary/filter. Any other better model to follow?

Well, everything is working now but the presentation in the UI is not right at all.

After all, I'm wondering these questions: Is this the right approach and Am I in the right direction? Any other better and easier way to do what I'm trying to do? I believe this modification goes further than a simple site preset definition, and despite of I'm trying to understand the Share code and I'm constantly searching for posts or articles regarding this kind of customization I'm not making some more progress.

I hope I have explained clear enough. I would really appreciate some help to be guided in the right way.

Thanks in advance.

[erikwinlof]

Hi Alejandro,

By looking at the code and your description I would say that you are indeed using the correct approach but that your template html markup isn't perfect yet.

I understood it as everything actually is working except that the styling/layout of the different sections of the page isn't what you had expected.
If so, to get what you want, take some time and play around with the yui grid builder: http://developer.yahoo.com/yui/grids/builder/

Try setting it to…
Body Size: 100%
Body Columns: Sidebar left 300px
Split Content > Row: 4 Columns <—- This part of the code will later be handled by your call to <@layout.grid gridColumns gridClass "component" />

Then just click on "Show Code" and you should be able to get the structure I think your looking for.

Cheers, Erik

[alejandrogarcia]

Hi Erik,

Thanks a million for your answer.

I followed your recommendation and it helped me a lot to open my mind and find a slightly different approach. I have discarded both my custom template-instance and FTL, I have only changed my preset this way:

<?xml version='1.0' encoding='UTF-8'?>
<presets>
   <!– Well known preset used to generate the default Collaboration Site dashboard –>
   <preset id="custom-dashboard">
      <components>         
         <!– title –>
         <component>
            <scope>page</scope>
            <region-id>title</region-id>
            <source-id>site/${siteid}/dashboard</source-id>
            <url>/components/title/collaboration-title</url>
         </component>
         <!– navigation –>
         <component>
            <scope>page</scope>
            <region-id>navigation</region-id>
            <source-id>site/${siteid}/dashboard</source-id>
            <url>/components/navigation/collaboration-navigation</url>
         </component>
         
         <!– workgroups –>
         <component>
            <scope>page</scope>
            <region-id>component-1-1</region-id>
            <source-id>site/${siteid}/dashboard</source-id>
            <url>/components/custom/workgroups</url>
         </component>
         
         <component>
            <scope>page</scope>
            <region-id>component-2-1</region-id>
            <source-id>site/${siteid}/dashboard</source-id>
            <url>/components/dashlets/colleagues</url>
            <properties>
               <height>504</height>
            </properties>
         </component>
         <component>
            <scope>page</scope>
            <region-id>component-2-2</region-id>
            <source-id>site/${siteid}/dashboard</source-id>
            <url>/components/dashlets/docsummary</url>
         </component>
         <component>
            <scope>page</scope>
            <region-id>component-2-3</region-id>
            <source-id>site/${siteid}/dashboard</source-id>
            <url>/components/dashlets/activityfeed</url>
         </component>
      </components>
      <pages>
         <page id="site/${siteid}/dashboard">
            <title>Collaboration Site Dashboard</title>
            <title-id>page.siteDashboard.title</title-id>
            <description>Collaboration site's dashboard page</description>
            <description-id>page.siteDashboard.description</description-id>
            <template-instance>dashboard-2-columns-wide-right</template-instance>
            <authentication>user</authentication>
            <properties>
               <sitePages>[{"pageId":"documentlibrary"}]</sitePages>
            </properties>
         </page>
      </pages>
   </preset>
</presets>
‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

This way the presentation in the UI is good, it shows a column on the left with my webscript component and dashlets on the right. It only has a problem, if I try to customize the dashboard by adding a dashlet to the left side my component disappear and is no longer available because, as I understand and correct me if I'm wrong, my component is not a dashlet itself.

At the same time, the last reflection makes me also think in a dashlets-based approach, but I don't know if it could have any undesired consequence in the future…

Coming back to my first approach, I think that I would need to add a left panel as I was trying, out of the dashlets scope as the title, navigation or foot components. I think my only mistake was to not re-size the dahslets columns. By using the YUI Grid builder is the only way? Isn't there any other way (clean and un-intrusive of course) in order to change the dashlets column sizes?

Thanks again.

Regards.

[erikwinlof]

Hi again,

A dashlet is just a regular webscript component that happens to have been placed on a dashboard page.
There is only 1 small thing that makes it different from other components and that is that it has been "marked" as a dashlet.
That is done inside the .get.desc.xml file using the <family> element which, when your marking it as a dashlet, can be set to: user-dashlet, site-dashlet OR dashlet.
The ONLY thing this element does is to decide if your component shall appear on:
- only the customise used dashboard page = user-dashlet
- only the customise site dashboard page = site-dashlet
- both pages above = dashlet

(In a similar way you can also add webscripts to be part of the console using <family>admin-console</family>)

If a webscript doesn't have its <family> element set to any of these it will NOT show up in the cusotmise dashboard pages and can therefor not be used from there.
It can however be added using a preset which you have done.

Before I was under the impression that you wanted to "hardcode/fix" your custom component to the left of *all* dashlets which is why I suggested you would continue with your custom template. But after what you've just had written it sounds more like what you should do is keep with your latest plan but also make sure to add the following to your webscripts/dashlets .get.desc.xml file:
<family>site-dashlet</family>

Cheers and good luck, Erik

[alejandrogarcia]

Hi,

Thanks again for such a good explanation.

In fact in my lasts posts I was just guessing trying to find out the best option, but I'm still wondering which solution is the best to go. Actually I think that the first one (customized dashboard with fixed panel with menu on the left) is better than a dashlets-based solution mainly because one reason: the left panel and its components must be reusable in other custom pages that I would need to create, not only in the site dashboard page, and according to your explanation dashlets only can be shown in a dashboard.

I think that I will continue with my first idea, according to what I have just explained. Following your recommendation Erik, I got this YUI grid that meets my requirements:

<html>
<head>
   <title>YUI Base Page</title>
   <link rel="stylesheet" href="http://yui.yahooapis.com/2.8.0r4/build/reset-fonts-grids/reset-fonts-grids.css" type="text/css">
</head>
<body class="yui-skin-sam">
<div id="doc3" class="yui-t1">
   <div id="hd"><h1>Header</h1></div>
   <div id="bd">
      <div id="yui-main">
         <div class="yui-b">
            <div class="yui-g">
            <!– FULL WIDTH DASHLET ABOVE GOES HERE –>
            </div>
            <div class="yui-g">
               <div class="yui-u first">
               <!– SMALL DASHLET BELLOW GOES HERE –>
                  </div>
               <div class="yui-u">
               <!– SMALL DASHLET BELLOW GOES HERE –>
                  </div>
            </div>
         </div>
      </div>
      <div class="yui-b"><!– MY LEFT PANEL WITH MENU AND OPTIONS GOES HERE –></div>
   
   </div>
   <div id="ft"><p>Footer</p></div>
</div>
</body>
</html>
‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

If had to do a fixed dashboard without giving to the user the possibility of changing the layout and dashlets, then I would know how to proceed. In fact I have tried it (http://postimage.org/image/kkotj8669/) and works like a charm (with the exception of making some fixes to the YUI styles before for proper visualization). The problem is that it isn't possible to customization page (see image http://postimage.org/image/n6w2bo8tv/).

The question is, how to customize the original dashboard.ftl in order to preserve the customization functionality, as if it were another layout as those that exist out-of-the-box ("columns: wide centre", "Two columns: wide left, narrow right", etc.)??

I hope I'm explaining properly, and I hope this thread helps others trying to do the same than me :?

Thanks Erik.

Regards.

[erikwinlof]

Hi again 🙂

What I meant to say before was that the only way of making a webscript appear in the "CUSTOMIZE Dashboard pages" (in other words in the "Available dashlets" section of the pages where the user drags n drops dashlets for his dashboard OR when a site manager changes the  dashlets for a site) is to set the <family> tag to i.e. "dashlet".

There is nothing stopping a component (marked with i.e. <family>site-dashlet</family>) to be placed on another page.
…and as you have already experienced there is also nothing stopping a component that ISN'T marked with <family>site-dashlet</family> to end up on a site's dashboard when it has been placed there using a preset. (It will however not show up as an "Available dashlet" on the "Customize Dashboard pages")

Note though that marking a webscript with <family>site-dashlet</family> will make it appear as an "available dashlet" on ALL sites' Customise Dashboard pages. (There is currently no way of making it only appear for certain site preset, something which probably would make sense.)

So…..

If your fine with
a) the dashlet showing up as an available dashlet for all sites and also fine with
b) the fact that the site manager might remove your dashlet from the dashboard,
then use the second solution, that is the easiest!


…however if your not fine with that for some reason you will need to go with your first solution and…

1. Create your custom dashboard template like you already have (make sure it uses the call to <@layout.grid gridColumns gridClass "component" /> to handle the actual "dashlet grid"). Note that you can import the template javascript controller dashboard.js to avoid rewriting the template's javascript code.

2. You must now also make sure to make your custom template available in the "Current Layout:" section of the "Customize Dashboard" page. Take a closer look to this blog post to figure out how to do that in a 4.0 server: http://blogs.alfresco.com/wp/ddraper/2012/05/22/customizing-share-javascript-widget-instantiation-pa...
What you want todo is to add your custom template to the "layouts" option inside customize-layout.get.js.

Cheers, Erik

[alejandrogarcia]

Hi again Erik,

Yes!! Something like customize-layout.get.js is what I was looking for!!

Very useful answer. I'm understanding by short steps how Surf and Share work, sorry whether I'm too slow  :?

Well, now that I know that both solutions are possible for adding a new component on the left, which one do you think is the better option and why? If I had to make choice, I would choose the one that doesn't implies a dashlet, because I don't want the user to change or move that component, do you know what I mean?

Thanks very much Erik!

Regards.

[erikwinlof]

As long as I have understood your requirements fully, I would prefer the second solution. It requires a bit more work but it provides the best user experience.

Cheers & good luck, Erik

[alejandrogarcia]

Thanks a million again for your help Erik.

I'll follow your advise. I hope the time you spent with me was worth and other developers find this post useful if they try to do something similar to what I'm trying to do.

Best regards.