INTRODUCTION TO IN-PORTAL
-------------------------

In-Portal is Open Source object-oriented framework that is developed
in PHP and provides quick and easy way to build websites and web applications.

In-Portal Framework has modular structure that allows painlessly
add and extend already existing features via new modules.

In-Portal Community greatly appreciates any type of involvement
and contributions to the project.

Please visit

	http://www.in-portal.org/contribute.html

to see how You can participate and be a part of In-Portal Community.


THIS DEVELOPMENT KIT
--------------------

This README file provides you with the basic understanding and content
of provided Development Kit.

Latest version of this Development Kit can be downloaded here

	http://www.in-portal.org

	http://source.in-portal.org/custom/tags

This Development Kit is implemented and called "Custom" so it can be used
by developers as HOWTO create new modules as well as extend existing
modules not worrying about upgrading issues in the future.

This module contains samples of the most basic and widely used features
of In-Portal. While the code might look very simple, though it provides
a quick and effective way to unlock most powerful capabilities for
In-Portal customization on many levels.


FOLDER STRUCTURE
----------------

1. All In-Portal modules have the same folder structure, that provides a quick
access to each aspect of it's functionality. Top folder is the module name
in a LOWERCASE. It is "custom" for "Custom" module, "in-link" for "In-Link"
module and so on.

2. Inside there are three (3) main folders:

		* admin_templates/ - templates and resources (images, javascript, etc.),
		these are used Admin ONLY.

		* units/ - business logic of the module, used on both Front-end and Admin.

		* install/ - contains files used to install the module into existing
		In-Portal installation.


2.1. Content of "admin_templates/" folder.

This folder contains one (1) sub-folder for each Section in Admin console's
main navigation menu (in left frame). Each such folder should ONLY contain
templates ("*.tpl" files) used for displaying given Section in the main
navigation menu in Admin console.

Besides that there are one special purpose folder called "img/".
This folder contains all kind of images divided by categories (usage).
Images from each category (usage) are located in special sub-folder
associated with the given image category.

There are three (3) main folders

	* "icons/" - images, that will be used as Section icons in the
	main navigation menu next to the actual titles;
	NOTE one image per one menu Section, but the same image could be used
	for multiple menu Section.

	* "itemicons/" - images, that will be shown on the left from each
	row in grid of records (also called list).

	* "toolbar/" - images, that are used to draw buttons on toolbar
	on module templates that uses toolbar-based interface ONY.

	NOTE that it is not restricted to create any other folders
	and place images inside them or in the "img/" folder itself.

	NOTE it is also common practice to create a "js/" sub-folder
	and place all javascript scripts related to the Admin console inside.


2.2. Content of "units/" folder

This folder can contain unlimited number of sub-folders.

Each sub-folder should contain "*.php" files with the business logic
implementation for the given functionality.

Usually there are three (3) files

	- Unit Config - main file, that allows to connect a given Unit into the framework;

	- Event Handler - all code, that will manipulate with the data is located here;

	- Tag Processor - all code, that is used to output the data to a user
	in any requested form is located here.

	It is NOT permitted to create files in "units/" folder itself, only sub-folder
	as described above.

	HOWEVER it is not prohibited to place a group of "unit" type folders inside
	other "unit" type folders to logically divide them into groups.
	Example, "units/logs/visits/" and "units/logs/summary/" both located inside
	of "units/logs" folder, but each has it's own Unit Config, Event Handler, Tag Proccesor.


2.3. Content of "install/" folder.

This folder contains files used to during the installation which will automaticall install

	* install Language Phrases
	* install Email Events
	* apply Database changes (e.g. new tables)

associated with given module.

There are also "upgrades.sql" (required) and "upgades.php" (not required). These files
allow to maintain module version based on database structure control.


3. BASIC UNDERSTANDING AND USAGE
--------------------------------

Visual part of Admin console consists of tree (3) parts

	* Top - contains website logo, logout link and some other things.

	* Left - contains main navigation menu (list of Sections) and used to control all functionality.

	* Right - main part that show the actual Section and data.


3.1 Adding a new Section item

As we know left part of Admin console contains main navigation menu
so it's crucial to learn add a new Sections.

New menu Sections are added using Unit Config files (desribed above).
Each unit can have unlimited number of menu Sections (and Sub-Sections)
at any place inside the main navigation menu.

To add a new section you need to add it to 'Sections' array descrived in Unit Config file
of corresponding/related Unit, for example open "custom/units/widgets/widgets_config.php"

	'Sections' => Array (
		'custom' => Array (
			'parent'		=>	'in-portal:root',
			'icon'			=>	'custom',
			'label'			=>	'la_title_SampleMenuItem',
			'url'			=>	Array ('t' => 'custom/widgets/widget_list', 'pass' => 'm'),
			'permissions'	=>	Array ('view', 'add', 'edit', 'delete'),
			'priority'		=>	1,
			'type'			=>	stTREE,
		),
	),


4. WHAT'S NEXT
--------------

While we can write thousands of lines in this file we decided
to put all our knowledge base online using old good Wiki.

Please feel free to read, ask questions and participate in In-Portal Community!

	http://guide.in-portal.org/eng/index.php

	http://www.in-portal.org/contribute.html