[[TOC]]
= S3 API Guide =

This page links to all wiki pages describing how to make use of the S3 framework when developing Eden modules or other applications connecting to Eden via [wiki:S3/S3REST web services].

''External links:''

  * [http://pub.nursix.org/eden/s3 S3 API Documentation (Epydocs)]

  * [http://en.flossmanuals.net/sahana-eden Sahana Eden Essential Guide] (book):
    * [http://en.flossmanuals.net/sahana-eden/web-sevices Web Services]
    * [http://en.flossmanuals.net/sahana-eden/s3xml S3XML]
    * [http://en.flossmanuals.net/sahana-eden/mapping-gis Mapping & GIS]

== Authentication, Authorization, Accounting ==

 - [wiki:S3/S3AAA Authentication, Authorization, Accounting]
   - [wiki:S3/S3AAA/OrgAuth OrgAuth]
   - [wiki:S3/S3AAA/RecordApproval Record Approval]

== Security / Privacy ==
 - [wiki:S3/S3Anonymize Anonymize Tool]
 - [wiki:S3/ConsentTracking Consent Tracking]


== Logging ==

 - [wiki:S3/S3Log S3Log]

== RESTful API ==

=== API ===
 - [wiki:S3/S3REST/Methods Supported Methods]
 - [wiki:S3/S3REST/URLFormat URL Format]

 - [wiki:S3/XMLForms Generating XML Forms (XForms)]

=== Framework ===
 - [wiki:S3/S3REST/s3_rest_controller Implementing RESTful Controllers] (s3_rest_controller)
 - [wiki:S3/S3Method Extending the RESTful API by implementing S3Method]

=== Core Classes ===
 - [wiki:S3/S3Request S3Request]
 - [wiki:S3/S3Resource S3Resource]
 - [wiki:S3/S3ResourceFilter S3ResourceFilter]
 - [wiki:S3/FieldSelectors Field Selectors]

== Configuration ==
=== Deployment Settings ===
[wiki:DeveloperGuidelines/DeploymentSettings deployment_settings]

=== Configure ===
A lot of configuration options are stored as key/value pairs against the tablename using:
{{{#!python
s3db.configure(tablename, key=value)
}}}

These values can be read using:
{{{#!python
value = s3db.get_config(tablename, "key")
}}}

These settings may have defaults defined within the core models ({{{modules/s3db/*.py}}}) or default controllers ({{{controllers/*.py}}}) - possibly conditional based on the values of [wiki:DeveloperGuidelines/DeploymentSettings deployment_settings] or which method is being invoked.

Settings can also be customised within the {{{customise_*_resource()}}} or {{{customise_*_controller()}}} functions within a [wiki:DeveloperGuidelines/Templates Template].

The value can be a simple string, a complex object or sometimes a generator function.

Example settings include:
* {{{list_fields}}}
 - which fields get displayed as columns in datatables (& currently which are read from the database for use in datalist renderers, but this should change soon as we migrate to {{{S3DataListLayout()}}})
* {{{filter_widgets}}}
 - which [wiki:S3/FilterForms S3FilterWidgets] are displayed on datatable, datalist and [wiki:S3/S3Summary Summary] views.
* {{{report_options}}}
 - the axes & other options to configure [wiki:S3/S3Report S3Report] for both standalone {{{/report}}} pages & widgets e.g. in [wiki:S3/S3Summary Summary] views.
* {{{orderby}}}
 - The default sort order for datatables & datalists (datalists can specify {{{list_orderby}}} if they wish this to be different from that used by datables)

NB If the value is a complex object, then customising this doesn't require re-storing the value as the object is edited in-place.

==== See Also ====
* [wiki:S3/S3Model#TableConfigurationSettings S3Model#TableConfigurationSettings]
* [wiki:S3/TableConfigurationSettings]
=== Context ===
* [wiki:S3/Context Context]

== Database ==

=== Models ===
  - [wiki:DeveloperGuidelines/PersonEntityModel Person Entity Model]
  - [wiki:S3/S3Model Data Model Extensions]
    - [wiki:S3/S3Model/ComponentResources Components and Link-tables]
    - [wiki:S3/S3Model/SuperEntities Super-Entities]

  - [wiki:S3/S3ReusableField S3ReusableField]

=== Hierarchical Types (Taxonomies) ===

  - [wiki:S3/S3Hierarchy Hierarchy Toolkit]

=== Template-defined Models (Custom Tables) ===

  - [wiki:S3/CustomTables Custom Tables]

=== User-defined Models (Dynamic Tables) ===

  - [wiki:S3/DynamicTables Dynamic Tables]

== !Export/Import ==
* [wiki:S3/S3XML S3XML and S3JSON Formats]
 * [wiki:S3/S3XML/Transformation Using XSLT Transformation for Data Export/Import]
* [wiki:BluePrint/Importer/Excel XLS Format]
* [wiki:S3/DataImportCLI Importing Data from the web2py CLI]

== Subscriptions and Notifications ==
  - [wiki:S3/Notifications S3 Notifications]

== GUI ==

=== Menus and Navigation ===
  - [wiki:S3/S3Navigation S3Navigation]

=== Pages ===
  - [wiki:S3/S3Profile Profile Pages]
  - [wiki:S3/S3Summary Summary Pages]
  - [wiki:S3/S3Dashboard Dashboards]
=== Tables and Lists ===
  - [wiki:S3/DataTable S3DataTable]
  - [wiki:S3/DataList S3DataList]
  - [wiki:S3/PivotTable S3PivotTable]

=== Reports ===
  - [wiki:S3/S3Report S3Report Pivot Table Reports]

=== Filter Forms ===
  - [wiki:S3/FilterForms S3 FilterForms]
  - [wiki:S3/DefaultFilters Default Filters]

=== CRUD Forms ===
  - [wiki:S3/S3SQLForm Custom Forms for S3CRUD]

=== Form Widgets ===
  - [wiki:S3/S3GroupedOptionsWidget S3GroupedOptionsWidget]
  - [wiki:S3/S3HierarchyWidget S3HierarchyWidget]

== GIS/Mapping ==

=== Overview ===
  - [wiki:DeveloperGuidelines/GIS DeveloperGuidelines GIS]

=== Location Tracking ===
   - [wiki:S3/S3Tracking S3Tracking Generic Location Tracking System]

== Related [wiki:BluePrints] ==
   - [wiki:BluePrintRecordMerger Record Merger]
   - [wiki:BluePrintSearch Search Methods]

----
DeveloperGuidelines