A Guide for Building a New Web Application from the HudWebFramework

The purpose of this guide is to create a sample GIS web app based on HudWebFramework.

### 1. Copying and setting up application from base template

Although it is not necessary the folder `base` can be used as a template to create your own Web app. The folder base contains three subfolders: `config`, `css`, and `images` as shown below:

![subfolders](images/subfolders.png)

> Note: this guide uses Windows environment and your own OS and file manager may vary. You can also create your own config, css and images subfolders and files inside each subfolder.

Copy and paste base folder next to `Hud.Gis.Web` folder, which is the folder of HudWebFramework, then rename base to `Hud.Sample`. Next you need to create an `index.html` file inside the new Hud.Sample folder:

![index.html](images/index.html.png)

Open the index.html file with a text editor and copy&paste the code below to it:
```html
<!DOCTYPE html>
<head>
    <title>HUD Sample</title>
    <link rel="stylesheet" href="/Gis/scripts/bootstrap/3.3.4/css/bootstrap.min.css" />
    <link rel="stylesheet" href="//js.arcgis.com/3.13/esri/css/esri.css" />
    <style type="text/css">
        #mapDiv {
            position: relative;
        }

#page-container {
            margin-right: 0 !important;
            margin-left: 0 !important;
        }
    </style>
</head>
<body>
    <div id="logo"></div>
    <div id="page-container" class="row">
        <div id="mapDiv">
        </div>
    </div>
    <script type="text/javascript">
        var loadingGraphicStyle = "bottom:10px;left:10px;";
        var loadingMessage = "Loading...";

var host =
            location.protocol + "//" +
            location.host;

var subDirectory = "/Gis";
        var flag = false;
        var apiPath = host + subDirectory;

var appPath = location.origin + location.pathname;

var dojoConfig = {
            packages: [{
                name: "esri-bootstrap",
                location: apiPath + "/scripts/bootstrap-esri"
            }, {
                name: "Hud.Gis",
                location: apiPath + "/scripts/modules"
            }]
        };
    </script>

![iis](images/iis.png)

### 2. Adding basic toolbar
The config folder comes with a pre-configured `app.json` file but you can also create your own from scratch. Open app.json file with a text editor and copy&paste the code below:
``` json
{
    "fullTitle": "HUD Sample Web App",
    "smallTitle": "HUD Sample",
    "modules": [
        {
            "name": "BasicToolbar",
            "namespace": "Hud.Common/BasicToolbar/ToolbarController"
        }
    ]
}
```
### 3. Adding basemap picker
The config folder comes with a pre-configured `basemap.json` file and again you can always create your own. Simply add a few base maps in the given format:
```json
{
    "gray": {
        "title": "default",
        "name": "Light Gray Canvas",
        "baseMapLayers": [
            {
                "url": "http://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Base/MapServer"
            },
            {
                "url": "http://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Reference/MapServer",
                "isReference": true
            }
        ]
    },
    "streets": {
        "title": "streets",
        "name": "Streets",
        "baseMapLayers": [
            {
                "url": "http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer"
            }
        ]
    },
    "satellite": {
        "title":  "satellite",
        "name": "Satellite",
        "baseMapLayers": [
            {
                "url": "http://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer"
            }
        ]
    },
    "hybrid": {
        "title": "hybrid",
        "name": "Imagery with Labels",
        "baseMapLayers": [
            {
                "url": "http://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer"
            },
            {
                "url": "http://services.arcgisonline.com/ArcGIS/rest/services/Reference/World_Boundaries_and_Places/MapServer",
                "isReference": true
            }
        ]
    },
    "topo": {
        "title": "topo",
        "name": "Topographic",
        "baseMapLayers": [
            {
                "url": "http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer"
            }
        ]
    },
    "oceans": {
        "title": "oceans",
        "name": "Oceans",
        "baseMapLayers": [
            {
                "url": "http://services.arcgisonline.com/ArcGIS/rest/services/Ocean_Basemap/MapServer"
            }
        ]
    },
    "national-geographic": {
        "title": "national-geographic",
        "name": "National Geographic",
        "baseMapLayers": [
            {
                "url": "http://services.arcgisonline.com/ArcGIS/rest/services/NatGeo_World_Map/MapServer"
            }
        ]
    },
    "osm": {
        "title": "osm",
        "name": "OpenStreetMap",
        "baseMapLayers": [
            {
                "type": "OpenStreetMap"
            }
        ]
    }
}
```
> Note: Here we only added a few most commonly used base maps: Light Gray Canvas, Streets, Satellite, Imagery with Labels, Topographic, Oceans, National Geographic and OpenStreetMap. You may also find other base maps from [Sample GIS Server and GIS Services](http://services.arcgisonline.com/ArcGIS/rest/services/). Simply add the base map services in the given format as shown above.

If you have trouble adding basemap picker please check if the following code in highlight is added in HudWebFramework:

- In `Hud.Gis.Web\scripts\modules\Common\BasicToolbar\ToolbarController.js` look for

![basemappicker1](images/basemappicker1.png)

![basemappicker2](images/basemappicker2.png)

### 4. Adding location picker
If you already added basic toolbar to Hud.Sample\config\app.json you would not need to do anything because basic toolbar already includes location search tool. If you have trouble adding it please check if the following code in highlight is added in HudWebFramework:

- In `Hud.Gis.Web\scripts\modules\Common\BasicToolbar\ToolbarController.js` look for

![locationsearch1](images/locationsearch1.png)

![locationsearch2](images/locationsearch2.png)

### 5. Adding map layers via the map.json file
The config folder comes with a pre-configured `map.json` file. A JSON viewer helps convert JSON strings to a friendly readable format so open map.json with your prefered JSON viewer and it should look similar to this:

![map.json](images/map.json.png)

Where you need to add opertiaonal layers and initial base map to code blocks `operationalLayers` and `baseMap`, respectively. Also if you want to add pop-ups the config code needs to be placed to code block `popupInfo`:

![popups](images/popups.png)

A working JSON sample is provided below:
```json
{
    "item": {
        "title": "HUD",
        "snippet": "HUD National Map",
        "extent": [
            [
                -139.4916,
                10.7191
            ],
            [
                -52.392,
                59.5199
            ]
        ]
    },
    "itemData": {
        "operationalLayers": [
            {
                "url": "http://server.arcgisonline.com/arcgis/rest/services/Demographics/USA_2000-2010_Population_Change/MapServer/4",
                "id": "2000-2010-pop-change",
                "visibility": true,
                "opacity": 0.65,
                "title": "2000-2010 Population Change by State",
                "name": "2000-2010 Population Change by State",
                "minScale": 0,
                "maxScale": 1500000,
                "popupInfo": {
                    "title": "Population Change",
                    "fieldInfos": [
                        {
                            "fieldName": "OBJECTID",
                            "label": "OBJECTID",
                            "isEditable": false,
                            "tooltip": "",
                            "visible": false,
                            "stringFieldOption": "textbox"
                        },
                        {
                            "fieldName": "ST_ABBREV",
                            "label": "State Abbreviation",
                            "isEditable": false,
                            "tooltip": "",
                            "visible": true
                        },
                        {
                            "fieldName": "POPGRW0010",
                            "label": "2000-2010 Population Annual Compound Growth Rate (%)",
                            "isEditable": false,
                            "tooltip": "",
                            "visible": true,
                            "format": {
                                "places": 2
                            }
                        }
                    ],
                    "description": null,
                    "showAttachments": false,
                    "mediaInfos": [ ]
                }
            }
        ],
        "baseMap": {
            "baseMapLayers": [
                {
                    "id": "World_Light_Gray_Base_7739",
                    "opacity": 1,
                    "visibility": true,
                    "url": "http://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Base/MapServer"
                },
                {
                    "id": "World_Light_Gray_Reference_241",
                    "isReference": true,
                    "opacity": 1,
                    "visibility": true,
                    "url": "http://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Reference/MapServer"
                }
            ],
            "title": "gray"
        },
        "version": "1.7"
    }
}
```
### 6. Customizing the app with code
You can easily add existing modules to this Hud Sample Web app. For instance, there are two tools in the *Map Tools* dropdown menu:

![mapfilter](images/mapfilter.png)

Where *Background Layers* tool is the basemap picker inside the basic toolbar. Since we added basic toolbar in **2. Adding basic toolbar** and configured basemap.json in **3. Adding basemap picker** Background Layers is ready to work. The module we need for *Map Filter* can be found at `Hud.Gis.Web\scripts\modules\Common\MapFilter` then in `Hud.Gis.Web\scripts\modules\Common\BasicToolbar\ToolbarController.js` simply add the code in hightlight as shown below:

![mapfiltertobasictoolbar1](images/mapfiltertobasictoolbar1.png)

If you want to further develop *Map Filter* you can add the code inside the code block in highlight as shown below:

![mapfiltertobasictoolbar2](images/mapfiltertobasictoolbar2.png)

If you want to build your own common modules from scratch your can do so inside `Hud.Gis.Web\scripts\modules\Common` folder. Fortunately there is a `SampleTool` module found at `Hud.Gis.Web\scripts\modules\Common\SampleTool` which you can use as a template to build your own common modules. After build you need to extend `Viewport` module by adding the code in highlight as shown below to `Hud.Gis.Web\scripts\modules\Common\Viewport\ModuleController.js`:

![sampletool1](images/sampletool1.png)

Then you need to add the code in highlight as shown below to `app.json`:

![sampletool2](images/sampletool2.png)

To see the *Sample Tool* you might also need a ![sampletoolbutton](images/sampletoolbutton.png) button that triggers it. For demonstration purposes only we simply add the code in highlight as shown below to `index.html`:

![sampletool3](images/sampletool3.png)

### 7. Customizing the style/look of the app with CSS
To customize the style/look of the app with CSS you need to override the default Boostrap stylesheet with your own (for instance you may name it *bootstrap-override.css* and place it under the `css` folder) and add the code in highlight as shown below to `index.html`:

![bootstrapoverride](images/bootstrapoverride.png)

A working bootstrap-override.css sample is provided below:
```css
.navbar-default {
    background-color: #3981bf;
    border-color: #3170a5;
}

.navbar-default .navbar-collapse,
.navbar-default .navbar-form {
    border-color: #3170a5;
}

.navbar-default .navbar-brand:focus,
.navbar-default .navbar-brand:hover {
    color: white;
}

.navbar-default .navbar-brand,
.navbar-default .navbar-brand {
    color: white;
}

.navbar-default .navbar-nav>li>a:focus,
.navbar-default .navbar-nav>li>a:hover {
    color: white;
}

.navbar-default .navbar-nav>li>a {
    color: white;
}

.navbar-default .navbar-nav>li>a:hover {
    color: white;
    background-color: #1A6CB1;
}

.navbar-default .navbar-nav>.open>a,
.navbar-default .navbar-nav>.open>a:focus,
.navbar-default .navbar-nav>.open>a:hover {
    background-color: #1A6CB1;
    color: white;
}

.navbar-nav > li > .dropdown-menu {
    background-color: #1A6CB1;
    color: white;
}

.dropdown-menu>li>a:focus,
.dropdown-menu>li>a {
    color: #000000;
}

.dropdown-menu > li > a:focus,
.dropdown-menu > li > a:hover {
    background-color: #3981bf;
    color: white;
}
```
Where colors of the nav header and the dropdown menu are customized from a gray to a blue theme:

![graytoblue](images/graytoblue.png)

If you want to customize the color of icons, for instance, the color of the icon of *Map Tools* from default to blue simply add the code in highlight as shown below to `Hud.Gis.Web\scripts\modules\Common\BasicToolbar\ToolbarView.html`:

![iconcolor1](images/iconcolor1.png)

Alternatively, you may also add the code as a class to your icon and then set the font color to it in CSS, for instance:

HTML
```html
<span class="glyphicon glyphicon-cog blue"></span>
```
CSS
```css
.blue {
    color: blue;
}
```
Both should change the color of the icon of *Map Tools* from default to blue:

![iconcolor2](images/iconcolor2.png)

<hr/>