.. _create-your-own-geoprisma-project-label:
===================================
Create your own GeoPrisma project
===================================
This article is a complete *step-by-step* procedure to be able to create a new
and complete *web-mapping* project using GeoPrisma as your main application.
With these instructions, you'll be able to start from nothing at all and end
with all the knowledge, tips and tricks needed to be able to start your project.
If your intention is to create and add a new sample to the GeoPrisma samples,
read this topic instead :
:ref:`how-to-make-a-new-sample-label`
.
Basic GeoPrisma knowledge
-----------------------------
First, be sure to have read and understood the :ref:`concepts-label` of
GeoPrima.
Services, basic knowledge
--------------------------
It is strongly recommended to have some basic knowledge in the following
topics before moving on :
* Setting up a WMS server (any, at least one)
* With MapServer : http://mapserver.org/ogc/wms_server.html
* With GeoServer : http://docs.geoserver.org/2.0.x/en/user/services/wms/index.html
* Setting up a FeatureServer server :
* http://featureserver.org/doc/Readme.html#configuration
* Setting up a TileCache server :
* http://tilecache.org/docs/README#configuration
Services, DataStores and Resources list
----------------------------------------
This portion of the article is about the configuration and use of any Service
needed in your GeoPrisma installation. Before moving on, you should have your
Services all set and ready. When they are, prepare your Resources.
Here's two ways to help you think about *how to prepare your Resources* :
#. You have plenty of data and don't know what to do with it (no Service yet) :
* Make a list of the Resources you want to use in your application.
* For each Resource, define what widget will be available
* For each Resource, define all the ServiceType used by the widgets it will
use
* Each ServiceType will consist of a DataStore and a Service you need to
prepare for the data.
Example with [widget](ServiceType) :
You have a *city* shapefile you want to use in GeoPrisma. You want users
to be able to view the cities in a [map](WMS), use some query tool
[query](WMS) and some will have the rights to edit them
[edition](featureserver). So, the data need to be served by a WMS server,
such as MapServer and by FeatureServer. You'll need both services
installed, serving the data accordingly to your need. Also, since you'll
want the users to *upload* changes to the data, you should plan to import
your data in a *editable* format, such as in a *PostGIS* database.
#. You have working and ready web mapping services you want to use in
GeoPrisma :
* Make a list of the Services you have avalaible.
* For each Service, make a list of the Resources availables. If the same
data is served by multiple Services, only create **one** Resource with
many DataStores.
Restrict the access to the Services
------------------------------------
**IMPORTANT**
GeoPrisma becomes responsible of the access to these Resources,
so you **must** make all the Services they use unavailable outside the GeoPrisma
Proxy (else, what's the point, right ?)
Download
-------------------------
:ref:`download-label`
GeoPrisma from the SVN repository (recommended).
Fill the requirements
----------------------
Check that your have every :ref:`prerequistes-label` filled. If you use apache,
you might want to automatically load the required modules as *extension* in
your *config.ini* file (example, for linux) :
.. code-block:: php
extension=php_curl.so
extension=php_gettext.so
extension=php_xsl.so
extension=php_pgsql.so
Create your 'Project' directory
--------------------------------
Here's a proposed directory structure to use inside your project directory. It
will be used in this *how to* :
* config
* htdocs
* xslt
* js
* css
* img
Make your *htdocs* directory visible from the web.
Choose an existing sample to build from
----------------------------------------
The easiest way to start your project is to look among the existing samples
and choose one that fits your needs. If it's your first time playing around
with GeoPrisma, think small and easy !
Simply copy the files from a single example and place them in your project
directory. If you used the above structure, copy the files to the locations :
1. common.php --> config
2. proxy.php --> htdocs
3. template.xslt --> htdocs/xslt
4. index.php --> htdocs
5. config.xml --> config
6. sample.php (you don't need this file)
Finally, also copy this file (from the root *samples* directory).
7. config.php --> config
To know more about these files, see
:ref:`concepts-label`
.
Choose your drivers
--------------------
In the *core* configuration file of GeoPrisma, you'll have to specify which
driver to use for each of the following elements :
#. :ref:`acl-drivers-label`
#. :ref:`config-drivers-label`
You can either choose from existing drivers included in GeoPrisma or create and
your own. If you decide to do so, please fill a ticket with a patch in trac :
http://trac.osgeo.org/geoprisma/
If it's your first time playing around with GeoPrisma, you should start by
using the :ref:`noacl-driver-label` as your ACL driver. It'll be easier to
play around with less stuff to worry about. We'll cover that later.
The choice of the config driver is up to you, but in this *how to* we'll pick
the
:ref:`xmlconfig-driver-label`
since it's easy, quick to use and all the samples currently use this driver.
'Core' config
--------------
All the *.php* files are used to configure the *core* of GeoPrisma. Edit them
to fit to your chosen driver settings.
You might need to change some path variables, like :
.. code-block:: php
$g_strGeoprisma = "$g_strCurrentDir/..";
to :
.. code-block:: php
$g_strGeoprisma = "/path/to/YourGeoPrismaRootDir";
Set your ACL and CONFIG driver. Set your default LOCALE language.
Config file (config.xml)
-------------------------
Edit your :ref:`xmlconfig-driver-label` file (config.xml).
Remove the junk you don't need. Add your Services, DataStores, Resources and
Widgets defined in your list. See the Widget API documentation and samples to
know more about the widgets and their possible options.
.. _create-your-own-geoprisma-project-template-label:
Template (XSLT)
----------------
Edit your Template file
* Add any missing xmlns and remove useless ones :
.. code-block:: php
xmlns:map="http://geoprisma.org/map"
xmlns:geoexttoolbar="http://geoprisma.org/geoexttoolbar"
xmlns:shortcut="http://geoprisma.org/shortcut"
* Add any missing prefixes and remove useless ones :
.. code-block:: php
extension-element-prefixes="dyn map geoexttoolbar shortcut"
* Add any missing xslt widget files and remove useles ones :
.. code-block:: php
* Change the path to the widgets to fit your installation
.. code-block:: php
* Add the *drawWidget* functions of your widgets. See the Widget API
Documentation for concrete example of use of each widget and how to *draw*
them.
* Apply any more esthetic changes.
i18n
----------------
All your html pages should start with :
.. code-block:: php
To be able to use the existing internationalization support in current widgets
and adding them to your project, read about
:ref:`i18n-label`
Test your application
----------------------
Visit project *htdocs* directory form in a browser. GeoPrisma should
automatically generates the interface from the Resources and Widgets you
defined.
More widgets
----------------------
* Try to add more widgets
* Test their different options
* See them in action
.. seealso::
* :ref:`widgets-label` documentation
* `Official widget documentation (online) `_
* `Widget samples (online) `_ Click the *Samples* tag.
Ask the lists
--------------
Ask the *Mailing Lists* for help, questions and comments when needed.
See at http://www.geoprisma.org to join the lists.
Authentication and ACL
-----------------------
Now that you've played around the files and config a lot, you're ready to play
with the coolest thing in GeoPrisma : the ACL.
There's an existing example available showing all kind of different drivers
to use for the ACL. Simply play with it and look at the config files to learn
more :
* http://geoprisma.org/samples/borealis-authentification/
ACLManager
-----------
GeoPrisma has a basic tool to manage the ACL. See at :
* http://geoprisma.org/samples/acl2/index.php?lang=en_US
The example uses the
:ref:`borealis-acl-label`
driver, which is available to use.