Kurogo Tutorial 08 - Configuration-

Configuration

Kurogo 프레임워크는 조금만 셋업해도 동작할 수 있도록 만들어 졌습니다. 어쨌든 파일위치, 디버깅 정보 그리고 모듈의 기능에 영향을 미치는 모듈 옵션들이나 다른 기능들에 익숙해 지셔야 프레임워크를 잘 활용하실 수 있습니다.

모든 confituration은 .ini 파일들에서 이루어 집니다. 직접 이 파일을 수정하셔도 되고 어드민 모듈에서 수정하셔도 됩니다.

Structure of .ini Files

대부분의 개발자들이나 administrator들은 .ini 파일 구조에 익숙해지셔야 합니다. ini 파일들에 대한 깊은 정보는 PHP 매뉴얼의 parse_ini_file() 함수 부분을 보시면 도움이 되실 겁니다.

Properties

ini 파일에 있는 기본적인 요소는 property 입니다 모든 프로퍼티는 name과 value를 가지고 있습니다. 그리고 그 관계는 = 으로 설정합니다. name은 = 기호 왼쪽에 위치합니다. String 은 큰 따옴표 "" 로 감싸져야 합니다. Constants(상수) 들은 큰 따옴표 바깥쪽에 있을 수 있습니다. Kurogo에서 사용하는 별도의 방법은 {} 를 key name에 사용할 수 있게 한 겁니다.

key1="value"
key2=CONSTANT
key3=ANOTHER_CONSTANT "value"
key4="Using value {key3}"

Sections

Properties may be grouped into arbitrarily named sections. The section name appears on a line by itself, in square brackets ([ and ]). All properties after the section declaration are associated with that section. There is no explicit “end of section” delimiter; sections end at the next section declaration, or the end of the file. Sections may not be nested.

프로퍼티는 임의로 명명된 섹션들의 group 화 될 수 있습니다. 섹션 이름은 해당 라인에 [] (square brackets) 안에 있게 됩니다. 섹션 정의 이후의 모든 프로퍼티들은 해당 세션과 연관이 있는 것들입니다. 그 섹션의 끝을 나타내는 특별한 기호(구분자)는 없습니다. 해당 섹션은 그 다음 섹션 정의 부분 에서 끝납니다. 섹션은 nested 되지 않습니다.

[section]

Comments

세미콜른은 주석의 시작을 의미합니다. 주석은 그 줄의 끝까지 해당 됩니다. 세미콜른이 있는 라인의 내용은 엔진이 무시하고 넘어 갑니다.

; comment text

Configuration files

모듈이 작동할 때 아래 config 파일들이 자동으로 로딩 됩니다.;

- config/kurogo.ini : framework config file. 주요 기능은 active site와 configuration mode를 알려줌
- SITE_DIR/config/site.ini : site configuration file. 모든 모듈이 공유하는 프로퍼티가 있고 기본 환경을 세팅해 줌
- SITE_DIR/config/strings.ini : Strings table. 사이트에서 사용하는 다양한 string들을 포함
- SITE_DIR/config/MODULEID/module.ini : 현재 모듈에 대한 Basic configuration file. disabled status, protected, secure and authorization 을 포함한 모듈과 관련된 프로퍼티들이 있음. 또한 다른 unique 한 다른 module configurable parameters 들도 있음
- SITE_DIR/config/MODULEID/pages.ini : 현재 모듈에 대한 Title/navigation configuration

다른 모듈들은 external data configuration 과 모듈 output 과 formatting을 위한 특정 configuration을 위해 SITE_DIR/config/MODULEID 폴도로부터 파일들을 로드할 겁니다.

Local Files

쿠로고 프레임워크는 로컬 서버 customization을 위해 configuration 파일을 overrid 할 수 있도록 지원합니다. config/kurogo.ini 안에 있는 CONFIG_IGNORE_LOCAL 이 1로 설정되지 않는 한 프레임워크는 각 configuration file이 로드될 때 파일이름이 -local로 된 파일도 같이 로드합니다. 예를 들어 SITE_DIR/config/site.ini 은 SITE_DIR/config/site-local.ini 로 override 될 수 있습니다. ITE_DIR/config/home/module.ini는 SITE_DIR/config/home/module-local.ini로 오버라이드 될 수 있구요. 전체 파일읠 duplicate 할 필요는 없습니다. 오직 -local에서 다르게 작동해야만 하는 부분이 있으면 그 부분만 넣어 주시면 됩니다. 그리고 기본 config에 없는 내용을 -local 에 추가할 수도 있습니다.

These files are ignored by the git version control system and are an excellent place to put sensitive file paths or credentials that should not be part of a public source code repository. It can also aid in deployment since your development machine may use different settings than a production server.

If CONFIG_IGNORE_LOCAL is set to 1, then -local files will be ignored. This is useful if you do not use them and may slightly improve performance.
Configuration Mode

In addition to -local files. There is also an option to include configuration override files by specifying a mode string. This string is like -local but can be set to any value. This will allow you to create multiple versions of configuration files, with slightly different versions of certain values and instantly switch between them. This option is set in the CONFIG_MODE value of config/kurogo.ini These files are not ignored by git.

One use of this would be to create development and production versions of some of your configuration files. You can have SITE_DIR/site-development.ini and SITE_DIR/site-production.ini with differing values for debugging. Then you can set CONFIG_MODE to development or production. If CONFIG_MODE is empty (the default), than no files will be searched. Another example would be to include authorization values for certain modules in a production environment.

Keep in mind that this setting is independent of -local files. -local files will override any option presuming CONFIG_IGNORE_LOCAL is not enabled.

Kurogo has included a series of example -production.ini files to indicate recommended values for production servers
Retrieving Configuration Values

There are a variety of methods that are used to retrieve values from the configuration files. Please see Module Configuration for more information on how to retrieve these values in your module.
Site Configuration

The SITE_DIR/config/site.ini file configures the basic site configuration. It is broken up into several sections
Error handling and debugging

The properties in this section are used during development. Most of them are boolean values (0 is off, 1 is on)

    DEFAULT_LOGGING_LEVEL - See Logging in Kurogo for more information.
    LOGGING_LEVEL[area] - See Logging in Kurogo for more information.
    DISPLAY_ERRORS - Display PHP errors. This can make discovering bugs more easy. You should turn this off on a production site.
    DEVICE_DEBUG - When the framework is running in device debugging mode, you can prepend any framework url with device/[PAGETYPE]-[PLATFORM]/ or device/[PAGETYPE]/ to see that version of the page in your browser. So for example “/device/basic/about/” will show the basic version of the About module’s index page.
    MODULE_DEBUG - Enables debugging information provided by each module. The type of information will vary by module. An example of this is showing the LDAP server used by the People module
    MINIFY_DEBUG - When Minify debugging is turned on, Minify adds comments to help with locating the actual file associated with a given line.
    DATA_DEBUG - Data debugging enables logging and certain output to debug data connections. When turned on, it will log url requests in the error log.
    DEVICE_DETECTION_DEBUG - Show the device detection info in the footer
    PRODUCTION_ERROR_HANDLER_ENABLED - The production error handler will email exceptions to the DEVELOPER_EMAIL address. You should treat exceptions as extraordinary situations that should normally not occur in production environments.
    DEVELOPER_EMAIL - an email address to send exception notices. At this time, it uses the php mail() function so it may not be compatible with all environments.

You should turn the _DEBUG options to off in a production environment and enable the Production Error Handler with an appropriate developer email address.
Site settings

    SITE_DISABLED - When set to 1 this site is disabled. Useful for MultiSite
    SECURE_REQUIRED - When set to 1 then the site will require a secure (https) connection
    SECURE_HOST - Alternate hostname to use for secure (https) connections. If not included it will use the same host name.
    SECURE_PORT - Alternate port to use for secure connections. Typically you should leave it at the default of 443
    LOCALE - Locales are used for date/time formatting. If you wish to use a locale other than the server default, then you should set this. Note that valid values are dependent on the operating system of the server.
    LANGUAGES[] - A list of language priorities. See Localization for more info.
    LOCAL_TIMEZONE - Set this to your environment’s time zone. See http://php.net/manual/en/timezones.php for a list of valid time zones
    LOCAL_AREA_CODE - Set this to your environment’s primary area code
    AUTODETECT_PHONE_NUMBERS - Turn this off to prevent the auto detection of telephone numbers in content. This is primarily only supported in iOS devices at this time.

Modules

    DYNAMIC_MODULE_NAV_DATA - This value determines whether modules can present dynamic data on the navigation home screen. This could include dynamic titles, images or other information. If you are not providing dynamic data, then you should turn off this option. It is off by default. See Dynamic Home Screen Information for more information
    CREATE_DEFAULT_CONFIG - This value determines whether config folders will be automatically created if they don’t exist. This can be convienient for development when you want to populate a config folder with the default values, but should be turned off for production to ensure modules that you don’t use don’t create configuration folders.

Cache

    MINIFY_CACHE_TIMEOUT - The timeout for saving the minify cache. This determines how often to look for new templates or css/js files. It should be set high for production sites.

Analytics

    GOOGLE_ANALYTICS_ID - set this to your google analytics id and the framework will utilize the google analytics server
    GOOGLE_ANALYTICS_DOMAIN - If you use subdomains in your google analytics reporting, set this to the appropriate domain
    PERCENT_MOBILE_ID - set this to your percent mobile analytics id and the framework will utilize the percent mobile analytics server
    STATS_ENABLED - if set to 0 then the internal statistics engine will be disabled
    KUROGO_STATS_TABLE (kurogo_stats_v1) - The name of the table to use for internal statistics gathering
    KUROGO_VISIT_LIFESPAN (1800) - The timeout (in seconds) for tracking visits

Temp Directory

    TMP_DIR - This should be set to your a writable temporary directory. If this entry is blank, it will use the system default temporary directory.

Themes

    ACTIVE_THEME - This is set to the active theme. It should be a valid folder inside the SITE_DIR/themes directory.
    TABLET_ENABLED - If set to 0 then the tablet devices will receive the compliant page type templates.

URL Rewriting and the default page

In the [urls] section you can put a series of values that allow you to map a url to another. Typically this would be if you want to map a module’s url to several possible values, perhaps to maintain historical bookmarks. The entered url will be redirected to the value you specify. For example:

    directory = people would map the url /directory to /people (i.e. the people module)

Take care that you do not create infinite redirect loops.

There is a special case for the DEFAULT url. This is the module that is loaded when users enter your site without a module name (i.e. the root of your site). You can configure this to show a different module depending on the type of device/platform. In the initial setting, users browsing your site from a computer will be presented with the info module and users browsing your site from a mobile device will be shown the home module.

The default option will look for the most specific value when determining which default page to show. You can create entries like such (in uppercase)

        DEFAULT-PAGETYPE-PLATFORM - matches the specific pagetype/platform combination. like DEFAULT-COMPLIANT-COMPUTER or DEFAULT-TOUCH-BLACKBERRY.
        DEFAULT-PAGETYPE - matches all the devices from a particular pagetype. Like DEFAULT-COMPLIANT or DEFAULT-BASIC
        DEFAULT will match any device if a more specific entry is not found

This allows you to customize the front door experience for your users.
Device Detection

See Device Detection for more information on configuration values.
Cookies

    MODULE_ORDER_COOKIE_LIFESPAN - How long (in seconds) to remember the module order customization. In production sites this should be set to a long time, like 15552000 (180 days)
    LAYOUT_COOKIE_LIFESPAN - How long to remember the device detection results for pagetype and platform. In production sites this should be set to a long time, like 1209600 (14 days)
    BOOKMARK_COOKIE_LIFESPAN - How long to remember the saved bookmarks for a user. In production sites this should be set to a long time, like 15552000 (180 days)

Database

The main database connection can be used by a variety of modules for storing and retrieving values. See the database section for specific information on configuration values.
Authentication

    AUTHENTICATION_ENABLED - Set to 1 to enable authentication
    AUTHENTICATION_IDLE_TIMEOUT - Idle Timeout in seconds before users are logged off Use 0 to disable
    AUTHENTICATION_USE_SESSION_DB - If 1 then session data will be saved to the site database
    AUTHENTICATION_REMAIN_LOGGED_IN_TIME - Time in seconds where users can choose to remain logged in even if closing their browser. If this is set to 0 then user’s cannot remain logged in. Typical times are 604800 (7 days) or 1209600 (14 days).

Log Files

    KUROGO_LOG_FILE - The location of the Kurogo log file. This is where all Kurogo log statements will be placed depending on the value of DEFAULT_LOG_LEVEL
    LOG_DATE_FORMAT - Date format for log files
    LOG_DATE_PATTERN - regex pattern of log dates, should match output from LOG_DATE_FORMAT

Module Visibility and protection

Each module contains an configuration file in SITE_DIR/config/moduleID/module.ini. This file contains values common to all modules, as well as module specific values.

    id - The module id to use. By default this will be the same name as the moduleID. You can change this to create a copied module or to use another module’s code at this url.
    title - The module title. Used in the title bar and other locations
    disabled - Whether or not the module is disabled. A disabled module cannot be used by anyone. Use this value for temporarily disabling modules.
    search - Whether or not the module provides search in the federated search feature.
    secure - Whether or not the module requires a secure (https) connection. Configuring secure sites is beyond the scope of this document.

Permanently disabling modules

When CREATE_DEFAULT_CONFIG is set to 0, if you remove a module’s config folder it will be permanently disabled and will not be accessible.
Optional Common Module Settings

    SHOW_LOGIN - By default the login link only appears on the home module. If you wish for it to show up on other modules, you can set this value to 1 on any module you wish to see it. You could also set this to 0 on the home module to suppress its showing.

Home Screen

See Home Module for information on configuring the look and layout of the home screen.
Strings

There are a number of strings that are used throughout the framework to identify the site name the organization it is a part of. These include:

    SITE_NAME - The name of the site. Used in the footer and other places.
    COPYRIGHT_LINK - Link to copyright notice (optional)
    COPYRIGHT_NOTICE - Copyright notice
    FEEDBACK_EMAIL - email address where users can send feedback.

Administration Module

In addition to editing these files, you can use the administration module to manage the configuration. The admin module is located at /admin and does not have an icon on the home screen.