The replacement for STK is Magnolia Templating Kit (MTK), first released with Magnolia 5.4 on July 3, 2015. MTK is quicker to learn than STK and requires fewer skills. MTK is aimed at the increasing number of front-end developers who looked for something leaner and less time-consuming. MTE is front-end framework agnostic, which means you can integrate it with any modern framework such as Bootstrap or Foundation.
STK timeline:
2009: First release
2015: Maintenance mode
2017: Deprecation
2018: End of life
With the the release of Magnolia 5.6 we have stopped producing preconfigured bundles and webapps with the STK based demo. If you still rely on STK, you can use it. However, you have to build a bundle or webapp with STK yourself.
Using Maven to generate the webapp
We assume that you have at least a basic knowledge of Maven. To tailor a webapp, you typically start with an existing webapp where you add (and probably exclude) other modules. The page creating a custom bundle explains a scenario which starts with the Magnolia empty-webapp . In this tutorial you will create a custom webapp based on the magnolia-enterprise-pro-webapp .
Maven setup
Since you will build a webapp based on the magnolia-enterprise-pro-webapp , make sure you have the proper Maven settings providing access to the Magnolia enterprise repository.
To check your settings, follow these steps:
open a terminal, change to a temporary directory and clone the documentation-check-maven-settings module from magnolia git:
mkdir tmp
cd tmp/
git clone https://git.magnolia-cms.com/git/documentation/documentation-check-maven-settings.git
Now change into the cloned module and build the project with the -U option:
cd documentation-check-maven-settings/
mvn clean install -U
Maven will print out all the downloaded artifacts. At the end it should display the "BUILD SUCCESS" message:
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.467 s
[INFO] Finished at: 2014-12-11T11:54:27+01:00
[INFO] Final Memory: 22M/184M
[INFO] ------------------------------------------------------------------------
If you couldn't build documentation-check-maven-settings , please read Maven setup and modify your settings accordingly. If you were successful, read on.
Creating a custom bundle using a Maven archetype
In this section, you will:
Run a Maven command to produce an archetype.
Adapt the result from step 1 to make sure that the webapp inherits from the magnolia-enterprise-pro-webapp .
Add the STK modules.
Set the pro widgetset
Build the webapp with Maven.
Step 1: Using the Maven archetype command
Open a shell and move to a working directory of your choice. Run the following command:
During the execution of the command, you will be prompted to choose options or add values. Here is an overview of the parameters which you have to decide for:
Parameter
Value used in this tutorial
Meaning
Choose a number or apply filter
2
= An archetype to create a Magnolia project (a parent pom and a webapp).
This creates an archetype for a Magnolia webapp.
Just enter the number. We will not apply the filter option here.
Choose archetype version
Always choose the latest
The version of the archetype script.
Please note that upon entering 2 in the previous step, the prompt will in fact read as follows:
The Maven groupId of this project. We use org.example .
Use a value reflecting your requirements.
artifactID
custom-stk-project
The Maven artifact id. We use custom-stk-project .
Use a value reflecting your requirements.
version
1.0-SNAPSHOT
The initial Maven version of this new project.
It is a common practice to start with 1.0-SNAPSHOT .
package
org.example.magnolia.webapp.stk
The package name for the Java package which will be created.
Use a value reflecting your requirements.
magnolia-bundle-version
5.6.1
Although
Error rendering macro 'artifact-resource-macro'
com.sun.jersey.api.client.ClientHandlerException: A message body reader for Java class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and Java type class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and MIME media type application/octet-stream was not found
is the latest version of the 5.6 Magnolia major version - please use 5.6.1 for the time being.
The Magnolia bundle version.
We recommend using the latest version. If you rely on an older branch, you may have to adapt the version of the STK modules added.
project-name
custom-stk-project
The name of the Magnolia module.
We recommend using the same name as in the artifactId parameter.
The command will summarize all the relevant parameters you have entered. To confirm the values press Y . The command will then create the following structure:
(The stk-example-project/stk-example-project-webapp/src folder contains more files than shown above, but you may ignore them in the context of the present topic.)
Now it's time to have a look at the two pom files. You will edit them both in the next step. In the following file, study especially the dependencyManagement/dependencies section, which specifies modules versions.
custom-stk-project/pom.xmlExpand source
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.example</groupId>
<artifactId>custom-stk-project</artifactId>
<name>custom-stk-project (parent pom)</name>
<version>1.0-SNAPSHOT</version>
<packaging>pom</packaging>
<properties>
<magnoliaBundleVersion>5.6.1</magnoliaBundleVersion>
<javaVersion>1.8</javaVersion>
</properties>
<!-- Fill the following in, so you can use the release plugin -->
<scm>
<connection/>
<developerConnection/>
<url/>
</scm>
<dependencyManagement>
<dependencies>
<!-- Option A -->
<!-- Importing dependencyManagement of CE bundle. -->
<dependency>
<groupId>info.magnolia.bundle</groupId>
<artifactId>magnolia-bundle-parent</artifactId>
<version>${magnoliaBundleVersion}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<!-- Option B -->
<!-- If you want to use the Enterprise Edition. -->
<!--
<dependency>
<groupId>info.magnolia.eebundle</groupId>
<artifactId>magnolia-enterprise-bundle-parent</artifactId>
<version>${magnoliaBundleVersion}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
-->
</dependencies>
</dependencyManagement>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.7.0</version>
<configuration>
<source>${javaVersion}</source>
<target>${javaVersion}</target>
</configuration>
</plugin>
</plugins>
<!-- default resources configuration which will filter your module descriptors -->
<resources>
<resource>
<directory>src/main/resources</directory>
<includes>
<include>**/*</include>
</includes>
</resource>
<resource>
<filtering>true</filtering>
<directory>src/main/resources</directory>
<includes>
<include>META-INF/magnolia/*</include>
</includes>
</resource>
</resources>
</build>
<repositories>
<repository>
<id>magnolia.public</id>
<url>https://nexus.magnolia-cms.com/content/groups/public</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
<!-- IF YOU NEED MODULES FROM THE ENTERPRISE VERSION, UNCOMMENT THE FOLLOWING REPOSITORY -->
<!--
<repository>
<id>magnolia.enterprise.releases</id>
<url>https://nexus.magnolia-cms.com/content/repositories/magnolia.enterprise.releases</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
-->
<repository>
<id>vaadin-addons</id>
<url>https://maven.vaadin.com/vaadin-addons</url>
</repository>
</repositories>
<modules>
<module>custom-stk-project-webapp</module>
</modules>
</project>
In the following file, study especially the dependencies section. It specifies which modules will form part of the webapp.
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.example</groupId>
<artifactId>custom-stk-project</artifactId>
<version>1.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>custom-stk-project-webapp</artifactId>
<name>custom-stk-project: webapp</name>
<packaging>war</packaging>
<dependencies>
<!--
Add your project specific dependencies here:
A custom webapp typically is based on a magnolia webapp. The most simple and reduced bundle to start with is the "magnolia-empty-webapp" (see "option i" below).
To see a complete list of preconfigured Magnolia webapps, have a look at https://documentation.magnolia-cms.com/display/DOCS/Bundles+and+webapps
=> Please just use one of the four below listed options!
Make sure to use the appropriate option (A or B) in the parent pom
-->
<!-- option i - magnolia-empty-webapp -->
<!-- Dependencies versions are already imported by parent pom. Requires "Option A" in the parent pom. -->
<dependency>
<groupId>info.magnolia</groupId>
<artifactId>magnolia-empty-webapp</artifactId>
<type>war</type>
</dependency>
<dependency>
<groupId>info.magnolia</groupId>
<artifactId>magnolia-empty-webapp</artifactId>
<type>pom</type>
</dependency>
<!-- option ii - magnolia-community-webapp -->
<!-- Dependencies versions are already imported by parent pom. Requires "Option A" in the parent pom. -->
<!--
<dependency>
<groupId>info.magnolia.bundle</groupId>
<artifactId>magnolia-community-webapp</artifactId>
<type>war</type>
</dependency>
<dependency>
<groupId>info.magnolia.bundle</groupId>
<artifactId>magnolia-community-webapp</artifactId>
<type>pom</type>
</dependency>
-->
<!-- option iii - magnolia-enterprise-standard-webapp -->
<!-- Dependencies versions are already imported by parent pom. Requires "Option B" in the parent pom. -->
<!--
<dependency>
<groupId>info.magnolia.eebundle</groupId>
<artifactId>magnolia-enterprise-standard-webapp</artifactId>
<type>war</type>
</dependency>
<dependency>
<groupId>info.magnolia.eebundle</groupId>
<artifactId>magnolia-enterprise-standard-webapp</artifactId>
<type>pom</type>
</dependency>
-->
<!-- option iv - magnolia-enterprise-pro-webapp -->
<!-- Dependencies versions are already imported by parent pom. Requires "Option B" in the parent pom. -->
<!--
<dependency>
<groupId>info.magnolia.eebundle</groupId>
<artifactId>magnolia-enterprise-pro-webapp</artifactId>
<type>war</type>
</dependency>
<dependency>
<groupId>info.magnolia.eebundle</groupId>
<artifactId>magnolia-enterprise-pro-webapp</artifactId>
<type>pom</type>
</dependency>
-->
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<!-- exclude jars copied "physically" from the webapp overlay - so we only get those resolved by Maven's dependency management -->
<dependentWarExcludes>WEB-INF/lib/*.jar</dependentWarExcludes>
</configuration>
</plugin>
</plugins>
</build>
</project>
Step 2: Overlaying magnolia-enterprise-pro-webapp
In this step you will make sure that your webapp inherits from the magnolia-enterprise-pro-webapp . Maven will create the so-called Overlay. You must adapt both the version management section and and the module management sections. You have to edit both pom files shown above.
Adapting the version management section
In custom-stk-project/pom.xml edit the dependencyManagement/dependencies section. Delete the section marked as "Option A" and uncomment "Option B". Keep the block marked as "TEST". When done, the dependency management section should look like this:
The pom imports the version management section of magnolia-enterprise-bundle-parent. In step 3 you will also specify the version of the STK modules in the section.
Adapting the module management section
In custom-stk-project/custom-stk-project-webapp/pom.xml edit the dependencies section. Uncomment the section marked as "option iv", delete the options i, ii and iii. The dependencies section should then look as follows:
These dependencies will instruct Maven to merge the artifacts from magnolia-enterprise-pro-webapp into the project. In step 3 you will add the STK modules to the webapp.
Step 3: Adding the STK modules
Here are the modules which you have to add to enable the standard templating kit:
magnolia-module-standard-templating-kit
The module which contains the templates.
Required
magnolia-theme-pop
A theme.
Required when using the demo project, see the next row.
magnolia-demo-project
A demo project based on the STK templates and the pop theme.
Optional
Be aware that the above modules have transient dependendencies to other Magnolia modules, for example to magnolia-module-public-user-registration and magnolia-module-device-detection . These dependencies are handled by Maven automatically. Now let's edit the pom files again.
Editing custom-stk-project/pom.xml
Add the following snippet to the dependencyManagement/dependencies section:
Please note that the version tags of the added dependencies do not contain the value but a variable instead. Set this variable in the properties section at the beginning of the file.
For a Magnolia 5.6 webapp use the latest minor version of the STK 3.1.x series which is
Error rendering macro 'artifact-resource-macro'
com.sun.jersey.api.client.ClientHandlerException: A message body reader for Java class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and Java type class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and MIME media type application/octet-stream was not found
Since you are creating a webapp based on the EE pro webapp, you have to make sure that the webapp is configured to use the pro widgetset (see Magnolia widgetsets).
Go to the custom-stk-project-webapp/src/main/webapp/WEB-INF/config/default folder or create the folder if it doesn't exist yet. Create the magnolia.properties file there:
Congratulations! Your webapp is finished. You can start it from your IDE for further development.
For a production environment consider using a different persistence layer instead of the embedded H2. When deploying the webapp as WAR you should at least change the path to the repository. You can also add another module to your project to create an artifact which bundles Tomcat or another servlet container with your webapp.
Adapting a webapp manually
This section explains how you can adapt a webapp by adding (and removing) JAR files to make sure it contains the STK modules. The aim is, again, to end up with an enterprise PRO webapp with the STK modules.
Compared to Maven-based solutions, adjusting a webapp manually is more error-prone and also harder to maintain.
The base artifact: magnolia-enterprise-pro-demo-bundle
Start with a preconfigured artifact provided by Magnolia. This time take a complete bundle which comes together with Tomcat. Tomcat bundles are first-choice artifacts for quick testing scenarios or for users who do not want to invest in custom Maven setups.
Download
Error rendering macro 'artifact-resource-macro'
com.sun.jersey.api.client.ClientHandlerException: A message body reader for Java class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and Java type class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and MIME media type application/octet-stream was not found
, copy it to a folder of your choice, unzip it, but do not start the bundle yet.
Adapting webapps/magnoliaAuthor/WEB-INF/lib
Open the magnolia-enterprise-<x.y>/apache-tomcat-8.5.5/webapps/magnoliaAuthor/WEB-INF/lib folder. It contains the JAR files whose content you will adapt. Note that the webapps folder – at this moment, before the bundle has been started for the first time – contains only one complete webapp: magnoliaAuthor. During the first start, the start script will copy the WEB-INF folder to the magnoliaPublic folder. That's why both webapps will contain the same modules (and JAR files).
Be aware of transient dependencies
Magnolia modules often have dependencies to other Magnolia modules or to modules provided by third-party providers. When manually tailoring a webapp, you have to make sure that the library files for the dependent modules are also provided.
Removing travel-demo's JAR files
Since we start with magnolia-enterprise-pro-demo-bundle , we have to get rid of the Magnolia travel demo modules. The bundle cannot contain both demo projects. Therefore, remove the following JAR files from the webapps/magnoliaAuthor/WEB-INF/lib folder (all JAR files beginning with magnolia-travel* ):
Now add the following JAR files to the webapps/magnoliaAuthor/WEB-INF/lib folder:
Error rendering macro 'artifact-resource-macro'
com.sun.jersey.api.client.ClientHandlerException: A message body reader for Java class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and Java type class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and MIME media type application/octet-stream was not found
Error rendering macro 'artifact-resource-macro'
com.sun.jersey.api.client.ClientHandlerException: A message body reader for Java class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and Java type class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and MIME media type application/octet-stream was not found
Error rendering macro 'artifact-resource-macro'
com.sun.jersey.api.client.ClientHandlerException: A message body reader for Java class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and Java type class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and MIME media type application/octet-stream was not found
Error rendering macro 'artifact-resource-macro'
com.sun.jersey.api.client.ClientHandlerException: A message body reader for Java class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and Java type class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and MIME media type application/octet-stream was not found
Error rendering macro 'artifact-resource-macro'
com.sun.jersey.api.client.ClientHandlerException: A message body reader for Java class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and Java type class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and MIME media type application/octet-stream was not found
com.sun.jersey.api.client.ClientHandlerException: A message body reader for Java class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and Java type class info.magnolia.sys.confluence.plugin.artifactinfo.nexus.entities.SearchNGResponse, and MIME media type application/octet-stream was not found
The first part of the startup command ./magnolia_control.sh start launches Magnolia. The second part && tail -f ../logs/catalina.out displays log messages written to /apache-tomcat/logs/catalina.out log file. This makes it easier to troubleshoot startup errors.
Magnolia reports startup information. If startup fails, look for the reason in the report. In a successful startup the last line reads: INFO: Server startup in 12345 ms.
To stop Magnolia, type CTRL + C, then ./magnolia_control.sh stop and press RETURN.
Open a command prompt and go to the Magnolia installation directory. (To do this, type cd C:\Users\<username>\magnolia-x.y\apache-tomcat\bin)
Type magnolia_control.bat start and press ENTER. Magnolia reports startup information in a new Tomcat window. If startup fails, look for the reason in the report. In a successful startup the last line reads: INFO: Server startup in 12345 ms
To stop Magnolia, type CTRL + C , then ./magnolia_control.bat stop and press ENTER.
Open a terminal window.
Go to the Magnolia installation directory: cd /home/<your account>/magnolia-x.y/apache-tomcat/bin Your path may be different.
Start Magnolia: In bash shell: ./magnolia_control.sh start && tail -f ../logs/catalina.out In fish shell: ./magnolia_control.sh start; tail -f ../logs/catalina.out
The first part of the startup command ./magnolia_control.sh start launches Magnolia. The appended part tail -f ../logs/catalina.out displays log messages written to /apache-tomcat/logs/catalina.out log file. This makes it easier to troubleshoot startup errors.
Magnolia reports startup information. If startup fails, look for the reason in the report. In a successful startup the last line reads: INFO: Server startup in 12345 ms
To stop Magnolia, type CTRL + C , then ./magnolia_control.sh stop and press ENTER.
Open a terminal window.
Go to the Magnolia installation directory: cd /home/userAccount/magnolia-x.y/apache-tomcat/bin Your path may be different.
The first part of the startup command ./magnolia_control.sh start launches Magnolia. The second part && tail -f ../logs/catalina.out displays log messages written to /apache-tomcat/logs/catalina.out log file. This makes it easier to troubleshoot startup errors.
Magnolia reports startup information. If startup fails, look for the reason in the report. In a successful startup the last line reads: INFO: Server startup in 12345 ms
To stop Magnolia, type CTRL + C , then ./magnolia_control.sh stop and press ENTER.