topic Re: How to define a custom Site layout in Alfresco Archive

How to define a custom Site layout

alejandrogarcia — Thu, 08 Nov 2012 14:33:01 GMT

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 sh

Re: How to define a custom Site layout

erikwinlof — Thu, 08 Nov 2012 14:55:05 GMT

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

Re: How to define a custom Site layout

alejandrogarcia — Thu, 08 Nov 2012 16:15:46 GMT

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.

Re: How to define a custom Site layout

erikwinlof — Fri, 09 Nov 2012 08:16:08 GMT

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

Re: How to define a custom Site layout

alejandrogarcia — Fri, 09 Nov 2012 14:01:22 GMT

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.

Re: How to define a custom Site layout

erikwinlof — Fri, 09 Nov 2012 14:38:01 GMT

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-part-1/
What you want todo is to add your custom template to the "layouts" option inside customize-layout.get.js.

Cheers, Erik

Re: How to define a custom Site layout

alejandrogarcia — Fri, 09 Nov 2012 15:38:02 GMT

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.

Re: How to define a custom Site layout

erikwinlof — Mon, 12 Nov 2012 07:51:10 GMT

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

Re: How to define a custom Site layout

alejandrogarcia — Mon, 12 Nov 2012 08:10:32 GMT

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.