Kurogo Tutorial 06 - 소스 코드 여행 -

Source code tour

이 섹션에서는 Kurogo 소스 코드 프로젝트에 있는 다양한 파일들과 디렉토리들을 여행해 볼겁니다. 프로젝트의 레이아웃을 안다는 것은 코딩 이전에 무엇인가를 결정할 때 그리고 여러분의 파일을 어디에 위치 시켜야 할지를 결정할 때 도움을 줄 겁니다.

Basic Layout

Kurogo 폴더의 루트는 몇개의 폴더가 있습니다.

add-ons

이 디렉토리에는 추가적인 scripts나 code들이 들어갑니다. 주로 다른 어플리케이션과  interact 하는데 사용될 수 있습니다.

app

이 대렉토리에는 Kurogo가 제공하는 각 모듈의 code 와 templates 이 들어 있습니다. 또한 각 모듈에 의해 사용되는 shared template도 있습니다. (including headers and footers). lib 폴더에 이런 파일을 add 하거나 altering 하지 말고 Site folder  안에 새로운 파일이나 altered 파일을 넣으세요.

config

이 디렉토리에는 전체 프로젝트에 대한 메인 configuration file들이 들어 있습니다. 가장 주목할 파일은 kurogo.ini file 입니다.

doc (only included in source distribution)

이 디렉토리에는 이 guide를 포함해서 다양한 documentation 파일들이 있습니다. 이 가이드는 Sphinx documentation system 을 사용해서 만들어 졌습니다.

lib

이 디렉토리는 Kurogo에서 제공하는 라이브러리가 있습니다. data retrieval, parsing, authentication, database access 라이브러리와 configuration 등이 있습니다. 일반적으로 Kurogo가 제공하는 라이브러리만 이 디렉토리에 있어야 합니다. 여러분의 라이브러리는 SITE_FOLDER/lib 폴더에 넣어야 나중에 프로젝트를 업데이터 할 때 혼동이 없습니다.

site

이 디렉토리에는 각 사이트의 entry 가 있습니다. 좀 더 자세항 사항은 다음을 보세요. Site folder

www

이 디렉토리에는 사이트의 DocumentRoot가 있습니다. 여기에는 모든 incoming request들을 핸들링하는 메인 스크립트인 index.php 가 있습니다. 여기에 또한 css와 javascript가 있게 됩니다. .htaccess 와 web.config 파일은 Apache와 IIS를 위한 URL redirection이 있습니다.

Case Sensitivity

여러분 사이트를 개발 하실 때 대소문자를 구분한다는 사실을 항상 염두에 두세요. 많은 개발자들이 대소문자 구분을 하지 않는 시스템에서 작업을 하십니다. 대부분의 서버에서는 대소문자 구분을 합니다. 그러니까 폴더위치나 url등을 정할 때 이 부분을 잘 염두에 두셔야 합니다.

Provided vs. Site files

레이아웃 섹션에서 말했듯이 app,lib,www 같은 Kurogo에서 제공하는 파일들과 여러분이 사이트 작업을 위해 사용하시는 파일 등이 있습니다. 쿠로고는 오픈소스이기 때문에 여러분의 필요에 따라 소스를 고치셔도 됩니다. 만약 여러분이 프로젝트 디렉토리의 파일을 수정하거나 새 파일을 추가했다면 다음 버전에 업데이트 할 때 문제가 될 수 있습니다. 업그레이드 할 때 이런 부분을 도와주는 것으로 add additional functionality이 있습니다.

그리고 여러분이 좀 더 낫게 수정하면 여러분의 수정사항을  submit your changes 에 알려주시면 감사하겠습니다.

Libraries

이 프레임워크는 모듈라이즈와 특정 프로세스를 추상화하고 코드 재사용을 용이하게 하기 위해 많은 라이브러리를 사용하도록 하고 있습니다. 모든 라이브러리는 PHP 클래스로 돼 있습니다.

Packages

특정 클래스 파일들이나 클래스들을 하나의 패키지로 관리할 수 있습니다. 패키지로 관리함으로서 필요한 파일들을 하나로 묶어서 관리를 편하게 해 줍니다.(use: Kurogo::includePackage(‘PackageName’) in your module code) 현재 아래 패키지들이 사용 가능합니다.

• Authentication (included automatically when authentication is enabled)
• Authorization - for connecting to various OAuth based web services
• Cache - classes dealing with in-memory and disk caching
• Calendar - includes classes to deal with calendar data
• Config - classes to deal with configuration files
• DataController - legacy classes dealing with the pre 1.4 DataController class
• DataModel - subclasses of the DataModel class
• DataParser - subclasses of the DataParser class
• DataResponse - subclasses of the DataResponse class
• DataRetriever - subclasses of the DataRetriever class
• DateTime - classes for handling date and time
• db - used when you wish to interact with a database
• Emergency - used by the emergency module
• Maps - used by the map module
• People - used by the people module
• RSS - classes for handling RSS data
• Session - Subclasses of the session object, used for session management
• Video - used by the video module

Core / Support Files

• compat - defines several functions that normalize behavior throughout PHP versions
• exceptions - defines exception subclasses and sets up exception handling behavior
• Kurogo - a singleton class used to consolidate common operations like initialization, site configuration, and administration. See more
• minify - interface between the framework and the included open source minify library
• DeviceClassifier - An interface between the framework and the Device Detection Service
• deviceData.db - A SQLite database that contains browser entries used by the internal device detection system.
• Validator - A utility class to validate certain types of data

Native API Functions

이 함수는 특정 모듈함수에 접근권한을 주는 API interface를 다루는 함수 입니다. 이 인터페이스들은 native application에 의해 주로 이용됩니다. 그리고 AJAX 를 위한 모듈에 의해서도 사용되어 집니다.

• APIModule - The base class for API modules, inherits from Module
• APIResponse - A class that encapsulates the common response message for API requests

더 자세한 사항은 The APIModule Object 를 보세요.

External Data Retrieval

더 자세한 사항은 Data Retrieval  를 보세요.

Database Access

Kurogo는 데이터베이스 연결관련 configuration을 위해 database connection abstraction library를 제공합니다.

• db - A database access library based on PDO. It includes abstractions for MySQL, SQLite, PostgreSQL and MS SQL. This support is dependent on support in your PHP installation. The setting up and maintaining of databases and their associated extensions is beyond the scope of this document.
• SiteDB - Uses the main database configuration for access.

더 자세한 사항은 Database Access  를 보세요.

User Access and Authentication

• AuthenticationAuthority - 이것은 authenticating users 에 대한 루트 클래스 입니다. It is designed to be subclassed so each authority can provide the means of actually authenticating users, but still maintain a consistent interface for the login module. See Authentication for more information about the included authorities.
• AccessControlList - A class used by the authorization system to restrict access to modules based on user or group membership. This is especially useful for the Administration Module.
• User - The base class for identifying logged in users
• UserGroup - The base class for identifying groups

더 자세한 사항은 Authentication 를 보세요.

Session Management

• Session -  유저의 상태를 저장해서 관리합니다. 현재는 두 종류의 세션이 있습니다.
  

  • SessionFiles - Save and restore session data using the built in file handler
  • SessionDB - Save and restore session data using a database

Configuration

• Config - An abstract class that stores key/value data and has logic for handling replacement values (i.e referencing other keys’ values within a value)
• ConfigFile - Provides an interface for reading and writing an ini configuration file
• ConfigGroup - Provides an interface for coalescing multiple configuration files to provide a single key/value store
• ModuleConfigFile - A specific config file class to load module config files.
• SiteConfig - A specific ConfigGroup that loads the critical site and project-wide configuration files.

configuring Kurogo에 대한 더 자세한 사항은 Configuration 를 보세요. 

Modules and Templates

• Module - The core class that all modules inherit from. Provides a variety of necessary services and behavior to module subclasses. See Writing Modules.
• WebModule - The core class that all web modules inherit from.
• HTMLPager - A support class used to paginate content
• smarty - The Smarty Template System
• TemplateEngine - An subclass of the smarty object used by the framework

더 자세한 사항은 Writing Modules 를 보세요.

Other

• ga - 자바스크립트를 지원하지 않는 브라우저를 위한 google analytics implementation 

Modules and Templates

app 폴더 안에 모듈과 탬플릿 파일들이 있습니다.

Common

common folder 안에는 모든 모듈에서 사용할 수 있는 template과 css 파일들이 있습니다. 이 각각의 탬플릿들은 다른 디바이스별로 몇가지 variant를 가지고 있습니다. (탬플릿 시스템과 파일 네이밍에 대한 좀 더 자세한 정보는 Templates을 보세요.) 이 탬플릿들은 아래와 같은 것들이있습니다.

• footer.tpl content placed at the bottom of most pages
• header.tpl content placed at the top of most pages
• help.tpl template used for displaying help pages
• formList.tpl template used for showing a list that enables input
  • formListItem.tpl template used for an individual form item in a list
• navlist.tpl template used for showing items as a list
  • listitem.tpl template used for an individual item in a list
• pager.tpl - template for providing pagination for long-form content
• results.tpl - template for displaying results in a list
• search.tpl - template for presenting a search box
• share.tpl - template for presenting a sharing content via social networking
• springboard - template for displaying content as a grid of icons
• tabs.tpl - template for displaying content in tabs

Modules

modules 폴더에는 Kurogo와 같이 bundle 된 모든 모듈들이 들어 있습니다. 각 모듈들은 PHP 코드와 탬플릿 파일들이 있습니다. 또한 CSS와 Javascript 파일들도 있습니다. 모듈 디자인에 대한 좀 더 자세한 사항은 Writing Modules 를 보세요.

여기서 naming convention은 아주 중요합니다. (특히 대소문자를 구분하는 시스템에서는요.)

• The folder must be lower case and be the same as the url of the module (/about, /home, /links). You can create modules at other urls by copying the module
• The folder must contain a PHP file named ModulenameWebModule.php. If the module is located in the site folder and it extends an existing module then it should be called SiteModulenameWebModule.php.
• The first (and ONLY) letter of the module must be capitalized and followed by WebModule.php.
  • AboutWebModule.php (NOT aboutwebmodule.php or AboutWebmodule.php)
  • FullwebWebModule.php (NOT FullWebModule.php or FullwebWebmodule.php)
  • SiteNewsWebModule.php (NOT siteNewsWebModule.php or Sitenewswebmodule.php)
• Template files go into the templates folder. There should be a .tpl for each page of the module. At minimum there should be an index.tpl which represents the default page (unless the module alters that behavior). Each page should be in all lower case.
• If you are overriding a project module you only need to include the pages that you are overriding.
• You may choose to place additional css style sheets in a folder named css
• You may choose to place additional javascript scripts in a folder named javascript
• You can provide default configuration files in a folder named config

site folder에 다른 모듈을 생성함으로서 included된 모듈의 behavior를 override 하는 것이 가능합니다. 좀 더 자세한 사항은 Extending an existing module를 보세요. 

Site folder

site folder에는 각 site를 위한 폴더 모임들이 있습니다. 이렇게 함으로서 각 사이트들은 각각 다른 configuration, design, custom code 등을 가질 수 있습니다. 처음 제공되는 디폴트 파일에는 한개의 active site만 있습니다. root Kurogo directory의 config/kurogo.ini file에서 active site를 설정하실 수 있습니다. 여기서 폴더의 이름은 kurogo.ini 파일에 있는 ACTIVE_SITE와 일치해야 합니다.

Multiple site folder는 사이트를 각각 다른 버전으로 개발하고 싶은 경우에 유용하게 사용될 수 있습니다. 각각의 사이트에는 아래와 같은 디렉토리들이 있습니다.

• app - Site specific templates and modules. Inside this folder you will find 2 folders
  • common - Site specific common templates and css
  • modules - Site specific modules. To promote ease when updating the framework to new versions, it is important that you keep site specific modules in this folder rather than in the root app/modules folder. If you wish to include your work in Kurogo, please see GitHub Repository. Also see Extending an existing module.
• cache - Contains server generated files that are cached for performance. This folder is created as needed, but must be writable by the web server process.
• config - Contains the site specific configuration files in .ini format. Many of these files can be managed using the Administration Module
  • site.ini - The general configuration file that affects all site behavior such as timezone, log file locations, database configuration, and more.
  • acls.ini - Site wide access control lists
  • authentication.ini - The configuration for user Authentication.
  • strings.ini - a configuration file containing strings used by the site
  • Each module’s configuration is contained a folder named by its module id. There are several standard files for each module:
    • module.ini - Settings for disabling, access control, search and module variables and strings
    • feeds.ini - Specifies external data connections
    • pages.ini - Titles for each page
    • Modules may have other config files as needed
• data - a folder that contains data files meant to be used by the server. Unlike cache folders, these files cannot be safely deleted. Examples would include data that is not able to be generated from a web service, SQLite databases, or flat authentication files. It is also possible that certain deployments would have nothing in the data folder.
• lib - an optional folder that contains code libraries used by site modules. The Kurogo autoloader will discover and find classes and packages in this folder.
• logs - Log files
• themes - Contains the themes available for this site. Each theme folder contains a common and modules folder that contains the CSS and image assets for the site. See Templates for more information.

WWW Folder

www폴더에 있는 파일과 폴더들은 사이트의 기본 위치인 DocumentRoot 에 있는 겁니다. 바로 대문 앞에 있는 것이죠. 이 구조를 잘 유지하시려면 모든 request,들은 index.php file을 통해서 전달되도록 하셔야 합니다. (예외인 경우는 min이나 minify url 처럼 이미 존재하는 path 나 폴더들일 경우입니다.)

index.php

이 index script 는 프레임워크의 메인 controller입니다. 모든 request들은 .htaccess를 override하고 아파치의 경우 mod_rewrite 를 그리고 IIS의 경우 URL Rewrite extension 사용해서 처리 됩니다. .htaccess file 은 모든 request들을 rewrite 합니다. request된 path를 포함한 $_GET variable _path 등을 rewrite 한느 것이죠. 예를 들어 http://server/module/page 는 http://server/index.php?_page=module/page가 됩니다. $_GET이나 $_POST 변수의 다른 추가적인 데이터도 가능합니다. 좀 더 자세한 사항은 Handling Requests 을 보세요