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 * GWT-Bootstrap uses embedded copies of bootstrap.css and bootstrap.js by default. If you need to use your own copies
026 * or include other resources, you'll need to create a custom {@link Configurator} and a custom {@link Resources}.
027 * </p>
028 * <p>
029 * A suggested layout is below. First, create your resource package at the same level as client/server/shared. Next, create
030 * css and js directories beneath the resources directory, and add your custom css and js files into those. Next, create your custom
031 * {@link Configurator} and a custom {@link Resources}. Finally, add
032 * a <code>replace-with</code> tag and a <code>public</code> tag to your module xml.
033 * </p>
034 * <p>
035 * Full example below:
036 * </p>
037 * 
038 * <p>
039 * 1. Create your resources package directory and add css and js directories beneath that. Add your custom css and js files to the css and js
040 * directories, respectively.
041 * <pre>
042 * src/main/java/com/example
043 * |-- client
044 * |-- resources
045 * |   |-- css
046 * |   |   `-- bootstrap.min.css < your custom css
047 * |   |   `-- bootstrap-responsive.min.css < your custom css
048 * |   |-- js
049 * |   |   `-- bootstrap.min.js < your custom js
050 * |   |-- ExampleConfigurator.java < your custom Configurator class
051 * |   `-- ExampleResources.java < your custom Resources interface
052 * |-- server
053 * |-- shared
054 * `-- Example.gwt.xml < your module xml file
055 * </pre>
056 * 
057 * 
058 * 2. Create a Resources interface (extending {@link Resources}) that overrides the
059 * getters of the files you want to replace.
060 * 
061 * <pre>
062 *      public interface MyResources extends Resources {
063 *              {@literal @Source("css/bootstrap.min.css")}
064 *              TextResource bootstrapCss();
065 *
066 *              {@literal @Source("css/bootstrap-responsive.min.css")}
067 *              TextResource bootstrapResponsiveCss();
068 *      }
069 * </pre>
070 * 
071 * </p>
072 * 
073 * <p>
074 * 3. Create a <code>Configurator</code> that returns your new {@link Resources}.
075 * 
076 * <pre>
077 *      public MyConfigurator implements Configurator {
078 *              public Resources getResources() {
079 *                      return GWT.create(MyResources.class);
080 *              }
081 *      }
082 * </pre>
083 * 
084 * </p>
085 * 
086 * <p>
087 * 4. Add a <code>replace-with</code> tag, a <code>source</code> tag, and a <code>public</code> tag to your module xml
088 * (<code>*.gwt.xml</code>):
089 * 
090 * <pre>
091 * {@literal
092 * <source path='resources'/>
093 * <replace-with class="com.example.resources.ExampleConfigurator">
094 *     <when-type-is class="com.github.gwtbootstrap.client.ui.config.Configurator"/>
095 * </replace-with>
096 * <public path="resources">
097 *     <exclude name="** /*.java"/>
098 *     <exclude name="** /*.class"/>
099 * </public>
100 *
101 * }
102 * </pre>
103 * 
104 * </p>
105 *
106 * <p>A more detailed tutorial and a full working example can be found <a href="http://carlosbecker.com/posts/using-a-custom-bootstrap-theme-in-gwt-bootstrap">here</a>.</p>
107 * @since 2.0.4.0
108 * 
109 * @author Dominik Mayer
110 * @author ohashi keisuke
111 * @author Carlos A Becker
112 * 
113 * @see Resources
114 * @see DefaultConfigurator
115 */
116public interface Configurator {
117
118        /**
119         * Get the Bootstrap Resources that should be used for this project.
120         * 
121         * @return the Bootstrap Resources
122         */
123        Resources getResources();
124
125        //@formatter:off
126        /**
127         * Determines whether the project uses a responsive design.
128         * 
129         * <p>
130         * If the responsive
131         * design is enabled, the interface can adapt to the screen size and show
132         * different content on smartphones, tablets and desktop computers.
133         * </p>
134         * 
135         * @return <code>true</code> if the responsive features should be enabled.
136         * Default: <code>false</code>
137         * 
138         * @see IsResponsive
139         * 
140         * @see <a href="http://twitter.github.com/bootstrap/scaffolding.html#responsive">Bootstrap documentation</a>
141         */
142        boolean hasResponsiveDesign();
143}