[richfaces-svn-commits] JBoss Rich Faces SVN: r11244 - in trunk/sandbox/ui/editor/src/main/java/org/richfaces: convert and 3 other directories.

Author: alevkovsky Date: 2008-11-19 11:45:36 -0500 (Wed, 19 Nov 2008) New Revision: 11244 Modified: trunk/sandbox/ui/editor/src/main/java/org/richfaces/component/UIEditor.java trunk/sandbox/ui/editor/src/main/java/org/richfaces/convert/SeamTextConverter.java trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/EditorRendererBase.java trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/html/images/EditorAdvancedThemeIcons.java trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/html/images/EditorIcons.java trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/html/images/EditorSimpleThemeIcons.java trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/resources/EditorHTMLRenderer.java Log: Editor: add javadocs Modified: trunk/sandbox/ui/editor/src/main/java/org/richfaces/component/UIEditor.java =================================================================== --- trunk/sandbox/ui/editor/src/main/java/org/richfaces/component/UIEditor.java 2008-11-19 16:43:52 UTC (rev 11243) +++ trunk/sandbox/ui/editor/src/main/java/org/richfaces/component/UIEditor.java 2008-11-19 16:45:36 UTC (rev 11244) @@ -39,10 +39,13 @@ */ public abstract class UIEditor extends UIInput { + /** Editor component type */ public static final String COMPONENT_TYPE = "org.richfaces.Editor"; + /** Editor component family */ public static final String COMPONENT_FAMILY = "org.richfaces.Editor"; + /** Id suffix of textarea which used as target element for tinyMCE scripts*/ public static final String EDITOR_TEXT_AREA_ID_SUFFIX = "TextArea"; public abstract void setType(String type); @@ -121,10 +124,16 @@ public abstract String getDialogType(); + /* (non-Javadoc) + * @see javax.faces.component.UIComponentBase#getRendersChildren() + */ public boolean getRendersChildren() { return true; } + /* (non-Javadoc) + * @see javax.faces.component.UIOutput#getConverter() + */ @Override public Converter getConverter() { Converter converter = super.getConverter(); Modified: trunk/sandbox/ui/editor/src/main/java/org/richfaces/convert/SeamTextConverter.java =================================================================== --- trunk/sandbox/ui/editor/src/main/java/org/richfaces/convert/SeamTextConverter.java 2008-11-19 16:43:52 UTC (rev 11243) +++ trunk/sandbox/ui/editor/src/main/java/org/richfaces/convert/SeamTextConverter.java 2008-11-19 16:45:36 UTC (rev 11244) @@ -47,25 +47,21 @@ import antlr.TokenStream; /** - * Seam Text Converter + * Seam Text Converter class. Provides converting html to seam text and vice versa. * * @author Alexandr Levkovsky * */ public class SeamTextConverter implements Converter { + /** log4j instance for converter class */ private static final Log _log = LogFactory.getLog(SeamTextConverter.class); - /** - * <p> - * The standard converter id for this converter. - * </p> - */ + /** The converter id for this converter. */ public static final String CONVERTER_ID = SeamTextConverter.class.getName(); - /** - * @see javax.faces.convert.Converter#getAsObject(javax.faces.context.FacesContext, - * javax.faces.component.UIComponent, java.lang.String) + /* (non-Javadoc) + * @see javax.faces.convert.Converter#getAsObject(javax.faces.context.FacesContext, javax.faces.component.UIComponent, java.lang.String) */ @SuppressWarnings("unchecked") public Object getAsObject(FacesContext context, UIComponent component, @@ -87,9 +83,8 @@ return null; } - /** - * @see javax.faces.convert.Converter#getAsString(javax.faces.context.FacesContext, - * javax.faces.component.UIComponent, java.lang.Object) + /* (non-Javadoc) + * @see javax.faces.convert.Converter#getAsString(javax.faces.context.FacesContext, javax.faces.component.UIComponent, java.lang.Object) */ @SuppressWarnings("unchecked") public String getAsString(FacesContext context, UIComponent component, Modified: trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/EditorRendererBase.java =================================================================== --- trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/EditorRendererBase.java 2008-11-19 16:43:52 UTC (rev 11243) +++ trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/EditorRendererBase.java 2008-11-19 16:45:36 UTC (rev 11244) @@ -41,21 +41,32 @@ import org.richfaces.component.UIEditor; /** - * @author Pavel Yaschenko - mailto:pyaschenko@exadel.com created 09.17.2008 + * Editor component renderer base class. * + * @author Alexandr Levkovsky + * */ public class EditorRendererBase extends InputRendererBase { + /** Specific script resource name which will be used to get server suffix */ private final static String SPECIFIC_SCRIPT_RESOURCE_NAME = "org/richfaces/renderkit/html/1$1.js"; + /** Specific xcss resource name which will be used to get server suffix */ private final static String SPECIFIC_XCSS_RESOURCE_NAME = "org/richfaces/renderkit/html/1$1.xcss"; + /** Editor viewMode attribute value which should disable rendering tinyMCE initialization */ private final static String TINY_MCE_DISABLED_MODE = "source"; + /* (non-Javadoc) + * @see org.richfaces.renderkit.InputRendererBase#getComponentClass() + */ @Override protected Class<? extends UIComponent> getComponentClass() { return UIEditor.class; } + /* (non-Javadoc) + * @see org.richfaces.renderkit.InputRendererBase#getConvertedValue(javax.faces.context.FacesContext, javax.faces.component.UIComponent, java.lang.Object) + */ @Override public Object getConvertedValue(FacesContext context, UIComponent component, Object submittedValue) @@ -63,11 +74,22 @@ return InputUtils.getConvertedValue(context, component, submittedValue); } + /** + * Method to get converted to String model value for component + * + * @param context - faces context instance + * @param component - component for which method is applied + * @param value - component value + * @return converted to String model value + */ protected String getConvertedStringValue(FacesContext context, UIEditor component, Object value) { return InputUtils.getConvertedStringValue(context, component, value); } + /* (non-Javadoc) + * @see org.richfaces.renderkit.InputRendererBase#doDecode(javax.faces.context.FacesContext, javax.faces.component.UIComponent) + */ @SuppressWarnings("unchecked") @Override protected void doDecode(FacesContext context, UIComponent component) { @@ -81,6 +103,13 @@ } + /** + * Method to get converted to String model value or if validation not passed submitted value for component + * + * @param context - faces context instance + * @param component - component for which method is applied + * @return converted to String component value + */ protected String getFormattedComponentStringValue(FacesContext context, UIEditor component) { String fieldValue = (String) component.getSubmittedValue(); @@ -91,14 +120,33 @@ return fieldValue; } + /** + * Method to get exact script resource URI suffix + * + * @param context - faces context instance + * @return string with script resource URI suffix + */ protected String getSriptMappingSuffix(FacesContext context) { return getResourceSuffix(context, SPECIFIC_SCRIPT_RESOURCE_NAME); } + /** + * Method to get exact xcss resource URI suffix + * + * @param context - faces context instance + * @return string with xcss resource URI suffix + */ protected String getCssMappingSuffix(FacesContext context) { return getResourceSuffix(context, SPECIFIC_XCSS_RESOURCE_NAME); } + /** + * Method to get resource URI suffix which was added due to web.xml mappings + * + * @param context - faces context instance + * @param resourceName - name of the resource which should be checked + * @return string with resource URI suffix which was added after resource name + */ private String getResourceSuffix(FacesContext context, String resourceName){ InternetResource resource = getResource(resourceName); String resourceUri = resource.getUri(context, null); @@ -109,6 +157,14 @@ return suffix; } + /** + * Method to write tinyMCE configuration script parameters from property + * file if it was determined through Editor configuration attribute. + * + * @param context - faces context instance + * @param component - Editor component instance + * @throws IOException + */ public void writeEditorConfigurationParameters(FacesContext context, UIEditor component) throws IOException { ResponseWriter writer = context.getResponseWriter(); @@ -140,6 +196,14 @@ } } + /** + * Method to write custom plugins script parameters from property + * file if it was determined through Editor configuration attribute. + * + * @param context - faces context instance + * @param component - Editor component instance + * @throws IOException + */ public void writeEditorCustomPluginsParameters(FacesContext context, UIEditor component) throws IOException { ResponseWriter writer = context.getResponseWriter(); @@ -169,6 +233,12 @@ } } + /** + * Method to build string with parameters from property file + * + * @param map - map with properties + * @return string with parameters in valid form for script + */ @SuppressWarnings("unchecked") private String convertProperties(Map map) { StringBuilder ret = new StringBuilder("{"); @@ -188,6 +258,13 @@ return ret.append("} ").toString(); } + /** + * Method to write script for loading custom plugins + * + * @param context - faces context instance + * @param map - properties map + * @return string with script + */ @SuppressWarnings("unchecked") private String getCustomPluginsCode(FacesContext context, Map map) { StringBuilder ret = new StringBuilder(); @@ -204,6 +281,13 @@ return ret.toString(); } + /** + * Method to write tinyMCE configuration script parameters from Editor component attributes. + * + * @param context - faces context instance + * @param component - Editor component instance + * @throws IOException + */ public void writeEditorConfigurationAttributes(FacesContext context, UIEditor component) throws IOException { ResponseWriter writer = context.getResponseWriter(); @@ -278,6 +362,13 @@ } } + /** + * Method to write tinyMCE configuration script parameters which was defined as <f:param> children for Editor + * + * @param context - faces context instance + * @param component - Editor component instance + * @throws IOException + */ public void writeEditorParameters(FacesContext context, UIComponent component) throws IOException { @@ -297,6 +388,12 @@ } } + /** + * Method to check if rendering of tinyMCE scripts needed. + * + * @param component - Editor component instance + * @return true if needed or false if only target textarea should be rendered + */ public boolean shouldRenderTinyMCE(UIEditor component) { if (component.getViewMode() != null && component.getViewMode().equalsIgnoreCase( @@ -307,6 +404,12 @@ } } + /** + * Method to get target textarea style if width or height attributes was determined + * + * @param component - Editor component instance + * @return string with style properties + */ public String getTextAreaStyle(UIEditor component) { StringBuilder b = new StringBuilder(); if (component.getWidth() != null) { Modified: trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/html/images/EditorAdvancedThemeIcons.java =================================================================== --- trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/html/images/EditorAdvancedThemeIcons.java 2008-11-19 16:43:52 UTC (rev 11243) +++ trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/html/images/EditorAdvancedThemeIcons.java 2008-11-19 16:45:36 UTC (rev 11244) @@ -33,14 +33,21 @@ import org.ajax4jsf.resource.ResourceContext; /** + * Class for advanced theme icons resource image of tinyMCE editor. + * Used for richfaces custom skin of tinyMCE editor. + * * @author Alexandr Levkovsky * */ public class EditorAdvancedThemeIcons extends EditorIcons{ + /** icons image dimensions */ private Dimension dimension = new Dimension(88, 66); + /** + * Class constructor + */ public EditorAdvancedThemeIcons() { super(); @@ -49,16 +56,23 @@ .getStartTime())); } + /* (non-Javadoc) + * @see org.ajax4jsf.resource.Java2Dresource#getDimensions(javax.faces.context.FacesContext, java.lang.Object) + */ public Dimension getDimensions(FacesContext facesContext, Object data) { return dimension; } + /* (non-Javadoc) + * @see org.ajax4jsf.resource.Java2Dresource#getDimensions(org.ajax4jsf.resource.ResourceContext) + */ protected Dimension getDimensions(ResourceContext resourceContext) { return dimension; } - /** - * + + /* (non-Javadoc) + * @see org.ajax4jsf.resource.Java2Dresource#paint(org.ajax4jsf.resource.ResourceContext, java.awt.Graphics2D) */ @Override public void paint(ResourceContext context, Graphics2D graphics) { Modified: trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/html/images/EditorIcons.java =================================================================== --- trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/html/images/EditorIcons.java 2008-11-19 16:43:52 UTC (rev 11243) +++ trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/html/images/EditorIcons.java 2008-11-19 16:45:36 UTC (rev 11244) @@ -42,18 +42,28 @@ import org.richfaces.skin.SkinFactory; /** + * Class with basic methods for drawing skinable icons for tinyMCE editor. + * * @author Alexandr Levkovsky * */ public abstract class EditorIcons extends Java2Dresource { + /** Additional background color parameter name in skin */ private final String ADDITIONAL_BACKGROUND_COLOR = "additionalBackgroundColor"; + /** SelectControl color parameter name in skin */ private final String SELECT_CONTROL_COLOR = "selectControlColor"; + /** Panel border color parameter name in skin */ private final String PANEL_BORDER_COLOR = "panelBorderColor"; + /** General text color parameter name in skin */ private final String GENERAL_TEXT_COLOR = "generalTextColor"; + /** Icon sub border transparency value */ private final int SUB_BORDER_TRANSPARENCY = 150; + /** + * Constructor + */ public EditorIcons() { super(); @@ -62,6 +72,9 @@ .getStartTime())); } + /* (non-Javadoc) + * @see org.ajax4jsf.resource.InternetResourceBase#getDataToStore(javax.faces.context.FacesContext, java.lang.Object) + */ protected Object getDataToStore(FacesContext context, Object data) { String additionalBackgroundColor = getSkinParameter(context, ADDITIONAL_BACKGROUND_COLOR); @@ -80,11 +93,13 @@ return ret; } + /* (non-Javadoc) + * @see org.ajax4jsf.resource.InternetResourceBase#deserializeData(byte[]) + */ protected Object deserializeData(byte[] objectArray) { if (objectArray == null) { return null; } - Object[] colors = new Object[5]; Zipper2 z = new Zipper2(objectArray); colors[0] = z.nextColor(); @@ -95,6 +110,13 @@ return colors; } + /** + * Method to get skin parameter value by parameter name + * + * @param context - faces context instance + * @param parameterName - name of the skin parameter + * @return string value of parameter + */ private String getSkinParameter(FacesContext context, String parameterName) { Skin skin = SkinFactory.getInstance().getSkin(context); Skin defaultSkin = SkinFactory.getInstance().getDefaultSkin(context); @@ -106,6 +128,14 @@ } + /** + * Method to paint icon background + * + * @param colors - icon colors + * @param selected - flag which defines either main or selected background color should be used in drawing + * @param withoutSubBorders - flag which defines either sub borders should be painted in icon + * @return buffered image + */ protected BufferedImage paintMainBlock(Object[] colors, boolean selected, boolean withoutSubBorders) { int w = 22; @@ -152,6 +182,12 @@ return image; } + /** + * Method to paint icons background separator + * + * @param colors - icon colors + * @return buffered image + */ protected BufferedImage paintSeparatorBlock(Object[] colors) { int w = 5; @@ -178,6 +214,13 @@ return image; } + /** + * Method to paint expand/collapse icon for some control + * + * @param colors - icon colors + * @param selected - flag which defines either main or selected background color should be used in drawing + * @return buffered image + */ protected BufferedImage paintFirstTriangleBlock(Object[] colors, boolean selected) { int w = 11; @@ -228,6 +271,16 @@ return image; } + /** + * Method to paint arrow triangle for expand/collapse icon + * + * @param g2d - Graphics2D instance + * @param x - x coordinate of the triangle + * @param y - y coordinate of the triangle + * @param main - main color of the triangle + * @param shadow - shadow color of the triangle + * @param shadowNeeded - defines if needed to draw triangle shadow + */ private void paintTriangle(Graphics2D g2d, int x, int y, Color main, Color shadow, boolean shadowNeeded) { int w = 4; @@ -244,6 +297,13 @@ } + /** + * Method to paint expand/collapse icon for dropdown list + * + * @param colors - icon colors + * @param selected - flag which defines either main or selected background color should be used in drawing + * @return buffered image + */ protected BufferedImage paintSecondTriangleBlock(Object[] colors, boolean selected) { int w = 14; @@ -296,6 +356,14 @@ return image; } + /** + * Method to fill icon body with gradient + * + * @param g2d - Graphics2D instance + * @param w - body width + * @param h - body height + * @param color - body color + */ private void fillBodyWithGradient(Graphics2D g2d, int w, int h, Color color) { Color halfColor = new Color(color.getRed(), color.getGreen(), color .getBlue(), 90); @@ -323,6 +391,11 @@ } + /** + * Method to prepare image for painting + * @param image + * @return Graphics2D instance for image + */ private Graphics2D prepareImage(BufferedImage image) { Graphics2D g2d = image.createGraphics(); Modified: trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/html/images/EditorSimpleThemeIcons.java =================================================================== --- trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/html/images/EditorSimpleThemeIcons.java 2008-11-19 16:43:52 UTC (rev 11243) +++ trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/html/images/EditorSimpleThemeIcons.java 2008-11-19 16:45:36 UTC (rev 11244) @@ -33,14 +33,20 @@ import org.ajax4jsf.resource.ResourceContext; /** + * Class for simple theme icons resource image of tinyMCE editor. + * Used for richfaces custom skin of tinyMCE editor. + * * @author Alexandr Levkovsky * */ public class EditorSimpleThemeIcons extends EditorIcons{ + /** icons image dimensions */ private Dimension dimension = new Dimension(40, 66); - + /** + * Class constructor + */ public EditorSimpleThemeIcons() { super(); @@ -49,16 +55,22 @@ .getStartTime())); } + /* (non-Javadoc) + * @see org.ajax4jsf.resource.Java2Dresource#getDimensions(javax.faces.context.FacesContext, java.lang.Object) + */ public Dimension getDimensions(FacesContext facesContext, Object data) { return dimension; } + /* (non-Javadoc) + * @see org.ajax4jsf.resource.Java2Dresource#getDimensions(org.ajax4jsf.resource.ResourceContext) + */ protected Dimension getDimensions(ResourceContext resourceContext) { return dimension; } - /** - * + /* (non-Javadoc) + * @see org.ajax4jsf.resource.Java2Dresource#paint(org.ajax4jsf.resource.ResourceContext, java.awt.Graphics2D) */ @Override public void paint(ResourceContext context, Graphics2D graphics) { Modified: trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/resources/EditorHTMLRenderer.java =================================================================== --- trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/resources/EditorHTMLRenderer.java 2008-11-19 16:43:52 UTC (rev 11243) +++ trunk/sandbox/ui/editor/src/main/java/org/richfaces/renderkit/resources/EditorHTMLRenderer.java 2008-11-19 16:45:36 UTC (rev 11244) @@ -39,18 +39,23 @@ import org.ajax4jsf.resource.ResourceContext; /** - * Editor html pages renderer - used for correcting scripts/images/css src + * Tiny_mce html resource pages renderer. + * Used for correcting scripts/images/css/irame src or href for normal loading by Resource Builder + * * @author Alexandr Levkovsky * */ public class EditorHTMLRenderer extends BaseResourceRenderer { + /** Specific script resource name which will be used to get server suffix */ private final static String SPECIFIC_SCRIPT_RESOURCE_NAME = "org/richfaces/renderkit/html/1$1.js"; + /** Specific xcss resource name which will be used to get server suffix */ private final static String SPECIFIC_XCSS_RESOURCE_NAME = "org/richfaces/renderkit/html/1$1.xcss"; - + + /** Regular expression pattern for finding elements for replacing and correcting */ private final static Pattern REGEXP = Pattern.compile("\\<(script|link|img|iframe)\\s+.*(?:src|href)\\s*=\\s*[\"']([^'\"]+)\\.([^\\'\"]+)[\"'][^>]*\\>", Pattern.CASE_INSENSITIVE); - /** + /* (non-Javadoc) * @see org.ajax4jsf.resource.BaseResourceRenderer#getCommonAttrs() */ @Override @@ -58,7 +63,7 @@ return null; } - /** + /* (non-Javadoc) * @see org.ajax4jsf.resource.BaseResourceRenderer#getHrefAttr() */ @Override @@ -66,7 +71,7 @@ return null; } - /** + /* (non-Javadoc) * @see org.ajax4jsf.resource.BaseResourceRenderer#getTag() */ @Override @@ -74,14 +79,14 @@ return "span"; } - /** + /* (non-Javadoc) * @see org.ajax4jsf.resource.ResourceRenderer#getContentType() */ public String getContentType() { return "text/html"; } - /** + /* (non-Javadoc) * @see org.ajax4jsf.resource.BaseResourceRenderer#send(org.ajax4jsf.resource.InternetResource, org.ajax4jsf.resource.ResourceContext) */ @Override @@ -104,8 +109,9 @@ } /** - * Method to correct scripts src - * @param resource + * Method to correct included resources src + * + * @param resource - html page to be checked */ private int updateAndSendResource(InputStream in, OutputStream out) throws IOException { @@ -159,14 +165,30 @@ return total; } - private String getSriptMappingSuffix() { + /** + * Method to get exact script resource URI suffix + * + * @return string with script resource URI suffix + */ + protected String getSriptMappingSuffix() { return getResourceSuffix(SPECIFIC_SCRIPT_RESOURCE_NAME); } - - private String getCssMappingSuffix() { + + /** + * Method to get exact xcss resource URI suffix + * + * @return string with xcss resource URI suffix + */ + protected String getCssMappingSuffix() { return getResourceSuffix(SPECIFIC_XCSS_RESOURCE_NAME); } - + + /** + * Method to get resource URI suffix which was added due to web.xml mappings + * + * @param resourceName - name of the resource which should be checked + * @return string with resource URI suffix which was added after resource name + */ private String getResourceSuffix(String resourceName) { InternetResourceBuilder builder = InternetResourceBuilder.getInstance(); InternetResource resource = builder.getResource(resourceName); @@ -179,7 +201,7 @@ return suffix; } - /** + /* (non-Javadoc) * @see org.ajax4jsf.resource.BaseResourceRenderer#requireFacesContext() */ @Override