Consistent naming and object model between UI and API

[bdaw]

I would like to discuss using consistent naming for portal entities. This is a concern visible between UI and API.

Internally we have several entities like:

• Site - generic object being collection of pages and navigations (very high level definition)
• Site of type portal - Like "classic" and "sample" that come out of the box.
• Site of type group - Each group can have one related site
• Dashboard - which is also site related to specific user in the end.

Within UI (GateIn 3.2) this naming is not used consistently. Just two simple examples:

• There is 'Site' menu which lists "Classic". However under sites management you can "Add New Portal"
• To create new Group Site (or Site of type group) you need to use "Add Navigation" button.

Because internal model is even more complex this makes it pretty hard to understand actual object model.

There is another major issue with the usage of word "Portal". It is easy to misunderstood the context in which it is used.

• Portal as a project or deployed server
• Portals Container
• Portal as a type of a Site

In the end you can create new portal inside of portal but in context of specific portals container…. I guess this is one of reasons why term "Site" is used in exchange in the UI. However like I mentioned above it becomes tricky in connection with API where "Site" is generic interface.

To simplify things I would like to propose that we name "Group Site" (Site of type group) with new term - "Space". Then we should clearly define what to we refer as a "Site" in the UI. I imagine there are 2 scenarios:

1) "Site" refers to "Site of type portal". UI shows "Site Classic", "Site Sample" and /platform/users group "space".

In the Java API level there is object hierarchy - "PortalObject --> Site, Space, Dashboard". (PortalObject could be probably changed to something better - I lack invention atm.)

In the REST API level there are URL patterns like "/sites", "/spaces" and "/dashboards"

2) "Portal" refers to "Site of type portal". UI shows "Portal Classic", "Portal Sample" and /platofrm/users group "space". Management operations live under "Sites Management" however we UI exposes actions like "Add New Portal" and "Add New Space". Term "Site" needs to be used carefully as it can refer to "Portal", "Space" or "Dashboard".

In the Java API level there is object hierarchy "Site -> Portal, Space, Dashboard.

In the REST API level there are URL patterns like "/portals", "/spaces" and "/dashboards"

[gcardoso]

It's a good idea to have different names for sites and group sites  to avoid confusion. I'm just not sure which is best (site or portal) to define a "Site of type portal". In terms of Brazil, a consultant told me that users call them "Portals". Do you have an idea about how users call them elsewhere?

[nscavell]

Since GateIn supports multiple portal containers, I don't really like the word 'portal' to be in association with a site. So with that said I like option 1, and a portal should refer to a portal container. My concern is that adding the new term "Space" might be confusing at first.

[julien_viet]

I am neutral concerning the naming above concerning the public API, however I will explain you why in current internal API and object model a site is called a site.

A site is called a site because it's a collection of resources : navigation and pages (and possibly other things like css or js in wcm).

The extension portal/space/dashboard (or however they are called) are specialization of this site concept, for instance "a dashboard is a site private to a user for which the navigation and pages define a concept of dashboard".

[theute]

I prefer option 1, just because the word 'portal' as bad press (for historical wrong reasons). I don't mind the mismatch with internal API too much if that makes public API and UI clearer.

[claprun]

If we can't explain it clearly, it means the abstraction is wrong (or at least, imperfect)…

I think, like Nick, that whatever we call portal containers (and I also agree that we might want to call them simply portals) shouldn't be used for user-visible features.

Otherwise, I'm not sure why we need a distinction between portals (e.g. classic) and sites (e.g. administrator site) to start with? Is there that much difference functionality-wise? For that matter, there shouldn't be any difference either between a site and a dashboard conceptually-wise if we understand sites as a collection of resources that are accessible by a specified set of users. Do our users even really care about sites or spaces? As a user, I'd think I wouldn't. I would just create a "portal" (or site, or whatever). Call it whatever and assign access restrictions to it. Do we have any interest in handling such portals any different than "regular" ones? More importantly, do our users?

So, based on the assumption that users don't care about "sites" vs. "spaces" (portals), I would just have one concept in the API. Call it Site. No need for Space or Dashboard. Spaces and Dashboards could be identified using convention (i.e. their name implies their function: Foo Dashboard, Administrator Group Site). If really needed, I would add a method on Site like isDashboard but I still don't think that we need to single out group sites as opposed to regular ones.

[bdaw]

I like the concept of just having single interface like Site in the API. We had a bit of brainstorming with Julien and Nick and we'd like to try going with something along in the API:

public interface Site

{

   Id getId();

   String getDisplayName();

   void setDisplayName(String displayName);

   String getDescription();

   void setDescription(String description);

   int getPriority();

   void setPriority(int priority);

   Navigation getNavigation();

   Page getPage(String pageName);

   //

   Navigation getNavigation(String navigationId);

   Navigation getNavigation(String... path);

   //

   <T> T getProperty(PropertyType<T> property);

   <T> void setProperty(PropertyType<T> property, T value);

   public class Id

   {

      private Type siteType;

      private String name;

      private Id(Type siteType, String name)

      {

         this.siteType = siteType;

         this.name = name;

      }

      public static Id create(Type siteType, String name)

      {

         return new Id(siteType, name);

      }

      public Type getSiteType()

      {

         return siteType;

      }

      public String getName()

      {

         return name;

      }

   }

   public static enum Type

   {

      PORTAL, GROUP, USER;

   }

}

OR

public static enum Type

{

      SITE, SPACE, DASHBOARD;

}

Usage:

classicSite.getId().getName() -> "classic"

johnDashboard.getId().getName() -> "john"

administratorsSpace.getId().getName()  -> "/platform/administrators"

This doesn't solve the issue with consistent naming though as those need to be referenced in documentation and in the UI.

[bdaw]

I agree with Chris and I think it comes down to what we want to have in the UI in the end. Either:

1) "Portal Site", "Group Site", "User Site" terms.

2) "Site", "Space", "Dashboard' - (please be consistent and don't do "Portal Site", "Group Site" and "Dashboard" mix....)

3) Just "Site" with a notion of an owner or access restriction to single user or group. Then however it is easy to get back to option 1)...

Personally I think option 2) makes most sense as single consistent terms are easier to understand. Option 3) is interesting to follow however this requires careful UI design to not confuse users.

[plamarque]

+1 for 2) "Site", "Space", "Dashboard

[boubaker]

IMHO, 2) is the best option that concord with our products.

In a training, for example, it's easy to say:

Site: pages for public access.

Dashboard: User pages (this term is usually used to define a personnal page of a user).

Space: similar to Social, the spaces is the pages shared between the members of a group.

But it will be helpful for developers, that those three enteties entends a generic one.

[fdrouet]

my choice is option 2 ("Site", "Space", "Dashboard)

[tugdualgrall]

I vote for:

option 2) "Site", "Space", "Dashboard' -

[gcardoso]

I also think this option will work fine:

2) "Site", "Space", "Dashboard'

[rdenarie]

Personnaly, I prefer solution 1) :

Portal Site, Group Site and User Site.

This solution allows to keep internal generic object Site, which can be Portal, group or user type.

In addition, it keeps a consistant naming between the 3 possible site.

For me, "Site, Space, Dashboard" is not "easy" to understand to a final user.  Solution 1) seems more clear.