1		INTRODUCTION TO IN-PORTAL
			2		-------------------------
			3
			4		In-Portal is Open Source object-oriented framework that is developed
			5		in PHP and provides quick and easy way to build websites and web applications.
			6
			7		In-Portal Framework has modular structure that allows painlessly
			8		add and extend already existing features via new modules.
			9
			10		In-Portal Community greatly appreciates any type of involvement
			11		and contributions to the project.
			12
			13		Please visit
			14
			15		http://www.in-portal.org/contribute.html
			16
			17		to see how You can participate and be a part of In-Portal Community.
			18
			19
			20		THIS DEVELOPMENT KIT
			21		--------------------
			22
			23		This README file provides you with the basic understanding and content
			24		of provided Development Kit.
			25
			26		Latest version of this Development Kit can be downloaded here
			27
			28		http://www.in-portal.org
			29
			30		http://source.in-portal.org/custom/tags
			31
			32		This Development Kit is implemented and called "Custom" so it can be used
			33		by developers as HOWTO create new modules as well as extend existing
			34		modules not worrying about upgrading issues in the future.
			35
			36		This module contains samples of the most basic and widely used features
			37		of In-Portal. While the code might look very simple, though it provides
			38		a quick and effective way to unlock most powerful capabilities for
			39		In-Portal customization on many levels.
			40
			41
			42		FOLDER STRUCTURE
			43		----------------
			44
			45		1. All In-Portal modules have the same folder structure, that provides a quick
			46		access to each aspect of it's functionality. Top folder is the module name
			47		in a LOWERCASE. It is "custom" for "Custom" module, "in-link" for "In-Link"
			48		module and so on.
			49
			50		2. Inside there are three (3) main folders:
			51
			52		* admin_templates/ - templates and resources (images, javascript, etc.),
			53		these are used Admin ONLY.
			54
			55		* units/ - business logic of the module, used on both Front-end and Admin.
			56
			57		* install/ - contains files used to install the module into existing
			58		In-Portal installation.
			59
			60
			61		2.1. Content of "admin_templates/" folder.
			62
			63		This folder contains one (1) sub-folder for each Section in Admin console's
			64		main navigation menu (in left frame). Each such folder should ONLY contain
			65		templates ("*.tpl" files) used for displaying given Section in the main
			66		navigation menu in Admin console.
			67
			68		Besides that there are one special purpose folder called "img/".
			69		This folder contains all kind of images divided by categories (usage).
			70		Images from each category (usage) are located in special sub-folder
			71		associated with the given image category.
			72
			73		There are three (3) main folders
			74
			75		* "icons/" - images, that will be used as Section icons in the
			76		main navigation menu next to the actual titles;
			77		NOTE one image per one menu Section, but the same image could be used
			78		for multiple menu Section.
			79
			80		* "itemicons/" - images, that will be shown on the left from each
			81		row in grid of records (also called list).
			82
			83		* "toolbar/" - images, that are used to draw buttons on toolbar
			84		on module templates that uses toolbar-based interface ONY.
			85
			86		NOTE that it is not restricted to create any other folders
			87		and place images inside them or in the "img/" folder itself.
			88
			89		NOTE it is also common practice to create a "js/" sub-folder
			90		and place all javascript scripts related to the Admin console inside.
			91
			92
			93		2.2. Content of "units/" folder
			94
			95		This folder can contain unlimited number of sub-folders.
			96
			97		Each sub-folder should contain "*.php" files with the business logic
			98		implementation for the given functionality.
			99
			100		Usually there are three (3) files
			101
			102		- Unit Config - main file, that allows to connect a given Unit into the framework;
			103
			104		- Event Handler - all code, that will manipulate with the data is located here;
			105
			106		- Tag Processor - all code, that is used to output the data to a user
			107		in any requested form is located here.
			108
			109		It is NOT permitted to create files in "units/" folder itself, only sub-folder
			110		as described above.
			111
			112		HOWEVER it is not prohibited to place a group of "unit" type folders inside
			113		other "unit" type folders to logically divide them into groups.
			114		Example, "units/logs/visits/" and "units/logs/summary/" both located inside
			115		of "units/logs" folder, but each has it's own Unit Config, Event Handler, Tag Proccesor.
			116
			117
			118		2.3. Content of "install/" folder.
			119
			120		This folder contains files used to during the installation which will automaticall install
			121
			122		* install Language Phrases
			123		* install Email Events
			124		* apply Database changes (e.g. new tables)
			125
			126		associated with given module.
			127
			128		There are also "upgrades.sql" (required) and "upgades.php" (not required). These files
			129		allow to maintain module version based on database structure control.
			130
			131
			132		3. BASIC UNDERSTANDING AND USAGE
			133		--------------------------------
			134
			135		Visual part of Admin console consists of tree (3) parts
			136
			137		* Top - contains website logo, logout link and some other things.
			138
			139		* Left - contains main navigation menu (list of Sections) and used to control all functionality.
			140
			141		* Right - main part that show the actual Section and data.
			142
			143
			144		3.1 Adding a new Section item
			145
			146		As we know left part of Admin console contains main navigation menu
			147		so it's crucial to learn add a new Sections.
			148
			149		New menu Sections are added using Unit Config files (desribed above).
			150		Each unit can have unlimited number of menu Sections (and Sub-Sections)
			151		at any place inside the main navigation menu.
			152
			153		To add a new section you need to add it to 'Sections' array descrived in Unit Config file
			154		of corresponding/related Unit, for example open "custom/units/widgets/widgets_config.php"
			155
			156		'Sections' => Array (
			157		'custom' => Array (
			158		'parent'                =>      'in-portal:root',
			159		'icon'                  =>      'custom',
			160		'label'                 =>      'la_title_SampleMenuItem',
			161		'url'                   =>      Array ('t' => 'custom/widgets/widget_list', 'pass' => 'm'),
			162		'permissions'   =>      Array ('view', 'add', 'edit', 'delete'),
			163		'priority'              =>      1,
			164		'type'                  =>      stTREE,
			165		),
			166		),
			167
			168
			169		4. WHAT'S NEXT
			170		--------------
			171
			172		While we can write thousands of lines in this file we decided
			173		to put all our knowledge base online using old good Wiki.
			174
			175		Please feel free to read, ask questions and participate in In-Portal Community!
			176
			177		http://guide.in-portal.org/eng/index.php
			178
			179		http://www.in-portal.org/contribute.html