001/*
002 *  Copyright 2012 GWT-Bootstrap
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package com.github.gwtbootstrap.client.ui.config;
017
018import com.github.gwtbootstrap.client.ui.base.IsResponsive;
019import com.github.gwtbootstrap.client.ui.resources.Resources;
020
021/**
022 * <h3>Using custom CSS/JS resources.</h3>
023 * 
024 * <p>
025 * If you need to adapt resources, create your resource package, add your files and implement this interface, then add a
026 * <code>replace-with</code> tag and <code>public</code> tag to your module xml. Example:
027 * </p>
028 * 
029 * <p>
030 *
031 * 1. Create your Resources package and add css,js directory to that (under your module xml package) and add your resources to adove css,
032 * js directory. (Bootstarp's css filename should be <code>bootstrap.min.css</code> and Bootstrap's js filename should be <code>bootstrap.min.js</code>)
033 * <pre>
034 * src/main/java/com/example
035 * |-- client
036 * |-- resources
037 * |   |-- css
038 * |   |   `-- bootstrap.min.css < your custom css
039 * |   |   `-- bootstrap-responsive.min.css < your custom css
040 * |   |-- js
041 * |   |   `-- bootstrap.min.js < your custom js
042 * |   |-- ExampleConfigurator.java < your custom Configurator class
043 * |   `-- ExampleResources.java < your custom Resources interface
044 * |-- server
045 * |-- shared
046 * `-- Example.gwt.xml < your module xml file
047 * </pre>
048 * 
049 * 
050 * 2. Create a Resources Interface (extending {@link Resources}) override the
051 * getters of the files you want to replace.
052 * 
053 * <pre>
054 *      public interface MyResources extends Resources {
055 *              {@literal @Source("css/bootstrap.min.css")}
056 *              TextResource bootstrapCss();
057 *
058 *              {@literal @Source("css/bootstrap-responsive.min.css")}
059 *              TextResource bootstrapResponsiveCss();
060 *      }
061 * </pre>
062 * 
063 * </p>
064 * 
065 * <p>
066 * 3. Create a <code>Configurator</code>.
067 * 
068 * <pre>
069 *      public MyConfigurator implements Configurator {
070 *              public Resources getResources() {
071 *                      return GWT.create(MyResources.class);
072 *              }
073 *      }
074 * </pre>
075 * 
076 * </p>
077 * 
078 * <p>
079 * 4. Add a <code>replace-with</code> tag, <code>source</code> and <code>public<tag> to your module xml (
080 * <code>*.gwt.xml</code>):
081 * 
082 * <pre>
083 * {@literal
084 * <source path='resources'/>
085 * <replace-with class="com.example.resources.ExampleConfigurator">
086 *     <when-type-is class="com.github.gwtbootstrap.client.ui.config.Configurator"/>
087 * </replace-with>
088 * <public path="resources">
089 *     <exclude name="** /*.java"/>
090 *     <exclude name="** /*.class"/>
091 * </public>
092 *
093 * }
094 * </pre>
095 * 
096 * </p>
097 *
098 * <p>A more detailed tutorial and a full working example can be found <a href="http://caarlos0.github.com/code/2012/06/27/using-a-custom-bootstrap-theme-in-gwt-bootstrap">here</a>.</p>
099 * @since 2.0.4.0
100 * 
101 * @author Dominik Mayer
102 * @author ohashi keisuke
103 * @author Carlos A Becker
104 * 
105 * @see Resources
106 * @see DefaultConfigurator
107 */
108public interface Configurator {
109
110        /**
111         * Get the Bootstrap Resources that should be used for this project.
112         * 
113         * @return the Bootstrap Resources
114         */
115        Resources getResources();
116
117        //@formatter:off
118        /**
119         * Determines whether the project uses a responsive design.
120         * 
121         * <p>
122         * If the responsive
123         * design is enabled, the interface can adapt to the screen size and show
124         * different content on smartphones, tablets and desktop computers.
125         * </p>
126         * 
127         * @return <code>true</code> if the responsive features should be enabled.
128         * Default: <code>false</code>
129         * 
130         * @see IsResponsive
131         * 
132         * @see <a href="http://twitter.github.com/bootstrap/scaffolding.html#responsive">Bootstrap documentation</a>
133         */
134        boolean hasResponsiveDesign();
135}