koi documentation - developer
Introduction
koi is a simple yet powerful content management system.
The documentation is in a very early state. Some important parts may be missing and the order of things may not be logical.
User Definitions
- developer - a person (programmer) responsible for implementing koi into a web site.
- administrator - a person responsible for updating content on the web site.
- end-user - a person viewing the final web site.
Legal
koi is licensed under the GNU General Public License, version 2.
Most artwork comes from the Tango Desktop Project under the Creative Commons Attribution Share-Alike license.
Included Software
Server Requirements
koi should run on most modern UNIX operating systems with Apache2 and PHP5.
It may run on Windows too, but that remains untested.
Other versions than the ones mentioned below may work too.
Use the TEST.php script for an automated test of most requirements.
Unix Operating System
- Tested under Debian GNU/Linux 4.0
Apache httpd
- Tested under version 2.2.3.
- mod_rewrite enabled
- MultiViews disabled (possibly not a requirement)
PHP
- Tested under version 5.2.6.
- PCRE extension enabled
- MYSQL extension enabled
- DBA extension enabled
- magic_quotes_gpc turned off
- register_globals turned off
- safe_mode turned off
MySQL
- Tested under version 5.0.32.
- InnoDB enabled
ImageMagick
- Tested under version 6.2.4.
- Access to convert via system path
Installation
- Download
- Place files in public_html to the root of your web directory (relative hosting enviroment not yet supported)
- Make the directories dba/ and cache/ world-writable
- Create a MySQL database and import koi.sql
- Edit koi/conf.php with MySQL connection parameters
- If your system does not have db4 support, change DB_HANDLER in same file
- Also change the e-mail from-address for users forgetting their password
- You should now be able to access www.yourdomain.com/TEST.php
- Fix any missing requirements and delete TEST.php when done
Getting Started
- koi comes with a demo site called United Cherry Foundation, located at www.yourdomain.com/
- The administration interface is available at www.yourdomain.com/admin/
- Take a look at the templates located in user/templates
Administrator Requirements
koi administration (/admin) requires a modern browser due to heavy AJAX and DHTML usage.
koi has passed testing with these browsers:
- Firefox 2.0
- Microsoft Internet Explorer 7
- Safari 3.1
- Opera 9
koi has failed testing with these browsers:
- Microsoft Internet Explorer 6
- Opera 8
- Konqueror (problems with tiny_mce and swfaddress)
Media Gallery
The file extensions listed below are accepted for upload by the Media Gallery.
More extensions can be added by modifying action_files_upload() in koi_admin.php.
Image Files
- .jpg .jpeg
- .gif
- .png
- .bmp
- .tif .tiff
Adobe Flash
Bittorrent
Archives
- .zip
- .rar
- .tar
- .gz .tgz
- .bz2 .tbz
Text
Documents
- .htm .html
- .odt
- .doc
- .pdf
Spreadsheets
Presentations
Audio Files
- .flac
- .ogg
- .mka
- .aac
- .mp3
- .m4a
- .ra
- .wma
Video Files
- .mkv
- .ts
- .qt
- .mp4
- .avi
- .asf
- .rm
- .wmv
File Locations
/
- .htaccess
- Apache mod_rewrite rules for implemented website
- preview.php
- Preview application creator
- public.php
- Public application creator
- TEST.php
- System compatibility tests
This file is safe to delete
admin/
- .htaccess
- Apache mod_rewrite rules for administration
- admin.php
- Administration Application Creator
- css/
- Administration cascaded style sheets
- images/
- Administration images
- scripts/
- Administration javascripts
cache/
Files and processed images are stored here.
Directory must be writable.
dba/
DBA files are stored here.
Directory must be writable.
koi/
- .htaccess
- Apache deny access
- conf.php
- Configuration file. Edit this file.
- koi_base.php
- Shared base classes
- koi_preview.php
- Preview application
- koi_public.php
- Public application
- koi_admin.php
- Admin application
- koi_admin.lang.csv
- Language specific labels
- shared4/
- Public domain libraries
user/
- 400.php
- Custom error handling of 400 Bad Request errors
- 401.php
- Custom error handling of 401 Unauthorized errors
- 402.php
- Custom error handling of 402 Payment Required errors
- 403.php
- Custom error handling of 403 Forbidden errors
- 404.php
- Custom error handling of 404 Not Found errors
- css/
- Recommended directory for css files
- images/
- Recommended directory for image files
- scripts/
- Recommended directory for javascript files
- plugins/
- Put you plug-ins here
- templates/
- Put your templates here
Templates
Recommendation: Take a look at the sample templates located in user/templates, before reading this section.
Template Types
There are two kinds og templates: Page and Element.
Page Templates
- Located in in the user/templates directory
- Naming scheme: page_template_name.php
- Must contain one class called named page_template_name
- Class must extend page_template
- Class must contain the public methods form() and show()
Element Templates
- Located in in the user/templates directory
- Naming scheme: element_template_name.php
- Must contain one class called named element_template_name
- Class must extend element_template
- Class must contain the public methods form(), show(), and thumbnail()
Template Methods
These methods must be implemented in the templates.
form()
- Both page and element templates must contain this method.
- Method is called when editing the page or element.
- Should contain calls to quick_page_form or quick_element_form only.
show()
- Both page and element templates must contain this method.
- Method is called when rendering the page or element.
- Access to $this->page and $this->element. Use print_r() to see available data.
- Build page using the get_page(), get_file(), get_image, and get_element() methods.
thumbnail()
- Only element templates must contain this method.
- Must return two element array (name, file_id)
- You will probably want to use $this->element->data['name'] for name
- You will probably want to use $this->element->data['field'] for file_id
- Use null for default file_id
Available Methods
The following methods are available through parent classes page_template and element_template:
get_page()
- Parameters: page_id or alias
- Returns array with detailed information, just like $this->page for Page templates.
get_element()
- Parameters: element_id
- Returns array with detailed information, just like $this->element for Element templates.
get_elements()
- Parameters: List of element_id seperated by # (the default format from get_page())
- Returns array of information from get_element().
show_element()
- Parameters: element (from get_element() or get_elements())
- Calls the show() method of the element template.
get_file()
- Parameters: file_id
- Returns array with detailed information about the file. Use this method for non-images and full size images.
get_image()
- Parameters: file_id, geometry
- Geometry is passed directly to ImageMagick.
Examples:
110x95 resize to max 100x95 while maintaining aspect ratio
110x resize to width 110 while maintaining aspect ratio
x95 resize to height 95 while maintaining aspect ratio
110x95> resize to max 110x95 while maintaining aspect ratio if image exceeds 110x95
110x95! resize to exactly 100x95 ignoring aspect ratio
- Returns array with detailed information about the imagee.
is_preview()
- Parameters: None
- Returns (bool) whether page/element is being displayed in preview or live mode.
Quick Forms
Two classes, quick_page_form and quick_element_form, exist to help you implement the form() method.
__construct()
- Parameters: $this->page or $this->element depending on template.
- Outputs: Nothing.
head()
- Parameters: None.
- Outputs: Start of form and checkbox to enable/disable page/element.
Page only: Text fields for title and alias.
foot()
- Parameters: None.
- Outputs: Submit buttom and end of form.
text()
- Parameters: Unique field name, label.
- Outputs: An optional text field.
text_req()
- Parameters: Unique field name, label.
- Outputs: A required text field.
email()
- Parameters: Unique field name, label.
- Outputs: An optional text field. Must contain valid e-mail if set.
email_req()
- Parameters: Unique field name, label.
- Outputs: A required text field. Must contain valid e-mail.
textarea()
- Parameters: Unique field name, label.
- Outputs: An optional text area.
textarea_req()
- Parameters: Unique field name, label.
- Outputs: A required text area.
date()
- Parameters: Unique field name, label.
- Outputs: Optional date construction: Five text fields for year, month, date, hour and minute. Also calendar and clear icons.
date_req()
- Outputs: Required date construction: Five text fields for year, month, date, hour and minute. Also calendar icon.
- Outputs: .
checkbox()
- Parameters: Unique field name, label.
- Outputs: Checkbox.
select()
- Parameters: Unique field name, label, items.
items is an associative array containing keys => values.
- Outputs: Optional select box (optional means that the first element, typical "select from list", may be chosen).
select_req()
- Parameters: Unique field name, label, items.
- Outputs: Required select box (required means that the first element, typical "select from list", may not be chosen).
media()
- Parameters: Unique field name, label.
- Outputs: Box to select media and trash can if chosen.
richtext()
- Parameters: Unique field name, label.
- Outputs: Rich text editor.
page_link()
- Parameters: Unique field name, label.
- Outputs: Optional select box for another page.
page_link_req()
- Parameters: Unique field name, label.
- Outputs: Required select box for another page.
splitter()
- Parameters: None.
- Outputs: A horizontal line.
description()
- Only available for pages.
- Parameters: None.
- Outputs: Text field for meta description.
keywords()
- Only available for pages.
- Parameters: None.
- Outputs: Text field for meta keywords.
template()
- Only available for pages.
- Parameters: None.
- Outputs: Select box for page template.
release_expire()
- Only available for pages.
- Parameters: None.
- Outputs: Date construction for page release and expiraion dates.
special()
- Only available for pages.
- Parameters: None.
- Outputs: Hidden input that marks the page with a gear wheel.
elements()
- Only available for pages.
- Parameters: Unique field name, label, templates.
templates may be a string or array containing class names of page templates.
- Outputs: Box containing elements and buttons to add, delete and move elements..
Plugins
Put your plug-ins (some PHP script you write) in the user/plugins directory. One sub directory for each plug-in, e.g. user/plugins/my_plugin.
You can change the icon by placing a 16x16 PNG file named koi.png in the above sub directory.
You can change the plugin name by placing a text file containing the name in same directory. The text file must be called koi.txt.
Place the following PHP code in at the top of your plug-in:
ini_set('include_path', '.:../../../koi/:../../../koi/shared4/');
require 'koi_admin.php';
$koi = new koi_admin;
if (!$koi->authenticate(@$_COOKIE['username'], @$_COOKIE['password'])) {
die('401 Unauthorized');
}
PHP Code: Files and Classes
This section is only relevant for developers, who want to help develop koi.
shared4/abstraction.php
Note: This file is public domain and not part of koi.
- class xml_gen
- XHTML abstraction layer
- class table_xml_gen
- XHTML abstraction layer for tables
- class form_xml_gen
- XHTML abstraction layer for forms with javascript validation
shared4/application.php
Note: This file is public domain and not part of koi.
- class application
- Generic web application
shared4/dbobject.php
Note: This file is public domain and not part of koi.
- class dbobject
- Object oriented access to MySQL tables
shared4/mysql.php
Note: This file is public domain and not part of koi.
- class mysql
- MySQL abstraction layer
koi_base.php
- abstract class template
- Abstract superclass extended for all templates
- abstract class element_template extends template
- Abstract superclass for element templates
- abstract class page_template extends template
- Abstract superclass for page templates
- class page_template_standard extends page_template
- The standard page template
- class page_container
- Container class for pages
- class element_container
- Container class for elements
- class file_container
- Contianer class for files
- abstract class koi_app
- Abstract class extended by the public and preview applications
koi_public.php
- class koi_public extends koi_app
- Application generating the implemented website
koi_preview.php
- class koi_preview extends koi_app
- Application generating preview of implemented website
koi_admin.php
- class koi_admin extends application
- Administration pplication
- class dbElement extends dbObject
- Object oriented access to Element table
- class dbFile extends dbObject
- Object oriented access to File table
- class dbFolder extends dbObject
- Object oriented access to Folder table
- class dbPage extends dbObject
- Object oriented access to Page table
- class dbUser extends dbObject
- Object oriented access to User table
- class Page extends dbPage
- Page object for administration
- class Element extends dbElement
- Element object for administration
- abstract class quick_form
- Quick Form abstract superclass
- class quick_element_form extends quick_form
- Quick Form for elements
- class quick_page_form extends quick_form
- Quick Form for pages
Copyright © 2008 by Wagawaga & Allan Hansen