Add a Second Site Webapp
Add a second site web application to your existing Bloomreach Experience Manager implementation project.
The tutorial assumes:
- You have at least followed the Get Started tutorial.
- Your existing project is a standard project created using the Maven archetype with default archetype property values and the News and Simple Content features added from the Essentials library.
In addition, it is highly recommended to:
- Follow the Build a Website tutorial.
- Read the Introduction to Multi Site Web Application Support.
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=14.0.0-2 \ -DarchetypeRepository=https://maven.onehippo.com/maven2
mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeGroupId=org.onehippo.cms7 -DarchetypeArtifactId=hippo-site-project-archetype -DarchetypeVersion=14.0.0-2 -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 basically 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.
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:
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:
You will have to manually merge the contents of the above 3 files into their counterparts in myproject/repository-data/application:
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 application 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 Experience manager. Also verify that both the 'live' sites are available (on http://localhost:8080/site/ and http://localhost:8080/mysiteproject/) and fully functional.
If you want to deploy in a server environment (on-premise or Bloomreach Cloud), you need to create a distribution containing all three webapps (CMS and both sites). Add the mysiteproject webapp to the appropriate assembly file, for example:
<component xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/component/1.1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/component/1.1.2 http://maven.apache.org/xsd/component-1.1.2.xsd"> <files> <file> <source>cms/target/cms.war</source> <outputDirectory>webapps</outputDirectory> <destName>cms.war</destName> </file> <file> <source>site/webapp/target/site.war</source> <outputDirectory>webapps</outputDirectory> <destName>site.war</destName> </file> <file> <source>../mysiteproject/site/webapp/target/site.war</source> <outputDirectory>webapps</outputDirectory> <destName>mysiteproject.war</destName> </file> </files> </component>
You can now create the distribution as usual:
mvn clean verify mvn -P dist
Please note that content for the site sub-project is not included in the distribution and will therefore not be bootstrapped on deployment. If you want to bootstrap some initial content (such as the mysiteproject root folder and the events folder), you would need to move the relevant YAML files from mysiteproject/repository-data/application/src/main/resources/hcm-content to myproject/repository-data/application/src/main/resources/hcm-content. However, this would complicate development going forward so it may be better to create the content manually after the first deployment and keep the management of this type of repository data seperated between the sub-projects.
This completes a full multi site development workflow cycle.