001: /*
002: ItsNat Java Web Application Framework
003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
004: Author: Jose Maria Arranz Santamaria
005:
006: This program is free software: you can redistribute it and/or modify
007: it under the terms of the GNU Affero General Public License as published by
008: the Free Software Foundation, either version 3 of the License, or
009: (at your option) any later version. See the GNU Affero General Public
010: License for more details. See the copy of the GNU Affero General Public License
011: included in this program. If not, see <http://www.gnu.org/licenses/>.
012: */
013: package org.itsnat.core.domutil;
014:
015: import java.util.List;
016: import org.w3c.dom.DocumentFragment;
017: import org.w3c.dom.Element;
018:
019: /**
020: * Manages a pattern based DOM Element table.
021: *
022: * <p>The generic table structure is:</p>
023: *
024: * <pre>
025: <tableParent>
026: <row>
027: ...
028: <optRowContent>
029: <cell>
030: <opt1>...<optN>Pattern</optN>...</opt1>
031: </cell>
032: ...
033: </optRowContent>
034: ...
035: </row>
036: ...
037: </tableParent>
038: * </pre>
039: *
040: * <p>The starting point usually is a DOM table with a single row containing one or several cells
041: * this row is save as the pattern (really a deep clone) and used when new rows are added, the first cell
042: * of the pattern is used to create new cells (for instance a new column).
043: * The initial DOM table (including the row pattern) may be initially cleared
044: * or kept as is when this object is created and attached to the underlying DOM table.</p>
045: *
046: * <p>This type of table helps to render a table of values into the DOM element table,
047: * for instance, this interface support "out the box" the typical DOM element table where
048: * every cell element contains some value usually as the data of a text node.
049: * Methods to add new cells include optionally a <code>value</code> parameter.
050: * The structure and renderer objects are used to customize how and where this value is saved in the table
051: * beyond the default cases.</p>
052: *
053: * <p>Columns can be added or removed, if a column is removed/added the same column
054: * is removed/added to the row pattern too (in fact the table may be empty, no rows, but {@link #getColumnCount()}
055: * may be non-zero), the cell pattern is used to add new cells to the row pattern
056: * if necessary. All rows have the same number of columns.</p>
057: *
058: * <p>By default a just created table has one row if the row pattern is not removed
059: * or zero rows if removed and as many columns as declared in the row pattern.</p>
060: *
061: * <p>A pattern based DOM Element table ever works in "master" mode {@link ElementListFree#isMaster()}
062: *
063: * @see org.itsnat.core.ItsNatDocument#createElementTable(Element,boolean)
064: * @author Jose Maria Arranz Santamaria
065: */
066: public interface ElementTable extends ElementTableBase {
067: /**
068: * Returns the current structure used by this table.
069: *
070: * @return the current structure.
071: * @see #setElementTableStructure(ElementTableStructure)
072: */
073: public ElementTableStructure getElementTableStructure();
074:
075: /**
076: * Sets the structure used by this table.
077: *
078: * @param structure the new structure.
079: * @see #getElementTableStructure()
080: */
081: public void setElementTableStructure(ElementTableStructure structure);
082:
083: /**
084: * Returns the current renderer used by this table.
085: *
086: * @return the current renderer.
087: * @see #setElementTableRenderer(ElementTableRenderer)
088: */
089: public ElementTableRenderer getElementTableRenderer();
090:
091: /**
092: * Sets the renderer used by this table.
093: *
094: * @param renderer the new renderer.
095: * @see #getElementTableRenderer()
096: */
097: public void setElementTableRenderer(ElementTableRenderer renderer);
098:
099: /**
100: * Returns the element used as a row pattern. This element may be a clone of the
101: * original first row used as a pattern.
102: *
103: * @return the row pattern element.
104: */
105: public Element getRowPatternElement();
106:
107: /**
108: * Returns the element used as a cell pattern. This element may be a clone of the
109: * original first cell used as a pattern.
110: *
111: * @return the cell pattern element.
112: */
113: public Element getCellPatternElement();
114:
115: /**
116: * Increases or shrinks the number of rows to fit the new size.
117: *
118: * <p>If the new size is bigger new rows are added at the end, if the size
119: * is lower tail rows are removed.</p>
120: *
121: * @param rowCount the new number of rows.
122: * @see #getRowCount()
123: * @see #addRow()
124: * @see #removeRowAt(int)
125: */
126: public void setRowCount(int rowCount);
127:
128: /**
129: * Adds a new row element at the end of the table using the row pattern (the new row is a clone).
130: *
131: * @return the new row element.
132: * @see #addRow(Object[])
133: */
134: public Element addRow();
135:
136: /**
137: * Adds a new row element at the end of the table using the row pattern, and renders the specified values using
138: * the current structure and renderer.
139: *
140: * @param rowData the row values to render.
141: * @return the new row element.
142: * @see #addRow()
143: * @see #getElementTableStructure()
144: * @see #getElementTableRenderer()
145: * @see ElementTableStructure
146: * @see ElementTableRenderer#renderTable(ElementTable,int,int,Object,Element,boolean)
147: */
148: public Element addRow(Object[] rowData);
149:
150: /**
151: * Adds a new row element at the end of the table using the row pattern, and renders the specified values using
152: * the current structure and renderer.
153: *
154: * @param rowData the row values to render.
155: * @return the new row element.
156: * @see #addRow(Object[])
157: */
158: public Element addRow(List rowData);
159:
160: /**
161: * Inserts a new row element at the specified position using the row pattern.
162: *
163: * @param row index of the new row.
164: * @return the new row element.
165: * @see #insertRowAt(int,Object[])
166: */
167: public Element insertRowAt(int row);
168:
169: /**
170: * Inserts a new row element at the specified position using the row pattern, and renders the specified row values using
171: * the current structure and renderer.
172: *
173: * @param row index of the new row.
174: * @param rowData the row values to render.
175: * @return the new row element.
176: * @see #insertRowAt(int)
177: * @see #getElementTableStructure()
178: * @see #getElementTableRenderer()
179: * @see ElementTableStructure
180: * @see ElementTableRenderer#renderTable(ElementTable,int,int,Object,Element,boolean)
181: */
182: public Element insertRowAt(int row, Object[] rowData);
183:
184: /**
185: * Inserts a new row element at the specified position using the row pattern and renders the specified row values using
186: * the current structure and renderer.
187: *
188: * @param row index of the new row.
189: * @param rowData the row values to render.
190: * @return the new row element.
191: * @see #insertRowAt(int,Object[])
192: */
193: public Element insertRowAt(int row, List rowData);
194:
195: /**
196: * Renders the specified values into the row with the given position
197: * using the current structure and renderer.
198: *
199: * @param row index of the row.
200: * @param rowData the row values to render.
201: * @see #insertRowAt(int,Object[])
202: * @see #getElementTableStructure()
203: * @see #getElementTableRenderer()
204: * @see ElementTableStructure
205: * @see ElementTableRenderer#renderTable(ElementTable,int,int,Object,Element,boolean)
206: */
207: public void setRowValuesAt(int row, Object[] rowData);
208:
209: /**
210: * Renders the specified values into the row with the given position
211: * using the current structure and renderer.
212: *
213: * @param row index of the row.
214: * @param rowData the row values to render.
215: * @see #setRowValuesAt(int,Object[])
216: */
217: public void setRowValuesAt(int row, List rowData);
218:
219: /**
220: * Returns the "content" element of the row, this element is the parent of the row cells
221: * This element is obtained using the current structure.
222: *
223: * @param row index of the row.
224: * @return the content element of the row.
225: * @see #getElementTableStructure()
226: * @see ElementTableStructure#getRowContentElement(ElementTable,int,Element)
227: */
228: public Element getRowContentElementAt(int row);
229:
230: /**
231: * Returns the "content" element of the cell, this element is used to render below
232: * the associated value of the cell. This element is obtained
233: * using the current structure.
234: *
235: * @param row index of the row.
236: * @return the content element of the row.
237: * @see #getElementTableStructure()
238: * @see ElementTableStructure#getCellContentElement(ElementTable,int,int,Element)
239: */
240: public Element getCellContentElementAt(int row, int column);
241:
242: /**
243: * Adds a new column at the end of columns using the cell pattern.
244: *
245: * @return the new cell elements.
246: * @see #addColumn(Object[])
247: */
248: public Element[] addColumn();
249:
250: /**
251: * Adds a new column at the end of columns using the cell pattern, and renders the specified values using
252: * the current structure and renderer.
253: *
254: * @param columnData the column values to render.
255: * @return the new cell elements.
256: * @see #addColumn()
257: * @see #getElementTableStructure()
258: * @see #getElementTableRenderer()
259: * @see ElementTableStructure
260: * @see ElementTableRenderer#renderTable(ElementTable,int,int,Object,Element,boolean)
261: */
262: public Element[] addColumn(Object[] columnData);
263:
264: /**
265: * Adds a new column at the end of columns using the cell pattern, and renders the specified values using
266: * the current structure and renderer.
267: *
268: * @param columnData the column values to render.
269: * @return the new cell elements.
270: * @see #addColumn(Object[])
271: */
272: public Element[] addColumn(List columnData);
273:
274: /**
275: * Inserts a new column at the specified position using the cell pattern.
276: *
277: * @param column index of the new column.
278: * @return the new cell elements.
279: * @see #insertColumnAt(int,Object[])
280: */
281: public Element[] insertColumnAt(int column);
282:
283: /**
284: * Inserts a new column at the specified position using the cell pattern,
285: * and renders the specified values using
286: * the current structure and renderer.
287: *
288: * @param column index of the new column.
289: * @param columnData the column values to render.
290: * @return the new cell elements.
291: * @see #insertColumnAt(int)
292: * @see #getElementTableStructure()
293: * @see #getElementTableRenderer()
294: * @see ElementTableStructure
295: * @see ElementTableRenderer#renderTable(ElementTable,int,int,Object,Element,boolean)
296: */
297: public Element[] insertColumnAt(int column, Object[] columnData);
298:
299: /**
300: * Inserts a new column at the specified position using the cell pattern,
301: * and renders the specified values using
302: * the current structure and renderer.
303: *
304: * @param column index of the new column.
305: * @param columnData the column values to render.
306: * @return the new cell elements.
307: * @see #insertColumnAt(int,Object[])
308: */
309: public Element[] insertColumnAt(int column, List columnData);
310:
311: /**
312: * Renders the specified values into the column with the given position
313: * using the current structure and renderer.
314: *
315: * @param column index of the column.
316: * @param columnData the column values to render.
317: * @see #insertColumnAt(int,Object[])
318: * @see #getElementTableStructure()
319: * @see #getElementTableRenderer()
320: * @see ElementTableStructure
321: * @see ElementTableRenderer#renderTable(ElementTable,int,int,Object,Element,boolean)
322: */
323: public void setColumnValuesAt(int column, Object[] columnData);
324:
325: /**
326: * Renders the specified values into the column with the given position
327: * using the current structure and renderer.
328: *
329: * @param column index of the column.
330: * @param columnData the column values to render.
331: * @see #setColumnValuesAt(int,Object[])
332: */
333: public void setColumnValuesAt(int column, List columnData);
334:
335: /**
336: * Returns the number of columns.
337: *
338: * @see #setColumnCount(int)
339: * @return the number of columns.
340: */
341: public int getColumnCount();
342:
343: /**
344: * Increases or shrinks the number of columns to fit the new size.
345: *
346: * <p>If the new size is bigger new columns are added at the end, if the size
347: * is lower tail columns are removed.</p>
348: *
349: * @param columnCount the new number of columns.
350: * @see #getColumnCount()
351: * @see #addColumn()
352: * @see #removeColumnAt(int)
353: */
354: public void setColumnCount(int columnCount);
355:
356: /**
357: * Renders the specified value into the cell element with the given row and column position
358: * using the current structure and renderer.
359: *
360: * @param row row of the cell.
361: * @param column column of the cell.
362: * @param value the value to render.
363: * @see #getElementTableStructure()
364: * @see #getElementTableRenderer()
365: * @see ElementTableStructure
366: * @see ElementTableRenderer#renderTable(ElementTable,int,int,Object,Element,boolean)
367: */
368: public void setCellValueAt(int row, int column, Object value);
369:
370: /**
371: * Renders all table cells with new values
372: * using the current structure and renderer.
373: *
374: * @param values the values to render.
375: * @see #getElementTableStructure()
376: * @see #getElementTableRenderer()
377: * @see ElementTableStructure
378: * @see ElementTableRenderer#renderTable(ElementTable,int,int,Object,Element,boolean)
379: */
380: public void setTableValues(Object[][] values);
381:
382: /**
383: * Renders all table cells with new values
384: * using the current structure and renderer.
385: *
386: * @param values the values to render.
387: * @see #setTableValues(Object[][])
388: */
389: public void setTableValues(List values);
390:
391: /**
392: * Informs whether the original (saved as pattern) markup is used to render.
393: *
394: * <p>The default value is defined by {@link org.itsnat.core.ItsNatDocument#isUsePatternMarkupToRender()}</p>
395: *
396: * @return true if the original markup is used.
397: * @see #setUsePatternMarkupToRender(boolean)
398: */
399: public boolean isUsePatternMarkupToRender();
400:
401: /**
402: * Sets whether the original (saved as pattern) markup is used to render.
403: *
404: * @param value true to enable the use of original markup to render.
405: * @see #isUsePatternMarkupToRender()
406: */
407: public void setUsePatternMarkupToRender(boolean value);
408:
409: /**
410: * Returns the pattern used to render values if {@link #isUsePatternMarkupToRender()}
411: * is true.
412: *
413: * @return the pattern used to render values.
414: */
415: public DocumentFragment getCellContentPatternFragment();
416: }
|