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 `markup.py` 65 || A Python library providing HTML generation support 66 == 67 `README.txt` 68 || Some basic documentation 69 == 70 `vCalendar.py` 71 ||<rowspan="3"> Handling of vCalendar and related data formats 72 == 73 `vContent.py` 74 == 75 `vRecurrence.py` 76 }}} 77 78 == Architectural Components == 79 80 The principal components of the software architecture are described below. 81 82 === vContent === 83 84 The v-prefixed libraries are concerned with the basic interpretation of 85 calendar-related data. For the most part, these libraries should already 86 behave in a predictable and reliable fashion and should not need much 87 further development. There are perhaps some deficiencies in the 88 `vRecurrence` module that are described on the 89 [[../CalendaringSupport|calendaring standards page]]. 90 91 It is not inconceivable that a `vCard` module be introduced in the future 92 to handle vCard data, thus enhancing the data about people within 93 imip-agent, perhaps also supporting mechanisms to obtain free/busy and 94 other information about scheduling participants. 95 96 === imiptools === 97 98 The bulk of the work done in imip-agent happens within `imiptools`. When 99 used from [[../AgentPrograms|agent programs]] launched by the mail system, 100 the different modules support the "handler" functionality that involves 101 obtaining information from calendar data, performing the necessary action 102 related to a scheduling method, and generating responses or notifications. 103 More details are given about these activities in the guide to 104 [[../IncomingMessages|incoming message handling]]. 105 106 When used from the [[../CalendarManager|management interface]], the 107 modules support the Web-based functionality as a more general calendar 108 system client, typically handling a single calendar object at any given 109 time. 110 111 The `imiptools.stores` package provides the basis for calendar data 112 persistence. From the very start, the nature of data organisation for 113 calendar users was centred on the storage of each user's free/busy records, 114 since the priority was to generate such records from messages exchanged 115 over e-mail, and the use of plain text files was chosen as the simplest 116 and most transparent approach. Beyond this, the need to retain calendar 117 objects arose, and thus a [[../FilesystemUsage|filesystem-based approach]] 118 was cultivated to manage such data. 119 120 In the future, other persistence mechanisms could be supported. However, 121 aside from performance concerns around access to free/busy schedules, 122 there may be no urgent need to adopt relational database technologies, 123 particularly as each user's data should remain isolated from that of 124 other users, and thus the volumes of data should remain relatively small 125 if managed well enough. 126 127 === imipweb === 128 129 Most of the `imipweb` package is concerned with the display of calendar 130 information as Web pages and the handling of submitted data over the Web 131 as users interact with those Web pages. The `imip_manager.py` file is 132 deployed as a [[https://tools.ietf.org/html/rfc3875|CGI]] program, and it 133 acts as a simple "switch" that shows the appropriate kind of Web page (or 134 "view") depending on the requested URL, delegating to one of the modules 135 within the `imipweb` package to do so: 136 137 || '''Module''' || '''View''' || 138 || `imipweb.calendar` || Calendar || 139 || `imipweb.event` || Individual events || 140 || `imipweb.profile` || User profile || 141 142 A general `imipweb.resource` module supports the different views with 143 common functionality. Useful abstractions for period and date information 144 are provided in the `imipweb.data` module. The CGI interfacing is defined 145 in the `imipweb.env` module. 146 147 One of the most awkward aspects of providing a Web interface to events is 148 the need to provide a comprehensive enough representation of period data 149 as expressed in calendar objects that can be held in a form defined in a 150 Web page, interpreted by the program, written back to the form, all 151 without losing information. 152 153 == Localisation == 154 155 The traditional [[https://www.gnu.org/s/gettext|gettext]] mechanisms for 156 translating labels, messages and other user-readable strings are employed 157 in the imip-agent code. Some tools have been provided to maintain this 158 localisation. 159 160 To extract "messages" from the code, run the `tools/i18n_messages.sh` 161 script: 162 163 {{{ 164 tools/i18n_messages.sh 165 }}} 166 167 This produces a file called `imip-agent.pot` in the current directory, 168 and it also attempts to merge any new messages into the existing message 169 translations found in the `messages` directory. Such translation files 170 have the following form: 171 172 {{{ 173 messages/xx_XX.imip-agent.po 174 }}} 175 176 Here, `xx` is usually an [[WikiPedia:ISO_639-1|ISO 639-1]] language code, 177 whereas `XX` is usually an [[WikiPedia:ISO_3166-1|ISO 3166-1]] country code. 178 179 Translators should inspect and edit their files in the `messages` 180 directory and then use the `tools/i18n_format.sh` script to generate the 181 translations that the software will use: 182 183 {{{ 184 tools/i18n_format.sh 185 }}} 186 187 This installs the "compiled" translations into the `locale` directory in 188 a location of the following form: 189 190 {{{ 191 locale/xx_XX/LC_MESSAGES/imip-agent.mo 192 }}} 193 194 The `tools/install.sh` script will copy the `locale` directory into the 195 installation location unless the `--no-locale-dir` option is given. This is 196 provided to allow any centrally-installed translations to take precedence 197 over any locally-available translations.