Changeset 13172 for main/waeup.kofa/trunk/docs/source
- Timestamp:
- 16 Jul 2015, 05:30:14 (9 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
main/waeup.kofa/trunk/docs/source/userdocs/hostels.rst
r13171 r13172 4 4 ********************* 5 5 6 The accommodation sections is a built-in hostel management system. African universities usually run their own student hostels which are built on their huge university campuses. They combine the booking of beds with the registration process. There are two major use cases. Students either have to book a bed space before they can continue with the registration, or they are only allowed to book, if they have reached a certain registration state. In the first case, the university requires students to stay on campus. They usually have enough beds for all of their students and need to fill up the hostels. In the second case, bed space is limited. Since accommodation on campus is usually very reasonable and much safer than on the free market outside, students prefer to stay on campus. If bed allocation e.g. requires the payment of school fees, the university benefits from bed shortage, because students are forced to pay in order to get the highly coveted hostel bed. 7 8 From the database's point of view, the accommodation section is a container of type `HostelsContainer` with id ``hostels``, which is located in the `IUniversity` instance. It contains hostels (instances of `IHostel`) which again contain the beds (instances of `IBed`). 6 The accommodation sections is a built-in hostel management system. 7 African universities usually run their own student hostels which are 8 built on their huge university campuses. They combine the booking of 9 beds with the registration process. There are two major use cases. 10 Students either have to book a bed space before they can continue 11 with the registration, or they are only allowed to book, if they 12 have reached a certain registration state. In the first case, the 13 university requires students to stay on campus. They usually have 14 enough beds for all of their students and need to fill up the 15 hostels. In the second case, bed space is limited. Since 16 accommodation on campus is usually very reasonable and much safer 17 than on the free market outside, students prefer to stay on campus. 18 If bed allocation e.g. requires the payment of school fees, the 19 university benefits from bed shortage, because students are forced 20 to pay in order to get the highly coveted hostel bed. 21 22 From the database's point of view, the accommodation section is a 23 container of type `HostelsContainer` with id ``hostels``, which is 24 located in the `IUniversity` instance. It contains hostels 25 (instances of `IHostel`) which again contain the beds (instances of 26 `IBed`). 9 27 10 28 The :ref:`treelike storage of objects <object_database>` in the … … 24 42 ------------------- 25 43 26 The unique hostels container serves also as a configuration object. It defines for which academic session booking is enabled. The student's `current_session` must match the `accommodation_session`. It also defines the booking period and the registration workflow states for which booking is allowed, see :ref:`bed_tickets`. The only property attribute is `expired` which returns ``True`` if the current datetime is within the booking period. 44 The unique hostels container serves also as a configuration object. 45 It defines for which academic session booking is enabled. The 46 student's `current_session` must match the `accommodation_session`. 47 It also defines the booking period and the registration workflow 48 states for which booking is allowed, see :ref:`bed_tickets`. The 49 only property attribute is `expired` which returns ``True`` if the 50 current datetime is within the booking period. 27 51 28 52 .. literalinclude:: ../../../src/waeup/kofa/hostels/interfaces.py … … 32 56 --------- 33 57 34 The hostels container contains the various `Hostel` objects. Hostels are buildings with blocks, floors rooms and beds. When adding a hostel, the form page is requesting the hostel's name. The `hostel_id` is derived from the name by applying :code:`lower().replace(' ','-').replace('_','-')` to it. As usual, the id will be omitted in manage forms and can thus not be changed after hostel creation. 35 36 The add and manage form pages let us define the 'dimensions' of the hostel and and configure blocks with their assignment to either female or male students. And they are requesting the number of floors per block as well as the number of rooms per floor. All blocks have the same number of floors with a fixed number of rooms and a fixed number of beds per room. If beds or even entire rooms do not exist on a floor, these beds must be later marked reserved, so that they are skipped during the automatic allocation process, see below. 58 The hostels container contains the various `Hostel` objects. Hostels 59 are buildings with blocks, floors rooms and beds. When adding a 60 hostel, the form page is requesting the hostel's name. The 61 `hostel_id` is derived from the name by applying 62 :code:`lower().replace(' ','-').replace('_','-')` to it. As usual, 63 the id will be omitted in manage forms and can thus not be changed 64 after hostel creation. 65 66 The add and manage form pages let us define the 'dimensions' of the 67 hostel and and configure blocks with their assignment to either 68 female or male students. And they are requesting the number of 69 floors per block as well as the number of rooms per floor. All 70 blocks have the same number of floors with a fixed number of rooms 71 and a fixed number of beds per room. If beds or even entire rooms do 72 not exist on a floor, these beds must be later marked reserved, so 73 that they are skipped during the automatic allocation process, see 74 below. 37 75 38 76 .. note:: 39 77 40 Blocks for either female or male students? Does Kofa's hostel management accommodate girls and boys strictly separately? No, it doesn't. Blocks are not necessarily real buildings. They can be used as virtual subunits. If the entire hostel has only one block, then yes, either only female or only male students can be hosted in such a hostel. If two blocks are configured (one for male and one for female students), beds of the same room can be assigned to either the female or the male block, which means - even though very uncommon - girls and boys would be accommodated in the same room. 78 Blocks for either female or male students? Does Kofa's hostel 79 management accommodate girls and boys strictly separately? No, it 80 doesn't. Blocks are not necessarily real buildings. They can be used 81 as virtual subunits. If the entire hostel has only one block, then 82 yes, either only female or only male students can be hosted in such 83 a hostel. If two blocks are configured (one for male and one for 84 female students), beds of the same room can be assigned to either 85 the female or the male block, which means - even though very 86 uncommon - girls and boys would be accommodated in the same room. 41 87 42 88 .. literalinclude:: ../../../src/waeup/kofa/hostels/interfaces.py 43 89 :pyobject: IHostel 44 90 45 Beds can be dedicated to pre-study students, fresh students (`entry_session` and the hostels container's `accommodation_session` correspond), final-year students (`current_level` and the certificate's `end_level` correspond, or is even higher) and returning students (non-fresh and non-final-year students). Or they can be made bookable for all students (beds without category). The latter bed type can be configured but is not being used in the base package by :py:meth:`getAccommodationDetails<waeup.kofa.students.utils.StudentsUtils.getAccommodationDetails>`, the method which determines the appropriate bed type of the student. 46 47 Usually, not every student can be accommodated in every hostel. Faculties are sometimes far apart and do manage their own student hostels. These hostels require a 'special handling' in :py:meth:`getAccommodationDetails<waeup.kofa.students.utils.StudentsUtils.getAccommodationDetails>`. The special handling code must be set on the add and manage form pages of hostels. 48 49 The interface defines also two schema invariants (invariant-decorated methods). These methods validate one or more depending schema fields. In our case, the methods take care that blocks and beds are not assigned twice. 50 51 All the parameters above define the construction rules for beds when filling the hostel with beds, which is done by the `updateBeds` method described further below. 91 Beds can be dedicated to pre-study students, fresh students 92 (`entry_session` and the hostels container's `accommodation_session` 93 correspond), final-year students (`current_level` and the 94 certificate's `end_level` correspond, or is even higher) and 95 returning students (non-fresh and non-final-year students). Or they 96 can be made bookable for all students (beds without category). The 97 latter bed type can be configured but is not being used in the base 98 package by 99 :py:meth:`getAccommodationDetails<waeup.kofa.students.utils.StudentsUtils.getAccommodationDetails>`, 100 the method which determines the appropriate bed type of the 101 student. 102 103 Usually, not every student can be accommodated in every hostel. 104 Faculties are sometimes far apart and do manage their own student 105 hostels. These hostels require a 'special handling' in 106 :py:meth:`getAccommodationDetails<waeup.kofa.students.utils.StudentsUtils.getAccommodationDetails>`. 107 The special handling code must be set on the add and manage form 108 pages of hostels. 109 110 The interface defines also two schema invariants 111 (invariant-decorated methods). These methods validate one or more 112 depending schema fields. In our case, the methods take care that 113 blocks and beds are not assigned twice. 114 115 All the parameters above define the construction rules for beds when 116 filling the hostel with beds, which is done by the `updateBeds` 117 method described further below. 52 118 53 119 `IBed` … … 57 123 :pyobject: IBed 58 124 59 The `bed_id` contains the 'coordinates' of the bed. It tells us precisely in which hostel, in which block, on which floor and in which room the bed can be found. The bed id is composed as follows: ``[hostel id]_[block letter]_[room number]_[bed letter]``. The room number contains the floor level: :code:`room_nr = floor*100 + room`. Example: ``hall-1_A_101_C`` means that the bed is located in Hostel 1, Block A, 1st Floor, Room 101 (or 1) and labelled with 'C'. 60 61 The `bed_type` attribute is similarly being constructed. It describes which kind of student can be allocated: ``[special handling code]_[sex]_[stage]``. Example: ``regular_female_re`` means that this bed can be booked by regular female returning students. Other stages are: ``fr`` (fresh), ``pr`` (pre-study), ``fi`` (final-year) and ``all`` (all students). 125 The `bed_id` contains the 'coordinates' of the bed. It tells us 126 precisely in which hostel, in which block, on which floor and in 127 which room the bed can be found. The bed id is composed as follows: 128 ``[hostel id]_[block letter]_[room number]_[bed letter]``. The room 129 number contains the floor level: :code:`room_nr = floor*100 + room`. 130 Example: ``hall-1_A_101_C`` means that the bed is located in Hostel 131 1, Block A, 1st Floor, Room 101 (or 1) and labelled with 'C'. 132 133 The `bed_type` attribute is similarly being constructed. It 134 describes which kind of student can be allocated: ``[special 135 handling code]_[sex]_[stage]``. Example: ``regular_female_re`` means 136 that this bed can be booked by regular female returning students. 137 Other stages are: ``fr`` (fresh), ``pr`` (pre-study), ``fi`` 138 (final-year) and ``all`` (all students). 62 139 63 140 Beds of each hostel are consecutively numbered (`bed_number`). 64 141 65 Except for `owner`, all attributes of bed objects are being determined by the system, no matter if they are property or schema field attrributes. They can neither be edited nor imported (there is no batch processor for beds). The `owner` attribute contains the student id, if the bed is occupied. This attribute is either set by Kofa when the student creates a bed ticket (see :ref:`bed_tickets`), or can be set via the `BedManageFormPage`, see below. The `allowed_owners` schema invariant ensures (1) that the selected user exists, (2) that the student's current session corresponds with the accommodation session and (3) that the student doesn't reside in another bed. 142 Except for `owner`, all attributes of bed objects are being 143 determined by the system, no matter if they are property or schema 144 field attrributes. They can neither be edited nor imported (there is 145 no batch processor for beds). The `owner` attribute contains the 146 student id, if the bed is occupied. This attribute is either set by 147 Kofa when the student creates a bed ticket (see :ref:`bed_tickets`), 148 or can be set via the `BedManageFormPage`, see below. The 149 `allowed_owners` schema invariant ensures (1) that the selected user 150 exists, (2) that the student's current session corresponds with the 151 accommodation session and (3) that the student doesn't reside in 152 another bed. 66 153 67 154 Browser Pages … … 71 158 ----------- 72 159 73 Hostels are empty after creation and configuration. They do not contain any bed. The hostel's :py:meth:`Hostel.updateBeds<waeup.kofa.hostels.hostel.Hostel.updateBeds>` method must be called to fill the hostel with beds according to the hostel's configuration parameters. This is done by the same-named action of the `HostelManageFormPage`. `Hostel.updateBeds` iterates over all block letters, floor levels, room numbers and bed letters, which haven been configured on the `HostelManageFormPage`. In each bed letter iteration loop a bed is added and the `bed_id`, `bed type` as well as the consecutive `bed_number` are determined and stored with the bed. 74 75 As the method's name already promises, it does not only add beds to an empty hostel container, but also updates existing beds after re-configuration. It does this by removing all empty beds before the iteration starts. Occupied beds remain in the hostel but get the bed number ``9999``. When iterating over the newly configured blocks, floors, rooms and bed letters, Kofa checks first, if the bed belongs to the group of remaining beds, which could not be removed because they are occupied. If so, the bed type is adjusted and the bed number changed. The bed remains occupied by the same student, no matter if the student meets the newly configured conditions or not. 76 77 It might happen that e.g. a room for male students is converted into a room for female students, but a male student still resides in this room. This has to be checked and the student has to be relocated manually, see :ref:`student_relocation`. Moreover, due to the reconfiguration of the hostel, an occupied bed may no longer exist or offered for booking. This is then indicated by the bed number ``9999``. Also these students must be relocated manually. 160 Hostels are empty after creation and configuration. They do not 161 contain any bed. The hostel's 162 :py:meth:`Hostel.updateBeds<waeup.kofa.hostels.hostel.Hostel.updateBeds>` 163 method must be called to fill the hostel with beds according to 164 the hostel's configuration parameters. This is done by the 165 same-named action of the `HostelManageFormPage`. `Hostel.updateBeds` 166 iterates over all block letters, floor levels, room numbers and bed 167 letters, which haven been configured on the `HostelManageFormPage`. 168 In each bed letter iteration loop a bed is added and the `bed_id`, 169 `bed type` as well as the consecutive `bed_number` are determined 170 and stored with the bed. 171 172 As the method's name already promises, it does not only add beds to 173 an empty hostel container, but also updates existing beds after 174 re-configuration. It does this by removing all empty beds before the 175 iteration starts. Occupied beds remain in the hostel but get the bed 176 number ``9999``. When iterating over the newly configured blocks, 177 floors, rooms and bed letters, Kofa checks first, if the bed belongs 178 to the group of remaining beds, which could not be removed because 179 they are occupied. If so, the bed type is adjusted and the bed 180 number changed. The bed remains occupied by the same student, no 181 matter if the student meets the newly configured conditions or not. 182 183 It might happen that e.g. a room for male students is converted into 184 a room for female students, but a male student still resides in this 185 room. This has to be checked and the student has to be relocated 186 manually, see :ref:`student_relocation`. Moreover, due to the 187 reconfiguration of the hostel, an occupied bed may no longer exist 188 or offered for booking. This is then indicated by the bed number 189 ``9999``. Also these students must be relocated manually. 78 190 79 191 … … 81 193 ------------------- 82 194 83 Beds can be blocked by switching ther reservation status. The switch replaces the stage part of `bed_type` by ``_reserved``. Example: ``regular_female_re`` becomes ``regular_female_reserved``. Switching again, reverts this process. 84 85 Reserved beds won't be allocated automatically. The beds remains empty during the hostel booking period. Students can only be allocated manually to reserved beds, which is done via the `BedManageFormPage`, see below. 195 Beds can be blocked by switching ther reservation status. The switch 196 replaces the stage part of `bed_type` by ``_reserved``. Example: 197 ``regular_female_re`` becomes ``regular_female_reserved``. Switching 198 again, reverts this process. 199 200 Reserved beds won't be allocated automatically. The beds remains 201 empty during the hostel booking period. Students can only be 202 allocated manually to reserved beds, which is done via the 203 `BedManageFormPage`, see below. 86 204 87 205 Release Beds 88 206 ------------ 89 207 90 Releasing a bed does not simply mean clearing the `owner` attribute of the bed object. The student has to be notified that booking has been cancelled. This is done by replacing the `bed_coordinates` of the student's bed ticket. Instead of the coordinates, the student will read: ``-- booking cancelled on <datetime of cancellation> --``. 208 Releasing a bed does not simply mean clearing the `owner` attribute 209 of the bed object. The student has to be notified that booking has 210 been cancelled. This is done by replacing the `bed_coordinates` of 211 the student's bed ticket. Instead of the coordinates, the student 212 will read: ``-- booking cancelled on <datetime of cancellation> --``. 91 213 92 214 Manage Bed 93 215 ---------- 94 216 95 Not many things can be managed on this form page. As mentioned above, only the `owner` attribute can be changed by entering a student id. The id is being validated by a schema invariant. The manage form page cannot be accessed, if a student has aleady been allocated. Beds must be released first, before they can be allocated to other students. 217 Not many things can be managed on this form page. As mentioned above, 218 only the `owner` attribute can be changed by entering a student id. 219 The id is being validated by a schema invariant. The manage form 220 page cannot be accessed, if a student has aleady been allocated. 221 Beds must be released first, before they can be allocated to other 222 students.
Note: See TracChangeset for help on using the changeset viewer.
