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 */
016 package com.github.gwtbootstrap.client.ui.config;
017
018 import com.github.gwtbootstrap.client.ui.base.IsResponsive;
019 import 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 */
108 public 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 }