1 = Developing imip-agent = 2 3 To start developing the imip-agent software further, first obtain the code 4 by following the advice on the [[../Downloads|downloads page]]. Obtaining 5 the code directly from the repository is advisable since any changes you 6 make can then be tracked and managed. 7 8 <<TableOfContents(2,3)>> 9 10 == Distribution Contents == 11 12 The software distribution contains the following directories: 13 14 {{{#!table 15 '''Directory''' || '''Description''' 16 == 17 `conf` 18 || Example configuration files (see the 19 .. [[../GettingStarted|getting started guide]] for details) 20 == 21 `docs` 22 || Documentation, including these wiki pages 23 == 24 `htdocs` 25 || Resources for the [[../CalendarManager|management interface]] 26 == 27 `imiptools` 28 || A Python package providing mail handling and support for calendar 29 .. object processing 30 == 31 `imipweb` 32 || A Python package providing Web-related functionality for the 33 .. [[../CalendarManager|management interface]] 34 == 35 `messages` 36 || Localised messages for the [[../AgentPrograms|agent programs]] and 37 .. [[../CalendarManager|management interface]] 38 == 39 `tests` 40 || A suite of tests used to verify the behaviour of the software 41 .. (see the [[../Testing|testing guide]]) 42 == 43 `tools` 44 || Tools for [[../Administration|administration]] (see also the 45 .. [[../GettingStarted|getting started guide]]) 46 }}} 47 48 At the top level of the distribution, the following files are found: 49 50 {{{#!table 51 '''File''' || '''Description''' 52 == 53 `imip_person.py` 54 ||<rowspan="3"> The main program files for the 55 .. [[../AgentPrograms|agent programs]] 56 == 57 `imip_person_outgoing.py` 58 == 59 `imip_resource.py` 60 == 61 `imip_manager.py` 62 || The [[../CalendarManager|management interface]] main program file 63 == 64 `imip_store.py` 65 || The Python module providing an abstraction over the 66 .. [[../FilesystemUsage|data storage structures]] 67 == 68 `markup.py` 69 || A Python library providing HTML generation support 70 == 71 `README.txt` 72 || Some basic documentation 73 == 74 `vCalendar.py` 75 ||<rowspan="3"> Handling of vCalendar and related data formats 76 == 77 `vContent.py` 78 == 79 `vRecurrence.py` 80 }}} 81 82 == Architectural Components == 83 84 The principal components of the software architecture are described below. 85 86 === vContent === 87 88 The v-prefixed libraries are concerned with the basic interpretation of 89 calendar-related data. For the most part, these libraries should already 90 behave in a predictable and reliable fashion and should not need much 91 further development. There are perhaps some deficiencies in the 92 `vRecurrence` module that are described on the 93 [[../CalendaringSupport|calendaring standards page]]. 94 95 It is not inconceivable that a `vCard` module be introduced in the future 96 to handle vCard data, thus enhancing the data about people within 97 imip-agent, perhaps also supporting mechanisms to obtain free/busy and 98 other information about scheduling participants. 99 100 === imiptools === 101 102 The bulk of the work done in imip-agent happens within `imiptools`. When 103 used from [[../AgentPrograms|agent programs]] launched by the mail system, 104 the different modules support the "handler" functionality that involves 105 obtaining information from calendar data, performing the necessary action 106 related to a scheduling method, and generating responses or notifications. 107 More details are given about these activities in the guide to 108 [[../IncomingMessages|incoming message handling]]. 109 110 When used from the [[../CalendarManager|management interface]], the 111 modules support the Web-based functionality as a more general calendar 112 system client, typically handling a single calendar object at any given 113 time. 114 115 === imipweb === 116 117 Most of the `imipweb` package is concerned with the display of calendar 118 information as Web pages and the handling of submitted data over the Web 119 as users interact with those Web pages. The `imip_manager.py` file is 120 deployed as a [[https://tools.ietf.org/html/rfc3875|CGI]] program, and it 121 acts as a simple "switch" that shows the appropriate kind of Web page (or 122 "view") depending on the requested URL, delegating to one of the modules 123 within the `imipweb` package to do so: 124 125 || '''Module''' || '''View''' || 126 || `imipweb.calendar` || Calendar || 127 || `imipweb.event` || Individual events || 128 || `imipweb.profile` || User profile || 129 130 A general `imipweb.resource` module supports the different views with 131 common functionality. Useful abstractions for period and date information 132 are provided in the `imipweb.data` module. The CGI interfacing is defined 133 in the `imipweb.env` module. 134 135 One of the most awkward aspects of providing a Web interface to events is 136 the need to provide a comprehensive enough representation of period data 137 as expressed in calendar objects that can be held in a form defined in a 138 Web page, interpreted by the program, written back to the form, all 139 without losing information. 140 141 === imip_store === 142 143 The `imip_store` module provides the basis for calendar data persistence. 144 From the very start, the nature of data organisation for calendar users 145 was centred on the storage of each user's free/busy records, since the 146 priority was to generate such records from messages exchanged over e-mail, 147 and the use of plain text files was chosen as the simplest and most 148 transparent approach. Beyond this, the need to retain calendar objects 149 arose, and thus a [[../FilesystemUsage|filesystem-based approach]] was 150 cultivated to manage such data. 151 152 In the future, other persistence mechanisms could be supported. However, 153 aside from performance concerns around access to free/busy schedules, 154 there may be no urgent need to adopt relational database technologies, 155 particularly as each user's data should remain isolated from that of 156 other users, and thus the volumes of data should remain relatively small 157 if managed well enough. 158 159 == Localisation == 160 161 The traditional [[https://www.gnu.org/s/gettext|gettext]] mechanisms for 162 translating labels, messages and other user-readable strings are employed 163 in the imip-agent code. Some tools have been provided to maintain this 164 localisation. 165 166 To extract "messages" from the code, run the `tools/i18n_messages.sh` 167 script: 168 169 {{{ 170 tools/i18n_messages.sh 171 }}} 172 173 This produces a file called `imip-agent.pot` in the current directory, 174 and it also attempts to merge any new messages into the existing message 175 translations found in the `messages` directory. Such translation files 176 have the following form: 177 178 {{{ 179 messages/xx_XX.imip-agent.po 180 }}} 181 182 Here, `xx` is usually an [[WikiPedia:ISO_639-1|ISO 639-1]] language code, 183 whereas `XX` is usually an [[WikiPedia:ISO_3166-1|ISO 3166-1]] country code. 184 185 Translators should inspect and edit their files in the `messages` 186 directory and then use the `tools/i18n_format.sh` script to generate the 187 translations that the software will use: 188 189 {{{ 190 tools/i18n_format.sh 191 }}} 192 193 This installs the "compiled" translations into the `locale` directory in 194 a location of the following form: 195 196 {{{ 197 locale/xx_XX/LC_MESSAGES/imip-agent.mo 198 }}} 199 200 The `tools/install.sh` script will copy the `locale` directory into the 201 installation location unless the `--no-locale-dir` option is given. This is 202 provided to allow any centrally-installed translations to take precedence 203 over any locally-available translations.