Managing Space Templates

eXo Platform spaces are associated with templates at creation time. Each template defines the space visibility, registration and the list of applications. This chapter will cover configuration for

Tip

In order to extend existing space templates or create a new one, you must have your own extension.

This section assumes that you have already a working extension where you can plug the configuration.

Tip

All the configuration samples given in this chapter MUST be added to the portal configuration file of the extension war: custom-extension.war!/WEB-INF/conf/configuration.xml.

Tip

The definition of standard eXo templates can be found here.

Creating a new template

You can define a new space template by configuration using registerSpaceTemplatePlugin method of the org.exoplatform.social.core.space.spi.SpaceTemplateService. A space template consists of name, visibility, registration, banner, home application and applications list fields. To add a space template, add the following configuration :

<external-component-plugins>
    <target-component>org.exoplatform.social.core.space.spi.SpaceTemplateService</target-component>
    <component-plugin>
      <name>Space Template Configuration</name>
      <set-method>registerSpaceTemplatePlugin</set-method>
      <type>org.exoplatform.social.core.space.SpaceTemplateConfigPlugin</type>
      <init-params>
        <object-param>
          <name>template</name>
          <description>Space Template</description>
          <object type="org.exoplatform.social.core.space.SpaceTemplate">
            <field name="name"><string>custom</string></field>
            <field name="visibility"><string>private</string></field>
            <field name="registration"><string>open</string></field>
            <field name="bannerPath"><string>war:/conf/social-extension/social/space-template/custom/banner.png</string></field>
            <field name="permissions"><string>${exo.social.space.template.custom.permissions:*:/platform/users}</string></field>
            <field name="invitees"><string>${exo.social.space.template.custom.invitees:}</string></field>
            <field name="homePageApplication">
              <object type="org.exoplatform.social.core.space.SpaceApplication">
                <field name="portletApp"><string>social-portlet</string></field>
                <field name="portletName"><string>SpaceActivityStreamPortlet</string></field>
                <field name="appTitle"><string>Home</string></field>
              </object>
            </field>
            <field name="applications">
              <collection type="java.util.ArrayList">
                <value>
                  <object type="org.exoplatform.social.core.space.SpaceApplication">
                    <field name="portletApp"><string>social-portlet</string></field>
                    <field name="portletName"><string>SpaceSettingPortlet</string></field>
                    <field name="appTitle"><string>Space Settings</string></field>
                    <field name="removable"><boolean>false</boolean></field>
                    <field name="order"><int>2</int></field>
                    <field name="uri"><string>settings</string></field>
                  </object>
                </value>
                ...
              </collection>
            </field>
          </object>
        </object-param>
      </init-params>
    </component-plugin>
</external-component-plugins>

In which:

  • Name: Space Template Configuration
  • Set-method: registerSpaceTemplatePlugin
  • Type: org.exoplatform.social.core.space.SpaceTemplateConfigPlugin
  • Init-params:
Object-param Description
template Sets the SpaceTemplate to be defined.
Field name Possible value Description
name string The name of the space template.
visibility string The visibility setting of the space. Possible values: “private” or “hidden”
registration string The registration setting for the space. Possible values are: “open”, “validation” or “close”
bannerPath string The path of the space banner file inside your extension war.
permissions string The groups that have permissions to view and use this space template.
invitees string The users and/or spaces that will be invited during space creation.
homePageApplication SpaceApplication The application to use in the home page of a space.
applications list of SpaceApplication The list of the applications that are installed by default to a new space.

Tip

The permissions parameter is a list of membership expressions separated by “;” character. Example: exo.social.space.template.custom.permissions=*:/platform/administrators;*:/platform/web-contributors , only members of /platform/administrators and /platform/web-contributors can view custom template and use it.

Tip

The invitees parameter is a comma-separated list of user and space names. For users, the username is used (as displayed in users management table). For spaces you should use the pretty name (as displayed in spaces list) Example: exo.social.space.template.custom.invitees=userA,space A,userB , the users userA, userB and all space A members will be added to the invitees for space having custom template.

  • SpaceApplication:
Field name Possible value Description
portletAp string The .war name file which has the portlet.
portletName string The name of portlet which is registered in the system in its portlet.xml.
appTitle string The display name of the application.
removable boolean Specifies if the application can be removed from the space or not.
order integer The order of the application in the space navigation.
uri string The URI of the application in the page node.

In this example, you can place the banner image file “banner.png” inside the war of your extension at custom-extension.war!/WEB-INF/conf/social-extension/social/space-template/custom/.

Tip

You can add translations for both space template name and description:

  • for space template name, add the property in a resource bundle : space.template.$TEMPLATE_NAME (for this example space.template.custom)
  • for space template description, add the property in a resource bundle : space.template.description.$TEMPLATE_NAME (for this example space.template.description.custom)

Extending existing templates

Space templates can be extended in order to add applications. Only applications can be added to space templates via extension. In order to add some applications to an existing template, extendSpaceTemplatePlugin method of the org.exoplatform.social.core.space.spi.SpaceTemplateService will be used in a component plugin. Add this to the configuration of your extension :

<external-component-plugins>
    <target-component>org.exoplatform.social.core.space.spi.SpaceTemplateService</target-component>
    <!-- Community space template -->
    <component-plugin>
      <name>Space Template Extension</name>
      <set-method>extendSpaceTemplatePlugin</set-method>
      <type>org.exoplatform.social.core.space.SpaceTemplateConfigPlugin</type>
      <init-params>
        <object-param>
          <name>template</name>
          <description>Space Template</description>
          <object type="org.exoplatform.social.core.space.SpaceTemplate">
            <field name="name"><string>custom</string></field>
            <field name="applications">
              <collection type="java.util.ArrayList">
                <value>
                  <object type="org.exoplatform.social.core.space.SpaceApplication">
                    <field name="portletApp">
                      <string>task-management</string>
                    </field>
                    <field name="portletName">
                      <string>TaskManagementApplication</string>
                    </field>
                    <field name="appTitle">
                      <string>abcd</string>
                    </field>
                    <field name="removable">
                      <boolean>true</boolean>
                    </field>
                    <field name="order">
                      <int>3</int>
                    </field>
                    <field name="uri">
                      <string>tasks</string>
                    </field>
                  </object>
                </value>
              </collection>
            </field>
          </object>
        </object-param>
      </init-params>
    </component-plugin>
    ...
</external-component-plugins>

This will add “tasks” application to the “custom” space template. The “tasks” application will be the third application in the space created from this template according to the “order” field.

Defining an application handler

Application handlers manipulate space applications: install, activate, deactivate, uninstall. Each space template can have its own application handler. All applications handlers must implement the interface SpaceApplicationHandler. In order to define an application handler, add the following configuration :

<external-component-plugins>
    <target-component>org.exoplatform.social.core.space.spi.SpaceTemplateService</target-component>
    <component-plugin>
      <name>CustomSpaceApplicationHandler</name>
      <set-method>registerSpaceApplicationHandler</set-method>
      <type>com.custom.social.core.space.impl.CustomSpaceApplicationHandler</type>
      <init-params>
        <value-param>
          <name>templateName</name>
          <value>custom</value>
        </value-param>
      </init-params>
    </component-plugin>
</external-component-plugins>

This will define CustomSpaceApplicationHandler as the application handler of the space template “custom”.