summaryrefslogtreecommitdiffstats
path: root/documentation/articles/MVCBasicsInITMillToolkit.asciidoc
blob: fb61ace2ca64173a9154384f9f4370f1c17b4b20 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
---
title: MVC Basics In IT Mill Toolkit
order: 24
layout: page
---

[[mvc-basics-in-itmill-toolkit]]
= MVC Basics in IT Mill Toolkit

The Goal
^^^^^^^^

image:img/moduleDesign.jpg[1]

We want to create a simple UI following the MVC pattern using the IT Mill Toolkit. The project components need to have low coupling and follow an enterprise design. In our example we also want to retrieve information from a database and display it in the view. The different parts of the UI need also to be able to communicate with each other.

We have divided the project in two layers; A UI layer, which purpose is to display information to the user, and a Data layer which has no knowledge of the Toolkit and which is only responsible for retrieving and storing data. The reason for dividing the project up in these layers is so that, if we choose, we can easily use multiple servers.

The Data layer
^^^^^^^^^^^^^^

For the example we have created a ''Database.java'' class which will function as our database. We will never call upon this database directly from the UI. To access the data we will have the UI controllers contact the ''Authentication.java'' or ''Channel.java'' which will retrieve it for us.

image:img/view.jpg[1]

image:img/ActivityUML.jpg[1]

The UI layer
^^^^^^^^^^^^

First off lets discuss what we mean with ''View''. The Toolkit is such an flexible tool that the term needs to be defined on pretty much a case by case basis. In this example we have decided to let the center portion of the UI be the View.

In our example the UI consists of the Header, Menu and View. When the user chooses a item from the menu we need to easily update the View or in our case, switch View completely. We want to do this in such a way that we don't couple the different UI components together so that we can easily add extra components if needed. To achieve this we use the Observer pattern which is easily implemented in the Toolkit using ''Events''.

== The Controller ==

We started off by creating the ''UiHandler.java'' class where we define which components we want to add to our UI. This class will also work as the mediator for the different components by adding ''Listeners'' and monitoring for events in the components.

[source,java]
....
public class UiHandler extends VerticalLayout {
  // Portions of the application that exist at all times.
  private Header header;
  private WelcomeView defaultView;

  // The views that are shown to logged users.
  private UserView userView;
  private ChannelView itmillView;
  private ChannelView ubuntuView;

  private Menu menu;
  private SplitPanel menusplit;

  // Used to keep track of the current main view.
  private HashMap<String, AbstractView> viewList = new HashMap<String, AbstractView>();

...
}
....

We want to listen for changes in the menu which indicates that the user has chosen a new item and wants to change view. The menu consists of a Tree component which generates a ''ValueChangeEvent'' when a new item is selected from the tree. We catch these types of events in the UiHandler by adding a UserChangeListener in the ExampleApplication.java init() method.

[source,java]
....
public class ExampleApplication extends Application implements TransactionListener {
  public UiHandler ui;

  @Override
  public void init() {
    // sets the current application to ThreadLocal.
    setProject(this);

    // Creates the Main Window and then hands over all UI work to the
    // UiHandler
    setMainWindow(new Window("MVC Example Application"));

    setTheme("MVCExampleDefault");

    ui = new UiHandler(getMainWindow());

    // Adds a TransactionListener for this class.
    getContext().addTransactionListener(this);

    // Register user change listener for UiHandler.
    addListener(ui);
  }
}
....

[source,java]
....
public class UiHandler extends VerticalLayout implements UserChangeListener {
  public void applicationUserChanged(UserChangeEvent event) {
    // The value is null if the user logs out.
    if (event.getNewUser() == null) {
      userLoggedOut();
    } else {
      userLoggedIn();
    }
  }
}
....

The menu is now isolated with no knowledge about other components.  This gives us great flexibility with adding new instances of the menu if needed.

The View
^^^^^^^^

Following the MVC-pattern we have removed all control logic from the Views and transferred it to the controllers. The Views now consist only of the elements needed to display the data while the controllers handle the retrieving and manipulating of said data. The separation between control logic and View is done so that, if needed, we may have many different views displaying the same data without having to copy code. We can now simply add a controller to each new View to gain the same data functionality as any other View.

[source,java]
....
public class ChannelView extends AbstractView {
  protected Window confirm;
  private ChannelController controller;

  public void sendMessage() {
    // Let the controller modify the current text on the inputline and
    // insert it into the channel text table.
    controller.writeToChannel(inputLine.getValue(), textTable);
    ...
  }
}
....

When creating a project you may want to have different views displayed at different times sosetting the view is an easy task. We are using the SplitPanel component to create two sections in the UI. Adding components to the ''SplitPanel'' is achieved with ''setFirstComponent(c)'' to add on the left side and ''setSecondComponent(c)'' to add on the right side of the split. By our definition, our view is the area on the right side of the split. Had we been using the Layout component we could have achieved the same result using ''replaceComponent(oldComponent, newComponent)''.

[source,java]
....
// Set the menu on the left side of the split.
menusplit.setFirstComponent(menu);

// Set the user welcome View on the right side.
setMainView(userView);

...

public void setMainView(AbstractView c) {
  menusplit.setSecondComponent(c);
}
....

Setting/Switching the View is now as easy as simply replacing the second component in the the SplitPanel using ''setMainView''.

The source code for this project can be found in the MVCBasicsProject.zip file where we've added the .project and .classpath for your convinience, in case you are a Eclipse user. Remove these files if you use some other IDE.
4'>214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239
/* ====================================================================
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You 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 org.apache.poi.hssf.usermodel;

import org.apache.poi.POITestCase;
import org.apache.poi.hssf.HSSFITestDataProvider;
import org.apache.poi.hssf.HSSFTestDataSamples;
import org.apache.poi.hssf.model.HSSFFormulaParser;
import org.apache.poi.hssf.record.NameRecord;
import org.apache.poi.ss.formula.FormulaType;
import org.apache.poi.ss.formula.ptg.Ptg;
import org.apache.poi.ss.usermodel.BaseTestNamedRange;
import org.apache.poi.ss.util.CellRangeAddress;
import org.junit.Test;

import static org.junit.Assert.*;

/**
 * Tests various functionality having to do with {@link org.apache.poi.ss.usermodel.Name}.
 */
public final class TestHSSFName extends BaseTestNamedRange {

    /**
     * For manipulating the internals of {@link HSSFName} during testing.<br>
     * Some tests need a {@link NameRecord} with unusual state, not normally producible by POI.
     * This method achieves the aims at low cost without augmenting the POI usermodel api.
     * @return a reference to the wrapped {@link NameRecord}
     */
    public static NameRecord getNameRecord(HSSFName definedName) {
        return POITestCase.getFieldValue(HSSFName.class, definedName, NameRecord.class, "_definedNameRec");
    }

    public TestHSSFName() {
        super(HSSFITestDataProvider.instance);
    }

    @Test
    public void testRepeatingRowsAndColumsNames() throws Exception {
         // First test that setting RR&C for same sheet more than once only creates a
         // single  Print_Titles built-in record
         HSSFWorkbook wb = new HSSFWorkbook();
         HSSFSheet sheet = wb.createSheet("FirstSheet");

         // set repeating rows and columns twice for the first sheet
         CellRangeAddress cra = CellRangeAddress.valueOf("A1:A3");
         for (int i = 0; i < 2; i++) {
             sheet.setRepeatingColumns(cra);
             sheet.setRepeatingRows(cra);
             sheet.createFreezePane(0, 3);
         }
         assertEquals(1, wb.getNumberOfNames());
         HSSFName nr1 = wb.getNameAt(0);

         assertEquals("Print_Titles", nr1.getNameName());
         // TODO - full column references not rendering properly, absolute markers not present either
         // assertEquals("FirstSheet!$A:$A,FirstSheet!$1:$3", nr1.getRefersToFormula());
         assertEquals("FirstSheet!A:A,FirstSheet!$A$1:$IV$3", nr1.getRefersToFormula());

         // Save and re-open
         HSSFWorkbook nwb = HSSFTestDataSamples.writeOutAndReadBack(wb);
         wb.close();

         assertEquals(1, nwb.getNumberOfNames());
         nr1 = nwb.getNameAt(0);

         assertEquals("Print_Titles", nr1.getNameName());
         assertEquals("FirstSheet!A:A,FirstSheet!$A$1:$IV$3", nr1.getRefersToFormula());

         // check that setting RR&C on a second sheet causes a new Print_Titles built-in
         // name to be created
         sheet = nwb.createSheet("SecondSheet");
         cra = CellRangeAddress.valueOf("B1:C1");
         sheet.setRepeatingColumns(cra);
         sheet.setRepeatingRows(cra);

         assertEquals(2, nwb.getNumberOfNames());
         HSSFName nr2 = nwb.getNameAt(1);

         assertEquals("Print_Titles", nr2.getNameName());
         assertEquals("SecondSheet!B:C,SecondSheet!$A$1:$IV$1", nr2.getRefersToFormula());

         nwb.close();
     }

    @Test
    public void testNamedRange() throws Exception {
        HSSFWorkbook wb1 = HSSFTestDataSamples.openSampleWorkbook("Simple.xls");

        //Creating new Named Range
        HSSFName newNamedRange = wb1.createName();

        //Getting Sheet Name for the reference
        String sheetName = wb1.getSheetName(0);

        //Setting its name
        newNamedRange.setNameName("RangeTest");
        //Setting its reference
        newNamedRange.setRefersToFormula(sheetName + "!$D$4:$E$8");

        //Getting NAmed Range
        HSSFName namedRange1 = wb1.getNameAt(0);
        //Getting it sheet name
        sheetName = namedRange1.getSheetName();
        assertNotNull(sheetName);

        // sanity check
        SanityChecker c = new SanityChecker();
        c.checkHSSFWorkbook(wb1);

        HSSFWorkbook wb2 = HSSFTestDataSamples.writeOutAndReadBack(wb1);
        HSSFName nm = wb2.getNameAt(wb2.getNameIndex("RangeTest"));
        assertEquals("Name is " + nm.getNameName(), "RangeTest", nm.getNameName());
        assertEquals(wb2.getSheetName(0)+"!$D$4:$E$8", nm.getRefersToFormula());
        wb2.close();
        wb1.close();
    }

    /**
     * Reads an excel file already containing a named range.
     * <p>
     * Addresses Bug <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=9632" target="_bug">#9632</a>
     */
    @Test
    public void testNamedRead() throws Exception {
        HSSFWorkbook wb = HSSFTestDataSamples.openSampleWorkbook("namedinput.xls");

        //Get index of the named range with the name = "NamedRangeName" , which was defined in input.xls as A1:D10
        int NamedRangeIndex     = wb.getNameIndex("NamedRangeName");

        //Getting NAmed Range
        HSSFName namedRange1 = wb.getNameAt(NamedRangeIndex);
        String sheetName = wb.getSheetName(0);

        //Getting its reference
        String reference = namedRange1.getRefersToFormula();

        assertEquals(sheetName+"!$A$1:$D$10", reference);

        HSSFName namedRange2 = wb.getNameAt(1);

        assertEquals(sheetName+"!$D$17:$G$27", namedRange2.getRefersToFormula());
        assertEquals("SecondNamedRange", namedRange2.getNameName());
        
        wb.close();
    }

    /**
     * Reads an excel file already containing a named range and updates it
     * <p>
     * Addresses Bug <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=16411" target="_bug">#16411</a>
     */
    @Test
    public void testNamedReadModify() throws Exception {
        HSSFWorkbook wb = HSSFTestDataSamples.openSampleWorkbook("namedinput.xls");

        HSSFName name = wb.getNameAt(0);
        String sheetName = wb.getSheetName(0);

        assertEquals(sheetName+"!$A$1:$D$10", name.getRefersToFormula());

        name = wb.getNameAt(1);
        String newReference = sheetName +"!$A$1:$C$36";

        name.setRefersToFormula(newReference);
        assertEquals(newReference, name.getRefersToFormula());
        
        wb.close();
    }

     /**
      * Test to see if the print area can be retrieved from an excel created file
      */
    @Test
    public void testPrintAreaFileRead() throws Exception {
        HSSFWorkbook workbook = HSSFTestDataSamples.openSampleWorkbook("SimpleWithPrintArea.xls");

        String sheetName = workbook.getSheetName(0);
        String reference = sheetName+"!$A$1:$C$5";

        assertEquals(reference, workbook.getPrintArea(0));
        workbook.close();
    }

    @Test
    public void testDeletedReference() throws Exception {
        HSSFWorkbook wb = HSSFTestDataSamples.openSampleWorkbook("24207.xls");
        assertEquals(2, wb.getNumberOfNames());

        HSSFName name1 = wb.getNameAt(0);
        assertEquals("a", name1.getNameName());
        assertEquals("Sheet1!$A$1", name1.getRefersToFormula());
        wb.getCreationHelper().createAreaReference(name1.getRefersToFormula());
        assertTrue("Successfully constructed first reference", true);

        HSSFName name2 = wb.getNameAt(1);
        assertEquals("b", name2.getNameName());
        assertEquals("Sheet1!#REF!", name2.getRefersToFormula());
        assertTrue(name2.isDeleted());
        try {
            wb.getCreationHelper().createAreaReference(name2.getRefersToFormula());
            fail("attempt to supply an invalid reference to AreaReference constructor results in exception");
        } catch (IllegalArgumentException e) { // TODO - use a stronger typed exception for this condition
            // expected during successful test
        }
        wb.close();
    }

    /**
     * When setting A1 type of references with HSSFName.setRefersToFormula
     * must set the type of operands to Ptg.CLASS_REF,
     * otherwise created named don't appear in the drop-down to the left of formula bar in Excel
     */
    @Test
    public void testTypeOfRootPtg() throws Exception {
        HSSFWorkbook wb = new HSSFWorkbook();
        wb.createSheet("CSCO");

        Ptg[] ptgs = HSSFFormulaParser.parse("CSCO!$E$71", wb, FormulaType.NAMEDRANGE, 0);
        for (Ptg ptg : ptgs) {
            assertEquals('R', ptg.getRVAType());
        }
        wb.close();
    }
}