1: <?php
  2: /**
  3:  * ClipIt - JuxtaLearn Web Space
  4:  * PHP version:     >= 5.2
  5:  * Creation date:   2013-10-10
  6:  * Last update:     $Date$
  7:  * @author          Pablo Llinás Arnaiz <pebs74@gmail.com>, URJC JuxtaLearn Team
  8:  * @version         $Version$
  9:  * @link            http://www.juxtalearn.eu
 10:  * @license         GNU Affero General Public License v3
 11:  * @package         ClipIt
 12:  * @subpackage      clipit_api
 13:  */
 14: 
 15: /**
 16:  * An extensible class which holds common functionality and properties for Resource objects such as Videos or
 17:  * Storyboards.
 18:  */
 19: abstract class ClipitResource extends UBItem {
 20:     /**
 21:      * @const string Elgg entity SUBTYPE for this class
 22:      */
 23:     const SUBTYPE = "ClipitResource";
 24:     const REL_RESOURCE_TAG = "ClipitResource-ClipitTag";
 25:     const REL_RESOURCE_LABEL = "ClipitResource-ClipitLabel";
 26:     const REL_RESOURCE_PERFORMANCE = "ClipitResource-ClipitPerformanceItem";
 27:     const REL_RESOURCE_USER = "ClipitResource-ClipitUser";
 28:     // Resource Container relationships
 29:     const REL_SITE_RESOURCE = "";
 30:     const REL_EXAMPLE_RESOURCE = "";
 31:     const REL_ACTIVITY_RESOURCE = "";
 32:     const REL_TRICKYTOPIC_RESOURCE = "";
 33:     const REL_TASK_RESOURCE = "";
 34:     const REL_GROUP_RESOURCE = "";
 35:     // Scopes
 36:     const SCOPE_GROUP = "group";
 37:     const SCOPE_ACTIVITY = "activity";
 38:     const SCOPE_SITE = "site";
 39:     const SCOPE_EXAMPLE = "example";
 40:     const SCOPE_TRICKYTOPIC = "tricky_topic";
 41:     const SCOPE_TASK = "task";
 42:     // Tagging
 43:     public $tag_array = array();
 44:     public $performance_item_array = array();
 45:     public $label_array = array();
 46:     public $read_array = array();
 47:     // Rating averages
 48:     public $overall_rating_average = 0.0;
 49:     public $tag_rating_average = 0.0;
 50:     public $performance_rating_average = 0.0;
 51: 
 52:     /**
 53:      * Loads object parameters stored in Elgg
 54:      *
 55:      * @param ElggEntity $elgg_entity Elgg Object to load parameters from.
 56:      */
 57:     protected function copy_from_elgg($elgg_entity)
 58:     {
 59:         parent::copy_from_elgg($elgg_entity);
 60:         $this->tag_array = (array)static::get_tags($this->id);
 61:         $this->performance_item_array = (array)static::get_performance_items($this->id);
 62:         $this->label_array = (array)static::get_labels($this->id);
 63:         $this->read_array = (array)static::get_read_array($this->id);
 64:         $this->overall_rating_average = (float)$elgg_entity->get("overall_rating_average");
 65:         $this->tag_rating_average = (float)$elgg_entity->get("tag_rating_average");
 66:         $this->performance_rating_average = (float)$elgg_entity->get("performance_rating_average");
 67:     }
 68: 
 69:     /**
 70:      * Copy $this object parameters into an Elgg entity.
 71:      *
 72:      * @param ElggEntity $elgg_entity Elgg object instance to save $this to
 73:      */
 74:     protected function copy_to_elgg($elgg_entity)
 75:     {
 76:         parent::copy_to_elgg($elgg_entity);
 77:         $elgg_entity->set("overall_rating_average", (float)$this->overall_rating_average);
 78:         $elgg_entity->set("tag_rating_average", (float)$this->tag_rating_average);
 79:         $elgg_entity->set("performance_rating_average", (float)$this->performance_rating_average);
 80:     }
 81: 
 82:     /**
 83:      * Saves this instance to the system.
 84:      * @param  bool $double_save if $double_save is true, this object is saved twice to ensure that all properties are updated properly. E.g. the time created property can only beset on ElggObjects during an update. Defaults to false!
 85:      * @return bool|int Returns the Id of the saved instance, or false if error
 86:      */
 87:     protected function save($double_save = false)
 88:     {
 89:         parent::save($double_save);
 90:         static::set_tags($this->id, (array)$this->tag_array);
 91:         static::set_performance_items($this->id, (array)$this->performance_item_array);
 92:         static::set_labels($this->id, (array)$this->label_array);
 93:         static::set_read_array($this->id, $this->read_array);
 94:         return $this->id;
 95:     }
 96: 
 97:     /**
 98:      * Add Read Array for a Resource
 99:      *
100:      * @param int $id ID of the Resource
101:      * @param array $read_array Array of User IDs who have read the Resource
102:      *
103:      * @return bool True if OK, false if error
104:      */
105:     static function add_read_array($id, $read_array) {
106:         return UBCollection::add_items($id, $read_array, static::REL_RESOURCE_USER);
107:     }
108: 
109:     /**
110:      * Set Read Array for a Resource
111:      *
112:      * @param int $id ID of the Resource
113:      * @param array $read_array Array of User IDs who have read the Resource
114:      *
115:      * @return bool True if OK, false if error
116:      */
117:     static function set_read_array($id, $read_array) {
118:         return UBCollection::set_items($id, $read_array, static::REL_RESOURCE_USER);
119:     }
120: 
121:     /**
122:      * Remove Read Array for a Resource
123:      *
124:      * @param int $id ID of the Resource
125:      * @param array $read_array Array of User IDs who have read the Resource
126:      *
127:      * @return bool True if OK, false if error
128:      */
129:     static function remove_read_array($id, $read_array) {
130:         return UBCollection::remove_items($id, $read_array, static::REL_RESOURCE_USER);
131:     }
132: 
133:     /**
134:      * Get Read Array for a Resource
135:      *
136:      * @param int $id ID of the Resource
137:      *
138:      * @return static[] Array of Resource IDs
139:      */
140:     static function get_read_array($id) {
141:         return UBCollection::get_items($id, static::REL_RESOURCE_USER);
142:     }
143: 
144:     static function update_average_ratings($id)
145:     {
146:         $prop_value_array["overall_rating_average"] = (float)ClipitRating::get_average_rating_for_target($id);
147:         $prop_value_array["tag_rating_average"] = (float)ClipitTagRating::get_average_rating_for_target($id);
148:         $prop_value_array["performance_rating_average"] = (float)ClipitPerformanceRating::get_average_rating_for_target($id);
149:         return static::set_properties($id, $prop_value_array);
150:     }
151: 
152:     static function get_by_tags($tag_array)
153:     {
154:         $return_array = array();
155:         $all_items = static::get_all(0, 0, "", true, true); // Get only item ids, not objects
156:         foreach ($all_items as $item_id) {
157:             $item_tags = (array)static::get_tags((int)$item_id);
158:             foreach ($tag_array as $search_tag) {
159:                 if (array_search($search_tag, $item_tags) !== false) {
160:                     $return_array[(int)$item_id] = new static((int)$item_id);
161:                     break;
162:                 }
163:             }
164:         }
165:         return $return_array;
166:     }
167: 
168:     /**
169:      * Get all Tags from a Resource
170:      *
171:      * @param int $id Id of the Resource to get Tags from
172:      *
173:      * @return array|bool Returns an array of Tag IDs, or false if error
174:      */
175:     static function get_tags($id)
176:     {
177:         return UBCollection::get_items($id, static::REL_RESOURCE_TAG);
178:     }
179: 
180:     static function add_performance_items($id, $performance_item_array) {
181:         return UBCollection::add_items($id, $performance_item_array, static::REL_RESOURCE_PERFORMANCE);
182:     }
183:     static function set_performance_items($id, $performance_item_array) {
184:         return UBCollection::set_items($id, $performance_item_array, static::REL_RESOURCE_PERFORMANCE);
185:     }
186:     static function remove_performance_items($id, $performance_item_array) {
187:         return UBCollection::remove_items($id, $performance_item_array, static::REL_RESOURCE_PERFORMANCE);
188:     }
189:     static function get_performance_items($id) {
190:         return UBCollection::get_items($id, static::REL_RESOURCE_PERFORMANCE);
191:     }
192: 
193:     static function get_by_labels($label_array)
194:     {
195:         $return_array = array();
196:         $all_items = static::get_all(0, 0, "", true, true); // Get all item ids, not objects
197:         foreach ($all_items as $item_id) {
198:             $item_labels = (array)static::get_labels((int)$item_id);
199:             foreach ($label_array as $search_tag) {
200:                 if (array_search($search_tag, $item_labels) !== false) {
201:                     $return_array[(int)$item_id] = new static((int)$item_id);
202:                     break;
203:                 }
204:             }
205:         }
206:         return $return_array;
207:     }
208: 
209:     /**
210:      * Get Label Ids from a Resource.
211:      *
212:      * @param int $id Id of the Resource to get Labels from.
213:      *
214:      * @return array|bool Returns array of Label Ids, or false if error.
215:      */
216:     static function get_labels($id)
217:     {
218:         return UBCollection::get_items($id, static::REL_RESOURCE_LABEL);
219:     }
220: 
221:     /**
222:      * Add Labels to a Resource.
223:      *
224:      * @param int $id Id of the Resource to add Labels to.
225:      * @param array $label_array Array of Label Ids to add to the Resource.
226:      *
227:      * @return bool Returns true if added correctly, or false if error.
228:      */
229:     static function add_labels($id, $label_array)
230:     {
231:         return UBCollection::add_items($id, $label_array, static::REL_RESOURCE_LABEL);
232:     }
233: 
234:     /**
235:      * Remove Labels from a Resource.
236:      *
237:      * @param int $id Id of the Resource to remove Labels from.
238:      * @param array $label_array Array of Label Ids to remove from the Resource.
239:      *
240:      * @return bool Returns true if removed correctly, or false if error.
241:      */
242:     static function remove_labels($id, $label_array)
243:     {
244:         return UBCollection::remove_items($id, $label_array, static::REL_RESOURCE_LABEL);
245:     }
246: 
247:     /**
248:      * Set Labels to a Resource.
249:      *
250:      * @param int $id Id of the Resource to set Labels to.
251:      * @param array $label_array Array of Label Ids to set to the Resource.
252:      *
253:      * @return bool Returns true if added correctly, or false if error.
254:      */
255:     static function set_labels($id, $label_array)
256:     {
257:         return UBCollection::set_items($id, $label_array, static::REL_RESOURCE_LABEL);
258:     }
259: 
260:     static function get_scope($id)
261:     {
262:         $site = static::get_site($id, false);
263:         if (!empty($site)) {
264:             return static::SCOPE_SITE;
265:         }
266:         $example = static::get_example($id);
267:         if (!empty($example)) {
268:             return static::SCOPE_EXAMPLE;
269:         }
270:         $task = static::get_task($id);
271:         if (!empty($task)) {
272:             return static::SCOPE_TASK;
273:         }
274:         $group = static::get_group($id);
275:         if (!empty($group)) {
276:             return static::SCOPE_GROUP;
277:         }
278:         $activity = static::get_activity($id);
279:         if (!empty($activity)) {
280:             return static::SCOPE_ACTIVITY;
281:         }
282:         $tricky_topic = static::get_tricky_topic($id);
283:         if (!empty($tricky_topic)) {
284:             return static::SCOPE_TRICKYTOPIC;
285:         }
286:         return null;
287:     }
288: 
289:     static function get_site($id, $recursive = false)
290:     {
291:         $site_array = UBCollection::get_items($id, static::REL_SITE_RESOURCE, true);
292:         if (!empty($site_array)) {
293:             return array_pop($site_array);
294:         }
295:         if ($recursive) {
296:             $clone_array = static::get_clones($id, true);
297:             foreach ($clone_array as $clone_id) {
298:                 $site_array = UBCollection::get_items($clone_id, static::REL_SITE_RESOURCE, true);
299:                 if (!empty($site_array)) {
300:                     return array_pop($site_array);
301:                 }
302:             }
303:         }
304:         return null;
305:     }
306: 
307:     static function get_example($id)
308:     {
309:         $example = UBCollection::get_items($id, static::REL_EXAMPLE_RESOURCE, true);
310:         if (empty($example)) {
311:             return null;
312:         }
313:         return array_pop($example);
314:     }
315: 
316:     static function get_task($id)
317:     {
318:         $task = UBCollection::get_items($id, static::REL_TASK_RESOURCE, true);
319:         if (empty($task)) {
320:             return null;
321:         }
322:         return array_pop($task);
323:     }
324: 
325:     /**
326:      * Get the Group where a Resource is located
327:      *
328:      * @param int $id Resource ID
329:      *
330:      * @return int|null Returns the Group ID, or null if none.
331:      */
332:     static function get_group($id) {
333:         $resource = new static($id);
334:         if(!empty($resource->cloned_from)) {
335:             return static::get_group($resource->cloned_from);
336:         }
337:         $group = UBCollection::get_items($id, static::REL_GROUP_RESOURCE, true);
338:         if(empty($group)) {
339:             return null;
340:         }
341:         return (int)array_pop($group);
342:     }
343: 
344:     static function get_activity($id) {
345:         $group_id = static::get_group($id);
346:         if(!empty($group_id)) {
347:             return ClipitGroup::get_activity($group_id);
348:         } else {
349:             $activity = UBCollection::get_items($id, static::REL_ACTIVITY_RESOURCE, true);
350:             if(empty($activity)) {
351:                 return null;
352:             }
353:             return array_pop($activity);
354:         }
355:     }
356: 
357:     static function get_tricky_topic($id)
358:     {
359:         $activity_array = UBCollection::get_items($id, static::REL_TRICKYTOPIC_RESOURCE, true);
360:         if (empty($activity_array)) {
361:             return null;
362:         }
363:         return array_pop($activity_array);
364:     }
365: 
366:     /**
367:      * Adds Tags to a Resource, referenced by Id.
368:      *
369:      * @param int $id Id from the Resource to add Tags to
370:      * @param array $tag_array Array of Tag Ids to be added to the Resource
371:      *
372:      * @return bool Returns true if success, false if error
373:      */
374:     static function add_tags($id, $tag_array)
375:     {
376:         return UBCollection::add_items($id, $tag_array, static::REL_RESOURCE_TAG);
377:     }
378: 
379:     /**
380:      * Remove Tags from a Resource.
381:      *
382:      * @param int $id Id from Resource to remove Tags from
383:      * @param array $tag_array Array of Tag Ids to remove from Resource
384:      *
385:      * @return bool Returns true if success, false if error
386:      */
387:     static function remove_tags($id, $tag_array)
388:     {
389:         return UBCollection::remove_items($id, $tag_array, static::REL_RESOURCE_TAG);
390:     }
391: 
392: 
393:     /**
394:      * Get a list of Users who have Read a Resource, or optionally whether certain Users have read it
395:      *
396:      * @param int $id ID of the Resource
397:      * @param null|array $user_array List of User IDs - optional
398:      *
399:      * @return array[bool] Array with key => value: (int)user_id => (bool)read_status
400:      */
401:     static function get_read_status($id, $user_array = null)
402:     {
403:         $props = static::get_properties($id, array("read_array", "owner_id"));
404:         $read_array = $props["read_array"];
405:         $owner_id = $props["owner_id"];
406:         if (!$user_array) {
407:             return $read_array;
408:         } else {
409:             $return_array = array();
410:             foreach ($user_array as $user_id) {
411:                 if ((int)$user_id == (int)$owner_id || in_array($user_id, $read_array)) {
412:                     $return_array[$user_id] = true;
413:                 } else {
414:                     $return_array[$user_id] = false;
415:                 }
416:             }
417:             return $return_array;
418:         }
419:     }
420: 
421:     /**
422:      * Set the Read status for a Resource
423:      *
424:      * @param int $id ID of Resource
425:      * @param bool $read_value Read status value: true = read, false = unread
426:      * @param array $user_array Array of User IDs
427:      *
428:      * @return bool|int ID of Resource if Ok, false if error
429:      * @throws InvalidParameterException
430:      */
431:     static function set_read_status($id, $read_value, $user_array)
432:     {
433:         $read_array = static::get_read_array($id);
434:         $update_flag = false;
435:         foreach ($user_array as $user_id) {
436:             $index = array_search((int)$user_id, $read_array);
437:             if ($read_value === true && $index === false) {
438:                 array_push($read_array, $user_id);
439:                 $update_flag = true;
440:             } elseif ($read_value === false && $index !== false) {
441:                 array_splice($read_array, $index, 1);
442:                 $update_flag = true;
443:             }
444:         }
445:         if ($update_flag) {
446:             return static::set_read_array($id, $read_array);
447:         } else {
448:             return $id;
449:         }
450:     }
451: 
452: 
453: 
454:     /**
455:      * Sets Tags to a Resource, referenced by Id.
456:      *
457:      * @param int $id Id from the Resource to set Tags to
458:      * @param array $tag_array Array of Tag Ids to be set to the Resource
459:      *
460:      * @return bool Returns true if success, false if error
461:      */
462:     static function set_tags($id, $tag_array)
463:     {
464:         return UBCollection::set_items($id, $tag_array, static::REL_RESOURCE_TAG);
465:     }
466: 
467: }