quickstart.html.haml

---
layout: base
---

%h1
  Quickstart

%p
  This small tutorial will give an overview on how to get started with Togglz.

%h2 
  Installation

%p
  First add following dependencies to your project:

%pre(class="prettyprint lang-xml")
  :escaped
    <!-- Togglz for Servlet environments (mandatory) -->
    <dependency>
      <groupId>org.togglz</groupId>
      <artifactId>togglz-servlet</artifactId>
      <version>#{site.stableVersion}</version>
    </dependency>
    
    <!-- CDI integration (optional) -->
    <dependency>
      <groupId>org.togglz</groupId>
      <artifactId>togglz-cdi</artifactId>
      <version>#{site.stableVersion}</version>
    </dependency>
    
    <!-- Spring integration (optional) -->
    <dependency>
      <groupId>org.togglz</groupId>
      <artifactId>togglz-spring-web</artifactId>
      <version>#{site.stableVersion}</version>
    </dependency>

%p
  If you deploy your application to a Servlet 3.0 container, you won't have to do any further configuration.
  In case your container doesn't support Servlet 3.0, you have to manually register the required filter. Please 
  refer to <a href="/documentation/installation.html">Installation</a> for details.

%h2
  Configuration

%p
  First create your feature enum class:

%pre(class="prettyprint lang-java")
  :escaped
    public enum MyFeatures implements Feature {
    
        @EnabledByDefault
        @Label("First Feature")
        FEATURE_ONE,
        
        @Label("Second Feature")
        FEATURE_TWO;
        
        public boolean isActive() {
            return FeatureContext.getFeatureManager().isActive(this);
        }
        
    }

%p
  The next step is to create an implementation of <code>TogglzConfig</code>:

%pre(class="prettyprint lang-java")
  :escaped
    @ApplicationScoped
    public class DemoConfiguration implements TogglzConfig {
    
        public Class<? extends Feature> getFeatureClass() {
            return MyFeatures.class;
        }
    
        public StateRepository getStateRepository() {
            return new FileBasedStateRepository(new File("/tmp/features.properties"));
        }
    
        public UserProvider getUserProvider() {
            return new ServletUserProvider("admin");
        }
    
    }

%p
  See the following short description for a description of each method:

%ul
  %li
    <code>getFeatureClass()</code>: This method is used to tell Togglz about your feature enum. Just return the class of the enum here.
  %li
    <code>getStateRepository()</code>: This method must return the feature state repository which is responsible to persist 
    the state of features. This example uses the <code>FileBasedStateRepository</code> which uses Java property files to save the
    feature state. But Toggles provides several other implementations. 
    Please refer to <a href="/documentation/repositories.html">State Repositories</a> for details.
  %li
    <code>getUserProvider()</code>: This method returns a provider class that is responsible to tell the FeatureManager 
    which is the <i>current user</i>. Togglz provides out-of-the-box integration with many popular security frameworks. 
    Please refer to <a href="/documentation/authentication.html">User Authentication</a> for details.

%h2
  Usage

%p
  Using Togglz is very simple. To check if a feature is active just call the <code>isActive()</code> method of the corresponding feature enum value:

%pre(class="prettyprint lang-java")
  :escaped
    if( MyFeatures.FEATURE_ONE.isActive() ) {
      // new stuff here
    }

%h2
  Admin Console

%p
  Togglz ships with an embedded admin console that allows you to toggle your features:

%img(src='/images/screenshot-admin-console.png' class='content-image')

%p
  To enable the embedded Togglz admin console, add the following dependency to your <code>pom.xml</code>:

%pre(class="prettyprint lang-xml")
  :escaped
    <!-- Togglz Admin Console -->
    <dependency>
      <groupId>org.togglz</groupId>
      <artifactId>togglz-console</artifactId>
      <version>#{site.stableVersion}</version>
    </dependency> 

%p
  If you deploy your application to a Servlet 3.0 container, you won't have to do any further configuration. If your 
  container doesn't support Servlet 3.0, you will have to manually add the <code>TogglzConsoleServlet</code> to 
  your <code>/WEB-INF/web.xml</code>. Please refer to <a href="/documentation/installation.html">Installation</a> for details.

%p
  The admin console will be available in a virtual path named <code>togglz</code> within you application. So if you application is deployed to a context path named <code>myapp</code> within the container, you will have to use the following URL: 

%p.calign
  %a(href='http://localhost:8080/myapp/togglz/' class='biglink')
    http://localhost:8080/myapp/togglz/

%h2
  JSF integration

%p
  To make use of the JSF integration features, add the following module to your pom:

%pre(class="prettyprint lang-xml")
  :escaped
    <!-- JSF integration -->
    <dependency>
      <groupId>org.togglz</groupId>
      <artifactId>togglz-jsf</artifactId>
      <version>#{site.stableVersion}</version>
    </dependency> 

%p
  The JSF integration provides a very simple way to render page content depending on whether a feature is active or not:

%pre(class="prettyprint lang-xml")
  :escaped
    <h:panelGroup rendered="\#{features['FEATURE_ONE']}">
      <!-- Some part of the page required for FEATURE_ONE -->
    </h:panelGroup>

%h3
  Spring Boot Starter <span class="label label-important">since 2.3.0</span>

%p
  If you are using Spring Boot there is an alternative installation approach by using the <code>togglz-spring-boot-starter</code> module.
  This starter will install the common Togglz dependencies and will also perform auto configuration.
  See the <a href="/documentation/spring-boot-starter.html">Spring Boot Starter</a> chapter for more info.