Java tutorial
/* * Copyright 2011 Google Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); you may not * use this file except in compliance with the License. You may obtain a copy of * the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the * License for the specific language governing permissions and limitations under * the License. */ package com.google.gwt.dom.builder.shared; import com.google.gwt.core.client.GWT; /** * Factory for creating element builders. * * <p> * Use {@link ElementBuilderFactory#get()} to fetch the builder factory * optimized for the browser platform. * </p> * * <p> * If you are using the builder on a server, use * {@link HtmlBuilderFactory#get()} instead. {@link HtmlBuilderFactory} can * construct a {@link com.google.gwt.safehtml.shared.SafeHtml} string and will * work on the server. Other implementations may only work on a browser client. * </p> * * <p> * Element builder methods can be chained together as with a traditional * builder: * </p> * * <pre> * DivBuilder divBuilder = ElementBuilderFactory.get().createDivBuilder(); * divBuilder.id("myId").text("Hello World!").endDiv(); * </pre> * * <p> * See this example: {@example * com.google.gwt.examples.dom.builder.ElementBuilderFactoryChainingExample}. * </p> * * <p> * Alternatively, builders can be used as separate objects and operated on * individually. This may be the preferred method if you are creating a complex * or dynamic element. The code below produces the same output as the code * above. * </p> * * <pre> * DivBuilder divBuilder = ElementBuilderFactory.get().createDivBuilder(); * divBuilder.id("myId"); * divBuilder.text("Hello World!"); * divBuilder.endDiv(); * </pre> * * <p> * See an example: {@example * com.google.gwt.examples.dom.builder.ElementBuilderFactoryNonChainingExample}. * </p> * * <p> * You can also mix chaining and non-chaining methods when appropriate. For * example, you can add attributes to an element by chaining methods, but use a * separate builder object for each separate element. * </p> * * <p> * NOTE: Builders always operate on the current element. For example, in the * code below, we create two divBuilders, one a child of the other. However, * they are actually the same builder instance! Implementations of * ElementBuilderFactory use a single instance of each builder type to improve * performance. The implication is that all element builders operate on the * current element, so the call to <code>divBuilder0.id("div1")</code> will set * the "id" of the child div, and is functionally equivalent to * <code>divBuilder1.id("div1")</code>. Its important to always call end() * before resuming work on the previous element builder. * </p> * * <pre> * DivBuilder divBuilder0 = ElementBuilderFactory.get().createDivBuilder(); * DivBuilder divBuilder1 = divBuilder0.startDiv(); * divBuilder0.id("div1"); // Operates on the first element! * </pre> */ public abstract class ElementBuilderFactory { private static ElementBuilderFactory instance; /** * Get the instance of the {@link ElementBuilderFactory}. * * @return the {@link ElementBuilderFactory} */ public static ElementBuilderFactory get() { if (instance == null) { if (GWT.isClient()) { instance = GWT.create(ElementBuilderFactory.class); } else { // The DOM implementation will not work on the server. instance = HtmlBuilderFactory.get(); } } return instance; } /** * Created from static factory method. */ protected ElementBuilderFactory() { } public abstract AnchorBuilder createAnchorBuilder(); public abstract AreaBuilder createAreaBuilder(); public abstract AudioBuilder createAudioBuilder(); public abstract BaseBuilder createBaseBuilder(); public abstract QuoteBuilder createBlockQuoteBuilder(); public abstract BodyBuilder createBodyBuilder(); public abstract BRBuilder createBRBuilder(); public abstract InputBuilder createButtonInputBuilder(); public abstract CanvasBuilder createCanvasBuilder(); public abstract InputBuilder createCheckboxInputBuilder(); public abstract TableColBuilder createColBuilder(); public abstract TableColBuilder createColGroupBuilder(); public abstract DivBuilder createDivBuilder(); public abstract DListBuilder createDListBuilder(); public abstract FieldSetBuilder createFieldSetBuilder(); public abstract InputBuilder createFileInputBuilder(); public abstract FormBuilder createFormBuilder(); public abstract FrameBuilder createFrameBuilder(); public abstract FrameSetBuilder createFrameSetBuilder(); public abstract HeadingBuilder createH1Builder(); public abstract HeadingBuilder createH2Builder(); public abstract HeadingBuilder createH3Builder(); public abstract HeadingBuilder createH4Builder(); public abstract HeadingBuilder createH5Builder(); public abstract HeadingBuilder createH6Builder(); public abstract HeadBuilder createHeadBuilder(); public abstract InputBuilder createHiddenInputBuilder(); public abstract HRBuilder createHRBuilder(); public abstract IFrameBuilder createIFrameBuilder(); public abstract ImageBuilder createImageBuilder(); public abstract InputBuilder createImageInputBuilder(); public abstract LabelBuilder createLabelBuilder(); public abstract LegendBuilder createLegendBuilder(); public abstract LIBuilder createLIBuilder(); public abstract LinkBuilder createLinkBuilder(); public abstract MapBuilder createMapBuilder(); public abstract MetaBuilder createMetaBuilder(); public abstract OListBuilder createOListBuilder(); public abstract OptGroupBuilder createOptGroupBuilder(); public abstract OptionBuilder createOptionBuilder(); public abstract ParagraphBuilder createParagraphBuilder(); public abstract ParamBuilder createParamBuilder(); public abstract InputBuilder createPasswordInputBuilder(); public abstract PreBuilder createPreBuilder(); public abstract ButtonBuilder createPushButtonBuilder(); public abstract QuoteBuilder createQuoteBuilder(); /** * Create a builder for an <input type='radio'> element. * * @param name name the name of the radio input (used for grouping) * @return the builder for the new element */ public abstract InputBuilder createRadioInputBuilder(String name); public abstract ButtonBuilder createResetButtonBuilder(); public abstract InputBuilder createResetInputBuilder(); public abstract ScriptBuilder createScriptBuilder(); public abstract SelectBuilder createSelectBuilder(); public abstract SourceBuilder createSourceBuilder(); public abstract SpanBuilder createSpanBuilder(); public abstract StyleBuilder createStyleBuilder(); public abstract ButtonBuilder createSubmitButtonBuilder(); public abstract InputBuilder createSubmitInputBuilder(); public abstract TableBuilder createTableBuilder(); public abstract TableCaptionBuilder createTableCaptionBuilder(); public abstract TableSectionBuilder createTBodyBuilder(); public abstract TableCellBuilder createTDBuilder(); public abstract TextAreaBuilder createTextAreaBuilder(); public abstract InputBuilder createTextInputBuilder(); public abstract TableSectionBuilder createTFootBuilder(); public abstract TableCellBuilder createTHBuilder(); public abstract TableSectionBuilder createTHeadBuilder(); public abstract TableRowBuilder createTRBuilder(); public abstract UListBuilder createUListBuilder(); public abstract VideoBuilder createVideoBuilder(); /** * Create an {@link ElementBuilder} for an arbitrary tag name. The tag name * will will not be checked or escaped. The calling code should be carefully * reviewed to ensure that the provided tag name will not cause a security * issue if including in an HTML document. In general, this means limiting the * code to HTML tagName constants supported by the HTML specification. * * * @param tagName the tag name of the new element * @return an {@link ElementBuilder} used to build the element */ public abstract ElementBuilder trustedCreate(String tagName); }