= !BluePrint: Framework for Dashboards =
[[TOC]]

== Introduction ==

Dashboards (in this BluePrint) are containers to render multiple data resources and/or user activities on a single page, allowing synopsis and cross-analysis of data resources, as well as consolidation of user goals.

== Stakeholders ==

- Users
- Deployers (Content Managers)
- Service Providers (Template Developers)
- Plugin Developers
- Core Developers
== User Stories ==

=== End-Users ===
 - Deployers want to adapt the homepage to the context of the deployment and the current situation (global dashboard)
 - Deployers want to extend dashboards with additional/custom layouts or widgets provided as plugins
 - Organisation managers want to provide an overview of their current activities and status of their resources (org-specific dashboard)
 - Site managers want to provide an overview of the current status of their facilities and resources (site-specific dashboard)
 - Individual users want to adapt a personal landing page to their specific user role/tasks (personal dashboard)
 - Individual users want to share their dashboard configuration with other members of their team
 - Users want to re-use a dashboard configuration with multiple (e.g. offline) instances

=== Implementers ===
 - Developers want to implement pages providing overview of status/tasks/resources in a certain workflow (workflow dashboard)
 - Developers want to implement pages for synopsis and cross-analysis of multiple data resources (analysis dashboard)
 - Developers want to provide additional layouts or widgets for dashboards as plugins

=== Core Developers ===
 - Developers want to extend or add page layouts for dashboards
 - Developers want to extend or add widget classes
== Requirements ==
=== Functional ===

 1. Dashboards support an extensible library of page '''layouts'''
 2. Dashboards support an extensible library of '''widgets''' (=objects to render resources/activities)
 3. Dashboards provide a structure for cross-filtering of widgets (='''common context''')
 4. Dashboards (including widgets) are '''configurable at run time''' (through the web GUI), without requiring any server-side intervention
 5. Dashboard configurations '''can be shared''':
    - with other users
    - with other Sahana instances

=== Non-functional ===

 * easy to use (e.g. drag'n'drop to modify widget placement)
 * well-documented (both developers and users)
 * full coverage with automated (unit-)tests
 * fast and scalable

 * (should) support multiple widgets of the same type
 * (could) replace S3Profile
=== Interoperability ===

'''MUST'''
 - work consistently with all supported browsers, including normal browser actions (page reload, bookmarking)

'''SHOULD'''
 - maintain backwards-compatibility with existing user configurations
 - provide an option to export and import user configurations

'''COULD'''
 - maintain backwards-compatibility with 3rd-party widgets
 - provide an option to automatically synchronize configurations with other instances (e.g. offline instances)

'''WILL NOT''' (=things that are possible, but don't need framework level implementation)
 - make sure dashboards can be embedded into other pages
 - make sure dashboards work on mobile
== Framework Architecture ==

Overview of the tentative framework architecture:

[[Image(dashboard_architecture.png)]]
== Current Implementation ==

- [wiki:S3/S3Dashboard S3Dashboard] (modules/s3/s3dashboard.py)

== Future Extensions ==

 * default configurations per entity (i.e. per organisation, site or team)
 * default configurations per user role (possibly combined with per-entity defaults)
 * ability for the user to add new dashboards as menu items
== References ==
''tbw''

----
BluePrint