-In-Portal is object-oriented php framework, that allows to build websites quick and easy way. Framework has modular structure and allows for new features to be added to if via new modules. In standard package In-Portal aready contains 3 live modules - In-Link, In-News, In-Bulletin and one sample module "Custom".
+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.
-1. Purpose of Custom
-====================
-"Custom" module is sample In-Portal module, that can be used to create your own modules. This module contains of samples of most basic and widely used features of In-Portal. Despite that given sample code seems to very simple, though it provides quick and effective way to unlock most powerful In-Portal customization abilities.
+In-Portal Framework has modular structure that allows painlessly
+add and extend already existing features via new modules.
-2. Content of folders
-=====================
-Each module has same folder structure as other modules, that allows quick access to each aspect of it's functionality. Top folder is module name in lowecase and it is "custom" for "Custom" module, "in-link" for "In-Link" module and so on. Then there are 3 main folders: "admin_templates" - templates and resources (images, javascript, etc.), that given module uses only in administrative console; "units" - business logic, that given module will provide on both front-end and administrative console and "install" folder, that contains files, used to install given module into existing In-Portal installation.
+In-Portal Community greatly appreciates any type of involvement
+and contributions to the project.
-2.1. About "admin_templates" folder.
-This folder contains one sub-folder for each item in administrative console's main menu (in left frame). Each such folder will only contain templates ("*.tpl" files) used for displaying given main menu item in administrative console. Besides that there are one special purpose folder called "img". This folder contains all kind of images divided by categories. Images from each category are located in special sub-folder associated with given image category. There are three main folders - "icons" (images, that will be shown on the left from main menu item titles; one image per one menu item; one image could be used for multiple menu items); "itemicons" (images, that will be shown on the left from each row in grid, when grid, driven from given menu item will be shown); "toolbar" (images, that are used to draw buttons on toolbar on only module template, that uses toolbar based interface). It is possible to create any number of other folders and place images inside them or in the "img" folder itself. It is also common to create "js" sub-folder and place all javascript scripts related to administrative console in it.
+Please visit
-2.2. About "units" folder.
-This folder can contain unlimited number of folders. Each folder will contain "*.php" files used to create business logic part of given module. Usually there are three files - unit config file (main file, that allow to integrate given unit into system) and can't be absent; event handler file (all code, that will manipulate with data is located here); tag processor file (all code, that is used to output data to user in any requested form is located here). There is not permitted to create files in "units" folder itself, only sub-directories. Although it is not prohibited to place group of unit folders into other folders under "units" folder to logically divide them into groups.
+ http://www.in-portal.org/contribute.html
-2.3. About "install" folder.
-This folder contains files used to add phrases, email events and to apply database changes (e.g. new tables) associated with given module. There are also "upgrades.sql" (required) and "upgades.php" (not required), that allow to maintain module version based database structure control, e.g. allows to upgrade database structure associated with given module depending on module version.
+to see how You can participate and be a part of In-Portal Community.
-3. Basic mechanisms / usage
-===========================
-Administrative console consists of 3 parts (top, left, right). Top part contains website logo, logout link and some other things. Left part contains main administrative console's menu used to control all it's functionality. When menu item is clicked, then template associated with given menu item is shown in right part of administrative console.
-3.1 Adding menu item
-====================
-Left part of administrative console contains menu, that have various menu items in it. Menu items are added using configuration files of units. Each unit can add unlimited number of menu items at any place inside main menu. New menu items are added using "Sections" option in configuration file as follows:
-$config => Array (
+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"