Add a Second Site Webapp - BloomReach Experience - Open Source CMS

Add a Second Site Webapp

Introduction

Goal

Add a second site web application to your existing Bloomreach Experience Manager implementation project.

Prerequisites

The tutorial assumes:

In addition, it is highly recommended to:

Approach

The second site webapp will be a separate Maven project with its own version management and release cycle but with a dependency on the 'parent' sub-project's CMS webapp.

In a real world development environment, the parent sub-project's artifacts would be deployed in your organizations Maven repository. For the purpose of this tutorial, you will use your local Maven repository as surrogate.

Following this tutorial, you will walk through a very basic multi-site development workflow scenario: create the second site webapp using the Maven archetype, add a feature to it, then migrate any platform code and/or configuration related to the new feature to the parent sub-project. The end result will be that the complete implementation project, including the parent sub-project and the site sub-project) is ready for an aggregate deployment in an environment.

Create the Maven Project for the Second Site Webapp

First, navigate to the directory containing the existing project (myproject) and run the following Maven command:

mvn clean install

This deploys the project's artifacts in your local Maven repository so they are available when your build the new site sub-project.

Navigate to a directory outside the existing project (e.g. its parent directory).

To create the second site webapp sub-project, type the command shown below. This will create a new folder with a name equal to the chosen artifactId, containing the generated sub-project. On Windows, run the command on a single line and leave out the line continuation characters ('\') or use '^' as continuation character.

mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate \
-DarchetypeGroupId=org.onehippo.cms7 \
-DarchetypeArtifactId=hippo-site-project-archetype \
-DarchetypeVersion=13.2.0 \
-DarchetypeRepository=https://maven.onehippo.com/maven2

Windows

mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeGroupId=org.onehippo.cms7 -DarchetypeArtifactId=hippo-site-project-archetype -DarchetypeVersion=13.0.0 -DarchetypeRepository=https://maven.onehippo.com/maven2

The archetype plugin will ask you to confirm a number of properties defining the Maven coordinates for both the new site sub-project and the existing parent sub-project:

Confirm properties configuration:
groupId: org.example.site
artifactId: mysiteproject
version: 0.1.0-SNAPSHOT
package: org.example.site
parentArtifactId: myproject
parentGroupId: org.example
parentVersion: 0.1.0-SNAPSHOT
projectName: My Site Project
 Y: : 

If you are just following the tutorial and using the archetype default settings, press Enter to continue. Otherwise, enter 'N', then enter the appropriate values for your project.

Build and run the site sub-project as you normally would for a single-site project:

cd mysiteproject
mvn clean verify
mvn -Pcargo.run -Drepo.path=storage

Note that the site sub-project has its own CMS webapp (running at the usual URL, http://localhost:8080/cms/) which bascially repackages the parent sub-project's CMS. This CMS webapp exists solely for the purpose of development within the site sub-project. The same is true for the repository-data/application module.

The site will run at http://localhost:8080/mysiteproject/ although at this point there is nothing there yet.

Add a Feature to the Second Site Webapp

You are now ready to develop and test features in the site sub-project. Because feature development is outside the scope of this tutorial, you will add an out-of-the-box feature from the Essentials library as an example.

Tip: before you add the feature, bring the site sub-project code under version control (e.g. Git) so you can easily 'diff' afterwards to see what changes introduced by the new feature need to be migrated to the parent sub-project.

Browse to the Essentials dashboard at http://localhost:8080/essentials/ and install the 'Events' feature from the library.

Rebuild and restart the site sub-project and check the CMS and the site (at http://localhost:8080/mysiteproject/) to verify that the feature is installed and working correctly.

Note that up to this point, you have worked in complete isolation from the parent sub-project, i.e. your changes do not affect it. This is important, as it allows the parent sub-project to continue its own lifecycle of development, deployment, etc. without interference from any development going on in the site sub-project.

Migrate CMS Configuration from the Site Sub-Project to the Parent Sub-Project

Once the new feature in the site sub-project is ready, any new code and/or configuration in the cms and repository-data/application modules must be migrated to the corresponding modules in the parent sub-project.

Adding the 'Events' feature did not introduce any CMS code, but it did add and modify several files within the repository-data/application module. 

The following files were added:

  • mysiteproject/repository-data/application/src/main/resources/hcm-config/namespaces/mysiteproject.cnd
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/namespaces/mysiteproject.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/namespaces/mysiteproject/basedocument.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/namespaces/mysiteproject/eventsdocument.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/queries/templates/new-events-document.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/queries/templates/new-events-folder.yaml

Move all of the above files over to the corresponding folder within myproject/repository-data/application (create subfolders if necessary).

The following files were modified:

  • mysiteproject/repository-data/application/src/main/resources/hcm-config/main.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/templates.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/types.yaml

You will have to manually merge the contents of the above 3 files into their counterparts in myproject/repository-data/application:

myproject/repository-data/application/src/main/resources/hcm-config/main.yaml:

definitions:
  namespace:
    myproject:
      uri: http://www.myproject.com/myproject/nt/1.0
      cnd: namespaces/myproject.cnd
    mysiteproject:
      uri: http://www.mysiteproject.com/mysiteproject/nt/1.0
      cnd: namespaces/mysiteproject.cnd
      

myproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/templates.yaml (only English translations shown, merge other languages in a similar way):

definitions:
  config:
    /hippo:configuration/hippo:translations/hippo:templates/de:
      # <snip/>
    /hippo:configuration/hippo:translations/hippo:templates/en:
      new-resource-bundle: new resource bundle
      new-untranslated-folder: new untranslated folder
      new-news-document: new news item
      new-news-folder: new news item folder
      new-content-folder: new content folder
      new-content-document: new content document
      new-events-folder: new events folder
      new-events-document: new event
    /hippo:configuration/hippo:translations/hippo:templates/fr:
      # <snip/>
    /hippo:configuration/hippo:translations/hippo:templates/nl:
      # <snip/>

myproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/types.yaml (only English labels for eventsdocument shown, merge labels in other languages as well):

definitions:
  config:
    /hippo:configuration/hippo:translations/hippo:types/myproject:newsdocument:
      jcr:primaryType: hipposys:resourcebundles
      /en:
        # <snip/>
      /nl:
        # <snip/>
      /de:
        # <snip/>
      /fr:
        # <snip/>
    /hippo:configuration/hippo:translations/hippo:types/myproject:contentdocument:
      jcr:primaryType: hipposys:resourcebundles
      /en:
        # <snip/>
      /nl:
        # <snip/>
      /fr:
        # <snip/>
      /de:
        # <snip/>
    /hippo:configuration/hippo:translations/hippo:types/mysiteproject:eventsdocument:
      jcr:primaryType: hipposys:resourcebundles
      /en:
        jcr:primaryType: hipposys:resourcebundle
        jcr:name: Event
        mysiteproject:content: Content
        mysiteproject:date: Start date
        mysiteproject:enddate: End date
        mysiteproject:image: Image
        mysiteproject:introduction: Introduction
        mysiteproject:location: Location
        mysiteproject:title: Title
      /nl:
        # <snip/>
      /fr:
        # <snip/>
      /de:
        # <snip/>

After merging the changes, delete the 3 files from mysiteproject/repository-data/application. You can also delete any resulting empty folders.

Rebuild (mvn clean install) and restart the parent sub-project and browse to the CMS. Navigate to the Content perspective and select Document Types from the dropdown. The mysiteproject namespace should be there and contain the Event document type.

Stop the parent sub-project.

Delete the site sub-project's storage folder, the rebuild and restart the site sub-project. Verify that all the Events functionality (with the platform configuration now inherited from the parent sub-project) is still there and working as expected.

At this stage, you may want to test an aggregate deployment of the parent and site sub-projects. In your local development environment, you can use the following Maven command to do this:

mvn -Pcargo.run,with-main-site -Drepo.path=storage

Browse to the CMS and verify that both sites can be previewed in the Channels perspective. Also verify that both the 'live' sites are available (on http://localhost:8080/site/ and http://localhost:8080/mysiteproject/) and fully functional.

This completes a full multi site development workflow cycle.

Additional Reading

Multi Site Development Workflow

Configure Multiple Site Webapps in Bloomreach Cloud

 

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?