Difference between revisions of "Developer Manual"

From ARK
Jump to: navigation, search
(Standards and Guidance)
 
(28 intermediate revisions by 3 users not shown)
Line 1: Line 1:
The developer manual is aimed at people who will be contributing to the project and to a certain extent to those who intend to hack ARk to use it for their own ends. As a general rule, if you find yourself doing extensive hacking, please let us know as we would be happy to consider adding new code to the project.
+
The developer manual is aimed at people who will be contributing to the project and to a certain extent to those who intend to hack ARK to use it for their own ends. As a general rule, if you find yourself doing extensive hacking, please let us know as we would be happy to consider adding new code to the project.
  
 
If you don't know why you are reading this documentation, you are probably looking in the wrong part of the manual. For information on installation and administration see the [[Administrator Manual| administrator]] section of the manual.
 
If you don't know why you are reading this documentation, you are probably looking in the wrong part of the manual. For information on installation and administration see the [[Administrator Manual| administrator]] section of the manual.
  
Work to create developer documentation including migration of old documentation (Ticket #122) is ongoing (as of 11th Feb 2009) but in the meantime please contact a member of the [http://ark.lparchaeology.com/contact ARK Development Team] if you can't find what you are looking for within these pages.
+
Work to create developer documentation including migration of old documentation (Ticket #122) is ongoing (as of 21st Oct 2016) but in the meantime please contact a member of the [http://ark.lparchaeology.com/contact ARK Development Team] if you can't find what you are looking for within these pages.
  
==Background Reading==
+
===Background Reading===
  
The [[ARK model]] an incomplete guide to the overall structure of ARK, its file structures etc.
+
====[[ARK model]]====
 +
An incomplete guide to the overall structure of ARK, its file structures etc.
  
The [[ARK Data Storage]] model
+
====[[ARK Data Storage]]====
 +
An overview of the ARK data storage model
  
An overview of [[Filters]] and how they work (theoretical)  
+
====[[Filters]]====
 +
An overview of filters and how they work (theoretical)
  
 +
===Standards and Guidance===
  
==Standards and Guidance==
+
Coding standards are simple and follow the PEAR system rigidly without exception. See the page blow for further detail. Some further guidance is given below to try to help you build new code in a way that fits into the overall ARK style. This material is incomplete at this stage.
 +
 
 +
====[[Coding Standards]]====
 +
An overview of the coding standards with a link to PEAR.
 +
 
 +
====[[Adding a New Page]]====
 +
How to add a new page to the system
 +
 
 +
====[[Data Entry Pages]]====
 +
How the data entry pages fit together. Possibly needs to be re-written as something more generic
  
Coding standards are simple and follow the PEAR system rigidly without exception. See the page blow for further detail. Some further guidance is given below to try to help you build new code in a way that fits into the overall ARK style. This material is incomplete at this stage.
+
====[[Page Header Block]]====
 +
example code for a page header block. Possibly needs to be made into a more generic code snippets page
 +
 
 +
====[[Developing Subforms]]====
 +
A brief guide to developing new subforms
 +
 
 +
====[[Accessing User Information]]====
 +
How to get access to the logged in user's information which is held in the SESSION
 +
 
 +
====[[ARK log]]====
 +
An overview of the log system with detailed notes (note that this system is currently not fully working)
 +
 
 +
====[[Markup and Aliases]]====
 +
An overview and guide
 +
 
 +
====[[Error and Message Handling]]====
 +
An overview and guide
 +
 
 +
====[[Configuration Settings for Developers]]====
 +
An overview for developers of the config system
 +
 
 +
===Developer Documentation===
 +
 
 +
The code is documented in detail within the header blocks for each file and the documentation blocks for each function. This doucmentation is in the process of being categorised and grouped for easier reading, but can be consulted at:
 +
 
 +
====[[http://ark.lparchaeology.com/ark_phpdoc/li_ark.html PhpDocumenter Output]]====
 +
Detailed reference material for every function and script in the system - NB this is for ARK v0.7, and has not yet been updated for the latest release(s).
 +
 
 +
====[[http://www.phpdoc.org/ PhpDocumenter]]====
 +
Some info on the software used to create the documentation from the header blocks
 +
 
 +
[[Category:Developer]]
 +
 
 +
===API Documentation===
 +
 
 +
As of v1.1 it is possible to access ARK using an API via a URL - which currently responds with a JSON object.
 +
 
 +
The following methods can be used:
  
[[Coding Standards]] an overview with links.
+
[[describeARK]] - this provides some simple metadata about the ARK instance
  
===ARK 'Pages'===
+
[[describeItems]] - this provides a list of all the types of modules available
  
[[Data Entry Pages]]
+
[[describeFrags]] - this provides a list of all the different types of data available within the ARK instance (it lists the different 'types' of dataclass available
  
[[Adding a New Page]]
+
[[describeFilters]] - this provides a list of all available filters
  
[[Page Header Block]] example.
+
[[describeSubforms]] - this provides a list of available subforms (for transclusion)
  
[[Developing Subforms]] a brief guide
+
[[describeFields]] - this provides a list of available fields
  
[[Accessing User Information]] which is in the SESSION
+
[[getItems]] - this returns an array of items of a specified module
  
[[ARK log]] an overview with detailed notes (note that this system is currently not fully working)
+
[[getFrags]] - this returns an array of data frags attached to a specified item
  
[[Markup and Aliases]] an overview and guide
+
[[getFilter]] - this returns the result of a saved filter or a free-text search
  
[[Error and Message Handling]] and overview and guide
+
[[getFields]] - this returns an array of the fields attached to an item with their values
  
[[Configuration Settings for Developers]] an overview for developers of the config system
+
[[getConcepts]] - this is a wrapper page which retrieves the definition of a particular concept
  
==API Documentation==
+
[[transcludeFilter]] - this returns a fully rendered HTML representation of a filter result
  
The code is documented in detail within the header blocks for each file and the documentation blocks for each function. This doucmentation is in the process of being categorised and grouped for easier reading, but can be consulted at:
+
[[transcludeSubform]] - this returns a fully rendered HTML representation of a subform
  
[[http://ark.lparchaeology.com/ark_phpdoc/li_ark.html]]
+
[[putField]] - this is for putting values to an ARK. Use this for adding, editing or deleting fields
  
[[API Documentation]]
+
[[XMLParser]] - this is mainly used internally by the spatial elements of ARK to retrieve and present GML data
  
  
 
[[Category:Developer]]
 
[[Category:Developer]]

Latest revision as of 16:40, 21 October 2016

The developer manual is aimed at people who will be contributing to the project and to a certain extent to those who intend to hack ARK to use it for their own ends. As a general rule, if you find yourself doing extensive hacking, please let us know as we would be happy to consider adding new code to the project.

If you don't know why you are reading this documentation, you are probably looking in the wrong part of the manual. For information on installation and administration see the administrator section of the manual.

Work to create developer documentation including migration of old documentation (Ticket #122) is ongoing (as of 21st Oct 2016) but in the meantime please contact a member of the ARK Development Team if you can't find what you are looking for within these pages.

Background Reading

ARK model

An incomplete guide to the overall structure of ARK, its file structures etc.

ARK Data Storage

An overview of the ARK data storage model

Filters

An overview of filters and how they work (theoretical)

Standards and Guidance

Coding standards are simple and follow the PEAR system rigidly without exception. See the page blow for further detail. Some further guidance is given below to try to help you build new code in a way that fits into the overall ARK style. This material is incomplete at this stage.

Coding Standards

An overview of the coding standards with a link to PEAR.

Adding a New Page

How to add a new page to the system

Data Entry Pages

How the data entry pages fit together. Possibly needs to be re-written as something more generic

Page Header Block

example code for a page header block. Possibly needs to be made into a more generic code snippets page

Developing Subforms

A brief guide to developing new subforms

Accessing User Information

How to get access to the logged in user's information which is held in the SESSION

ARK log

An overview of the log system with detailed notes (note that this system is currently not fully working)

Markup and Aliases

An overview and guide

Error and Message Handling

An overview and guide

Configuration Settings for Developers

An overview for developers of the config system

Developer Documentation

The code is documented in detail within the header blocks for each file and the documentation blocks for each function. This doucmentation is in the process of being categorised and grouped for easier reading, but can be consulted at:

[PhpDocumenter Output]

Detailed reference material for every function and script in the system - NB this is for ARK v0.7, and has not yet been updated for the latest release(s).

[PhpDocumenter]

Some info on the software used to create the documentation from the header blocks

API Documentation

As of v1.1 it is possible to access ARK using an API via a URL - which currently responds with a JSON object.

The following methods can be used:

describeARK - this provides some simple metadata about the ARK instance

describeItems - this provides a list of all the types of modules available

describeFrags - this provides a list of all the different types of data available within the ARK instance (it lists the different 'types' of dataclass available

describeFilters - this provides a list of all available filters

describeSubforms - this provides a list of available subforms (for transclusion)

describeFields - this provides a list of available fields

getItems - this returns an array of items of a specified module

getFrags - this returns an array of data frags attached to a specified item

getFilter - this returns the result of a saved filter or a free-text search

getFields - this returns an array of the fields attached to an item with their values

getConcepts - this is a wrapper page which retrieves the definition of a particular concept

transcludeFilter - this returns a fully rendered HTML representation of a filter result

transcludeSubform - this returns a fully rendered HTML representation of a subform

putField - this is for putting values to an ARK. Use this for adding, editing or deleting fields

XMLParser - this is mainly used internally by the spatial elements of ARK to retrieve and present GML data