Index: branches/1.0.x/custom/README =================================================================== diff -u -N --- branches/1.0.x/custom/README (revision 12743) +++ branches/1.0.x/custom/README (revision 0) @@ -1,179 +0,0 @@ -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