Карта (geomap) в Showcase

Материал из Course Orchestra
Перейти к: навигация, поиск
Showcase

Создание решений на КУРС:Showcase

Карта (geomap)

Интерфейс хранимой процедуры:

CREATE PROC 
	@main_context varchar(MAX)='',
	@add_context varchar(MAX)='',
	@filterinfo xml='',
        @session_context xml='',
        @element_Id varchar(MAX)='',
	@geomapsettings xml='' output

Общая структура данных

Подложка и другие статические свойства карты задаются шаблоном. На карте может быть N слоев, каждый из которых содержит M1 выделенных областей или M2 точек в зависимости от своего типа. Точки и области - это объекты на карте. Каждой области слоя соответствует K1 показателей областей, а каждой точке слоя соответствует K2 показателей точек. Таким образом, одновременно каждый слой будет иметь свой набор показателей. Событиями на карте являются клик по области или клик по точке. В будущем (!) возможно внедрение события клика по показателю.

  • Замечание 1. Линии тоже возможны вместе с кликами по ним. Такие примеры уже у нас были - реконструкция и строительство дорог в Минрегионе.
  • Замечание 2. Должна быть поддержка шкалы времени. Возможен такой сценарий. Около карты расположен бегунок, при передвижении которого интерактивно показываются данные для соответствующего момента времени.

Структура mapsettings

См. схему mapsettings.xsd и mapProperties.xsd

<geomapsettings>
    <filters>
        <filter id="код фильтра" caption="наименование фильтра" type="пока только text" 
           query="применимо только для фильтров не типа текст">
        <filter ...>
    </filters>
    <labels>
        <header>некий html-текст</header>
        <footer>некий html-текст</footer>
    </labels>
    <action>
	default action
    </action>
    <exportSettings width="1280" height="1024" backgroundColor="#FFFFFF" jpegQuality="90" fileName="map"/>
    <properties legend="right" width="" height=""/>
    <template>json файл с параметрами</template>
</geomapsettings>

legend - положение легенды. В легенде могут отображаться:

  • список слоев с возможностью из включения\выключения;
  • список выделенных областей для каждого слоя;
  • список показателей для каждого слоя;
  • диапазоны значения при раскраске карты по значениям какого-то показателя.

Что именно будет в легенде, определяется шаблоном.


Настройки экспорта

В свойстве exportSettings хранятся динамические настройки экспорта карты, индивидуальные для каждого экземпляра карты:

Параметр Описание Форматы, для которых применимо Примечания
filename имя файла для сохранения все без расширения, только символы английского алфавита
width ширина создаваемого изображения JPG и PNG
height высота создаваемого изображения JPG и PNG
backgroundColor цвет фона для создаваемого изображения JPG и PNG
jpegQuality качество сжатия JPEG JPG

Если один из размеров не задан - полученное изображение автоматически вычислит второй размер исходя из принципа сохранения пропорций. Если параметр backgroundColor не задан, то изображение в формате PNG создается прозрачным, а в формате JPG – с белой подложкой.

Для того чтобы включить экспорт в карту нужно сделать видимой панель с кнопками экспорта для карты. Внешний вид панели настраивается в профайле карты: %userdata%\geomapproperties\default.properties. Если такого профайла нет, его нужно создать.

Параметры профайла карты описаны в следующей таблице:

Параметр Возможные значения Описание
buttons.panel.visible true false видимость панели
exporttopng.button.visible true false видимость кнопки экспорта в PNG
exporttojpg.button.visible true false видимость кнопки экспорта в JPG
exporttosvg.button.visible true false видимость кнопки экспорта в SVG
buttons.panel.position TOP BOTTOM LEFT RIGHT расположение панели относительно карты с легендой

Замечание о расположении элементов карты:

  • в центре располагается собственно карта
  • слева\справа\сверху\снизу от нее располагается легенда
  • слева\справа\сверху\снизу от карты с легендой располагается панель с кнопками
  • сверху от всего этого располагается header, снизу - footer.

Таблицы

Хранимая процедура построения карты также формирует и возвращает 5 таблиц с данными для элементов карты в указанном ниже порядке. Если формируются только первые две таблицы, то мы получим карту региона с точками. Если формируются только первые три таблицы, то мы получим карту с точками и выделенными областями. Ниже показана структура этих таблиц.

Слои

ID Name ObjectType HintFormat (необяз.)

В этой таблице в столбце ObjectType указывается тип слоя: POINT или POLYGON. В столбце HintFormat задается общий шаблон подсказки для всех объектов графика. Можно задавать следующие шаблоны:

%LayerID ID слоя
%LayerName имя слоя
%ObjectType тип объекта
%ObjectID ID объекта
%ObjectName имя объекта
%Lat Широта
%Lon Долгота


Пример: %LayerName - %ObjectName (%ObjectID) (%Lat - %Lon).

Точки (например, для обозначения городов)

ID Name Lat Lon LayerID Tooltip (необяз.) StyleClass (необяз.) ~~properties (необяз.)

В столбце ID задается уникальный для всех точек и всех областей код в виде строки, формат которой определяется используемыми геоданными! Это, по сути, уникальный идентификатор любого объекта на карте. Стиль точки (StyleClass) задается некой строкой-константой. Список возможных стилей должен быть задан в шаблоне. Lat и Lon - широта и долгота. Сейчас они обязательно задаются, но в будущем данное поведение может измениться. Здесь и далее ID, Name, Lat и Lon берутся из таблицы с геоданными - [dbo].[geodata].

Столбец ~~properties здесь и далее содержит описание события, связанного с данным объектом, например:.

	<event name="single_click">
		<ссылка/>
	</event>

Полигоны (например, для отображения областей)

ID Name GeometryID LayerID Tooltip (необяз.) Color (необяз.) StyleClass (необяз.) ~~properties (необяз.)

В данной таблице содержатся "активные" на карте области - то есть области, для которых заданы показатели, цвет, подсказки, события. Если цвет по умолчанию для области не задан, то она не подсвечивается или подсвечивается на основе значения показателя (см. ниже). Стиль (StyleClass) и цвет не имеет смысла задавать одновременно, т.к. стиль включает в себя цвет. Необязательность здесь и далее означает, что этот столбец можно не формировать! В столбце GeometryID указывается идентификатор гео-объекта в БД.

Показатели

ID Name LayerID Color (необяз) isMain (необяз)

В столбце isMain указывается признак показателя, на основе которого будут подсвечиваться области в данном слое. Этот признак учитывается только для показателя из слоя типа область (AREA). Конкретный цвет, в который будет подсвечена область, задается в шаблоне. Режим подсветки на основе значения имеет приоритет над цветом области по умолчанию.

Если цвет не задан - разные показатели подсвечиваются разными произвольно выбранными цветами, зашитыми в схеме.

Значения показателей

IndicatorID ObjectID Value (число) ~~properties (необяз.)

Структура JSON для шаблона карты

Шаблон сейчас разделен на 2 части - динамическую - связанную с данными и задаваемую в хранимой процедуре, и статическую - задаваемую в js файле. Ссылка на статическую часть задается в шаблоне из БД. Приведенный ниже пример демонстрирует различные способы задания настроек карты и стилей карты.

	{
registerSolutionMap: russia_ym,  

       style: [
{
       stroke: "yellow",
       fill: "green",
       strokeWidth: 1,
       text: {
               attr: "name",
               fill: "black",
               font: {size:"10px"}
       }       
},
{
       filter: "this.type==''Point''",
       strokeWidth: 2,
       fill: "blue",
       shape: "circle"
       
},
{	  
    styleClass: "cityStyle",
    point: {
       shape:"star",
       strokeWidth: 1,
       stroke: "black",
       fill: "red"
    }
},
{
       theme: "highlight",
       styleClass: "RU-AL",	
       stroke: "black",
       fill: "yellow"
},
{
    fid: "71",
    stroke: "red",
    strokeWidth: 3,
    fill: "purple"
},
{
    size: [20, 30],
    img: "solutions/default/resources/1.jpg"
},	
{
		fid: "l2",
		stroke: "black",
		strokeWidth: 1,
		styleFunction: {
			getStyle: "djeo.util.numeric.getStyle",
			options: {
				numClasses: 7,
				colorSchemeName: "Reds",
				attr: "mainInd",
				breaks: "djeo.util.jenks.getBreaks",
				calculateStyle: "djeo.util.colorbrewer.calculateStyle"
			}
		},
		legend: "djeo._getBreaksAreaLegend",
        	name: "PMS3a (размер)",
	}
]
}

Стили карты задаются в виде массива. При этом они могут действовать либо на все элементы карты, либо только на определенные подмножества объектов:

  • с определенным styleClass, напимер, styleClass: "cityStyle";
  • на определенные типы объектов, например, point или polygon: filter: «this.type==Point» или filter: «this.type==Polygon»;
  • только на объекты с определенным id, напимер, fid: "71".

В случае задания нескольких стилей, применимых для конкретного объекта на карте, применяется последний.

Точки на карте могут быть двух типов: векторные и растровые. Ниже показано задание стиля для векторной точки:

{      
    size: [10, 20],     
    strokeWidth: 2,
    fill: "blue",
    shape: "circle"
}

Стиль для растровой точки (ссылка на картинку) задается следующим образом:

{
    size: [10, 20],
    img: "solutions/default/resources/1.jpg"
}

где

  • size - общий атрибут, задает размер точки в пикселях;
  • strokeWidth - ширина границ точки в пикселях;
  • fill - цвет точки;
  • shape - фигура точки, может принимать одно из следующих значений: circle, star...;
  • img - путь к изображению для точки. Поддерживаются абсолютные пути и пути относительно Showcase. Напоминаю: каталог для иконок решения - resources - развертывается в solutions/%userdata_name%/resources.


Шаблон карты может содержать функцию для раскраски полигонов или точек по значению показателя. Данная функция задается внутри стиля в следующем формате:

	styleFunction: {
		getStyle: "djeo.util.numeric.getStyle",
		options: {
			numClasses: 7,
			attr: "mainInd",
			breaks: "djeo.util.jenks.getBreaks",
			colorSchemeName: "Reds",
			calculateStyle: "djeo.util.colorbrewer.calculateStyle"
		}
	},

Здесь attr: "mainInd" - имя показателя по которому идет раскраска. Данный параметр всегда должен равняться mainInd! Чтобы раскраска работала необходимо задать styleClass или fid слоя.

Кроме того, можно настроить автоматическую установку размера точек в зависимости от значения показателя:

        styleFunction: {
		getStyle: "djeo.util.numeric.getStyle",
		options: {
			numClasses: 7,
			attr: "mainInd",
			breaks: "djeo.util.jenks.getBreaks",
			medianSize: 24,
			sizeStep: 3,
			calculateStyle: "djeo.util.numeric.calculateSizeStyle"
		}
	}					
}

Легенда, отображающая раскраску по значениям показателей, задается в том же стиле, что и функция, отвечающая за раскраску:

legend: "djeo._getBreaksAreaLegend"

Подписи к городам и регионам можно задать с помощью следующего кода:

       text: {
               attr: "name",
               fill: "red",
               font:  {family: "serif", variant: "small-caps", weight: "bold", size:"10px"}
       }

где параметр attr определяет, что именно будет в подписи. Чаще всего это название объекта (name). Другие возможные значения для attr показаны в следующей таблице:

Значение Описание
id идентификатор объекта
styleClass класс стиля объекта
geometryId идентификатор геометрических координат региона

Параметр fill - это цвет подписи, а font - характеристика шрифта подписи. Соответствие атрибутов шрифта и CSS:

family generic-family
variant font-variant
weight font-weight
size font-size

Более подробное описание шаблона будет представлено в ноябре 2011 года Володей.

Подключение подложки

Процесс подключения подложки разделяется на 3 этапа:

Этап I. Выбор или создание файла подложки:

Две подложки с полной картой РФ в разных проекциях включены в дистрибутив в виде следующих файлов:

  • data\geo\russia_geometries.js
  • data\geo\russia_geometriesEpsg4326.js.

Если же нужна карта другого региона, то ее нужно создать самостоятельно.

При работе с подложками необходимо знать ряд вещей. Каждая карта должна быть включена в определенное пространство имен. Пространство имен - это псевдоним для пути к js скриптам. Оно может состоять из нескольких частей, разделенных точками.

Пространство имен указывается в начале файла подложки следующим образом:

dojo.provide("${namespase}.${filename}");
${namespase}.${filename} = ...

Для встроенных подложек пространство имен - courseApp.data.geo.

При создании новых карт нужно использовать пространство имен solution. Оно ссылается на каталог js в userdata решения. Например:

dojo.provide("solution.world_geometries");
solution.world_geometries = ...

где world_geometries - имя файла с подложкой без расширения js.

Сами новые подложки естественно должны лежать в каталоге js в userdata.

Создание подложек описывается в документе "Руководство по подготовке карт для Showcase" (файл mapsManual.zip), который входит в дистрибутив Showcase.

Этап II. Файл подключения подложки к Showcase

Файл подключения подложки к Showcase содержит настройки, с которыми будет отображаться на информационной панели некая подложка конкретной карты.

Пример такого файла можно посмотреть в архиве testUnderlayerSettings.zip, входящем в дистрибутив.

Для новой подложки приложенный файл можно просто скопировать в папку js в userdata и переименовать. Обратите внимание, что файл подключения - это JavaScript и для того, чтобы Tomcat его "подцепил", необходимо перезапустить сервер!

При этом нужно обратить внимание на следующие строчки:

dojo.provide("solution.${proxi_filename}"); 
и
solution.${proxi_filename}.make = ...

data.geometries = ${namespase}.${map_filemane};

где ${namespase} - это пространство имен подложки - courseApp.data.geo или solution.

В данном файле также можно выбрать движок для отрисовки карты:

  • Наш собственный движок (djeo),
  • Yandex Maps (ymaps),
  • Google Maps (gmaps),
  • Google Earth (ge).
data.engine = "ymaps"

Обращаем ваше внимание на 3 особенности:

  1. На всех подложках кроме djeo, нельзя задавать точки векторно. Для не наших подложек нужно использовать растровые иконки.
  2. На всех подложках кроме djeo нельзя импортировать карту в виде картинки.
  3. Для работы подложек Яндекса и Google Earth нужно указать правильный ключ API. Он задается в файлах geomap.key.${host}.properties, где ${host} – это ip или имя сервера. Эти файлы лежат в корневом каталоге userdata.

В тестовой userdata лежат два файла: localhost - для локального компьютера, и ci - для компьютера ci, выполняющего автоматизированное построение новых версий Showcase. Каждый файл должен содержать 2 ключа - для Яндекса и для Google. В случае отсутствия файла с именем хоста будут использованы данные localhost. Ключ для Яндекса можно получить здесь, ключ для Google Earth - здесь

В остальном данный файл редактировать не рекомендуется. Тем не менее файле подключения подложки можно настроить ряд глобальных настроек карты. В частности, можно настроить следующие строки:

	new djeo.control.Navigation(map);
	new djeo.control.Highlight(map);
	new djeo.control.Tooltip(map);
        if (legendNode) legend = new djeo.widget.Legend({map: map}, legendNode);

Эти строки включают, соответственно:

  1. зум и навигацию мышью на карте,
  2. подсветку объектов на карте,
  3. подсказки на карте,
  4. отображение легенды соответственно.

Также в этом файле можно задать стиль по умолчанию в переменной mapStyle, который будет применен если не задан ни один стиль в хранимой процедуре.

Этап III. Связывание подложки с процедурой

Для связывания начиная с версии 1.9.4 нужно просто добавить в шаблон карты в хранимой процедуре (тэг <template>) следующую строчку:

registerSolutionMap: ${proxi_filename},

где ${proxi_filename} - это имя файла подключения.

Интерфейс JS функции отрисовки карты

Данный раздел содержит техническую информацию о работе JS-функции при отрисовке карты!

В JS-функцию отрисовки карты приходит 4 параметра: div для карты, div для легенды, optionSet1 и optionSet2.

Параметр optionSet1 генерируется динамически на основе данных из БД, optionSet2 содержит заранее сохраненные настройки - шаблон (template).

На карте можно потенициально отображать следующие типы геометрических элементов: Point, LineString, Polygon, MultiPoint, MultyLineString, MultiPolygon На данный момент Showcase способен передавать данные из БД для следующих типов: Point и Polygon.

Параметр optionsSet1 содержит атрибуты, как указано в примере:

{
    width: 400, // вынуждены ширину задавать здесь, а не в стиле для div
    height: 400, // вынуждены высоту задавать здесь, а не в стиле для div
layers: [
  {
    "id": "id1", 
    "name": "Name1", 
    "type": "POINT", 
    "projection": "EPSG:4326",    
    "indicators": [],
    "features": [
       {
        "id": "feature2",
	"name": "name",
        "tooltip": "xxx",
	"style": "", // цвет, стиль точки или что-то еще - аналог inline стиля CSS
        "styleClass": "", // класс стиля
	"geometryId": "RU-AL",
        "pointCoords": [lon, lat],            
        // "polygonCoords" может отсутствовать тогда надо искать описание геометрии во внешнем файле
        "polygonCoords": [ [[lon1, lat1], ...координаты внешней линии], [координаты внутренней линии если есть]],
        "multiPolygonCoords": [ координаты первого полигона[ [[lon1, lat1], ...координаты внешней линии],
           [координаты внутренней линии если есть]] []],
        "lineStringCoords": null,
        "multiLineStringCoords": null,
        "attrs": { "mainInd": 45.3, ...}
       }
    ]
  },
  {
    "id": "id1", 
    "name": "Name2", 
    "type": "POLYGON",  
    "indicators":  
            {
            "isMain": true,
            "style": "#2AAA2E",
            "tooltip": null,
            "id": "mainInd",
            "name": "Производство (тыс. тонн)"
          }, ...
  }
  
]
}

Задание карты через XML-датасеты

Для создания карты необходимо задать все те же 5 датасетов в виде xml в параметре @geomapsettings:

<tables>

  <layers>
 </layers>

  <points>
  </points>

  <polygons> 
  </polygons>

  <indicators>
  </indicators>

  <indicatorValues>
  </indicatorValues>

</tables>

Внимание! Необходимо соблюдать порядок датасетов (совпадающий с порядком sql-датасетов) и их названия (layers, points и т.д.). Тег <rec> является обязательным. Он служит для обозначения записи в датасете.

Пример процедуры:

ALTER PROCEDURE [dbo].[geomap_func2_xmlds]
	@main_context varchar(512)='',
	@add_context varchar(512)='',
	@filterinfo xml='',
	@session_context xml ='',
	@element_id varchar(512) ='',
	@geomapsettings xml='' output
AS
BEGIN
SET NOCOUNT ON;

Declare @settings_str as varchar(max)
set @settings_str=
'<geomapsettings>
		<labels>
			<header>
				<h2>Карта с раскрашенными по значению показателя регионами</h2>
			</header>
	
		</labels>
		<properties legend="top" />
		<template> 
	{
	   registerModules: [["solution", "../../solutions/default/js"]],
	   managerModule: "solution.test",	
       style: [
	{
		fid: "l2",
		stroke: "black",
		strokeWidth: 1,
		styleFunction: {
			getStyle: "djeo.util.numeric.getStyle",
			options: {
				numClasses: 7,
				colorSchemeName: "Reds",
				attr: "mainInd",
				breaks: "djeo.util.jenks.getBreaks",
				calculateStyle: "djeo.util.colorbrewer.calculateStyle"
			}
		},
		legend: "djeo._getBreaksAreaLegend",
		name: "имя"
	},
{
       point: {
			strokeWidth: 2,
			fill: "blue",
			shape: "circle"
       }
}
]
      
}	
		</template>              	



<tables>

  <layers>
		<rec>
			<ID>l1</ID>
			<Name>Города</Name>
			<ObjectType>POINT</ObjectType>
			<HintFormat>%LayerName - %ObjectName (%ObjectID) (%Lat - %Lon)</HintFormat>
		</rec>
		<rec>
			<ID>l2</ID>
			<Name>Регионы</Name>
			<ObjectType>POLYGON</ObjectType>
			<HintFormat>%LayerName - %ObjectName (%ObjectID)</HintFormat>
		</rec>
  </layers>

  <points>
		<rec>
			<ID>1107</ID>
			<Name>Славгород</Name>
			<LayerID>l1</LayerID>
			<Lat>5.2990311e+001</Lat>
			<Lon>7.8648598e+001</Lon>
			<properties>
				<event name="single_click">
					<action>
						<main_context>current</main_context>
							<datapanel type="current" tab="current">
								<element id="06">
<add_context>Славгород</add_context>                                                                                             
								</element> 
							</datapanel>
							</action>
						</event>
			</properties>
		</rec>
		
        ...

  </points>
 <polygons> 
    <rec>
      <ID>1</ID>
      <Name>Республика Адыгея</Name>
      <code>RU-AD</code>
      <LayerID>l2</LayerID>
      <Tooltip>Республика Адыгея - производство</Tooltip>
      <StyleClass>RU-AD</StyleClass>
      <properties>
						    <event name="single_click">
                            <action>
                                <main_context>current</main_context>
                                <datapanel type="current" tab="current">
                                    <element id="06">
					<add_context>Республика Адыгея</add_context>                                                                                             
                                    </element> 
                                    
                                </datapanel>
                            </action>
					        </event>
		</properties>
    </rec>
		
        ...

  </polygons>
  <indicators>
		<rec>
			<ID>ind1</ID>
			<Name>Производство (тыс. тонн)</Name>
			<LayerID>l2</LayerID>
			<IsMain>1</IsMain>
			<Color>#2AAA2E</Color>
		</rec>
  </indicators>

  <indicatorValues>
    <rec>
      <IndicatorID>ind1</IndicatorID>
      <ObjectID>1</ObjectID>
      <VALUE>3.967000000000000e+002</VALUE>
    </rec>
		
        ...

  </indicatorValues>
 

</tables>		

	
</geomapsettings>' 
set	
@geomapsettings=CAST(@settings_str as xml)
END