Views are recordings of CartoWeb maps states at a given moment. One may see them as a kind of bookmarks: while browsing maps in CartoWeb interface, users can save the current state (map extent, selected layers, queries, annotations, etc.) under a label of their choice. It is then possible to access later those saved states.
Views are shared among users and are - in the current version - available to every user. Access to views edition functionalities (creation, modification, deletion) can be restricted to some categories of users. The default configuration only allows "admin"-roled users to perform view edition.
The views device consists of two parts:
- a main controlling system that handles views detection, loading, recording and storage.
- a "views" plugin that provides a graphical interface for performing views loading and edition. This plugin is not mandatory to have views working but greatly enhances the device usability.
No configuration is required for that plugin. However it still needs to be activated using the client_conf/client.ini loadPlugins parameter. For instance:
loadPlugins = auth, exportPdf, views
Main views controller configuration is done in the client_conf/client.ini file. The dedicated parameters are:
-
viewOn(boolean: 'true'|'false'): activates/deactivates the main view controller. Views plugin will not work if the controller is off. -
viewStorage(string: 'file'|'db'): tells what storage container must be used: file or database. -
viewablePlugins(comma-separated list of strings): list of plugins that must have their data saved in views. Note that "viewable" plugins must implement the Sessionable interface. If you wish to save data from extended plugins, you must add the extended plugin to the list, not the standard one (eg.myLocationinstead oflocation). -
viewMetas(comma-separated list of strings): list of metadata fields that must be saved in addition to the viewable plugins data (for instance author, email, description...). Common metadata fields such as "viewTitle" are anyway saved. Note that metadata fields must have homonym form fields inplugins/views/templates/views.tplto be taken into account. -
viewDsn(string): DSN (Data Source Name), gives the database connection parameters. Only used in database storage mode. Any DSN format supported by PEAR::DB can be used. See PEAR::DB manual for more info about DSNs at http://pear.php.net/manual/en/package.database.db.intro-dsn.php. Note that you can call any database server type as long as it is supported by PEAR::DB and that your PHP distribution has the matching extension enabled. -
viewAuth(comma-separated list of strings): list of roles allowed to perform views edition actions. Given roles must matchclient_conf/auth.inidefined ones. See also Chapter 15, Security Configuration. -
viewSavedRequest(comma-separated list of strings): list of REQUEST variables (GET, POST, COOKIE) that must be preserved when loading a view. Some are already built-in listed such astool,js_folder_idx,project,collapse_keymapand views related parameters. Adding other CartoWeb reserved REQUEST variables names to the list may prevent the view system from working correctly. -
viewLogErrors(boolean): if true, outdated views loadings will be logged inlog/viewErrors.log. -
viewUpgradeOutdated(boolean): if true, CartoWeb will try to upgrade outdated views on the fly. Else view outdated parts will be discarded and current plugin session data will be used instead. -
viewHooksClassName(string): name of the PHP class used to customize some views processing. See Section 11.3, “Customizing Views Processing Using Project Hooks” for details on how to write customized views hooks.
For instance:
; Views management viewOn = true viewStorage = db viewablePlugins = location, layers, query, outline viewMetas = author viewDsn = pgsql://www-data@localhost/cw3 viewAuth = admin, viewSavedRequest = personalVar1, personalVar2 viewLogErrors = true viewUpgradeOutdated = true viewHooksClassName = FoobarViewHooks
Should you decide to use a database storage, you would need first to create an appropriate table called views. Here is an example of SQL statements for PostgreSQL:
CREATE TABLE views (
views_id serial NOT NULL PRIMARY KEY,
views_ts timestamp without time zone,
viewtitle character varying(50),
author character varying(50),
sessiondata text,
viewshow boolean,
weight integer
);
Tip
Field "views_ts" is just present in table "views" but not visible in the graphical interface of the "views" plugin. This value is usefull to know the time of the creation/modification of a view (only available with option "viewStorage = db").
Any defined view may be loaded by any users. Loading a view may be achieved selecting it among a dropdown views list. Two dropdown lists are available:
- a public one that only displays views labels that have been marked as "visible" by their creators.
- a selector within the Views plugin edition interface. This view selector contains all views including the ones that have not been marked as "visible" by their creators. Note that this selector provides a view ID (integer) input as well.
Views may also be loaded using GET parameters in URLs that look like:
http://<cartoweb/client/base/url>?handleView=1&viewLoad=1&viewLoadId=<viewId>
or simply
http://<cartoweb/client/base/url>?view=<viewId>
Tip
Views not marked as "visible" may anyway be loaded by anyone. "Visible" only means that their labels appear in the public view dropdown selector whereas "invisible" ones don't.
Views edition is restricted to users whom roles match at least one of those specified in the client_conf/client.ini viewAuth parameter (see Section 13.2.2, “Main Views Controller”).
Views editors can create, update or delete views.
To save the current map state as a view, simply fill in the form fields with matching metadata. To make the view "visible", check the "Show view" option. Finally push the "save" button.
You may also save a new view using an existing view. To do so, load the desired view as described in Section 13.3.1, “Loading Views”, modify it as explained in Section 13.3.2.3, “Updating a View” and push the "Save as new view" button.
Load the view you want to delete as shown above and push the "Delete" button. A JavaScript confirmation pops before irreversible deletion.
To modify a view map properties (selected layers, annotations, map extent, etc.) as well as its metadata (title, "visibility", etc.), load it as seen above.
If your changes only concern metadata, simply update the dedicated form fields and push the "Update" button.
To update the view map properties, check the "Memorize form" option. Metadata and selected view ID are then memorized while you perform your changes (pans, zooms, annotations, layers selections, etc.). Eventually push the "Update" button.
