"Fossies" - the Fresh Open Source Software Archive

Member "canopy-3.0.7/docs/Version.txt" (1 Nov 2019, 16926 Bytes) of package /linux/www/canopy-3.0.7.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Version Documentation
    2 by Matthew McNaney
    3 
    4 
    5 Version 1.5 Rewrote portions to conform to changes in the module
    6 Version 1.0 Initial draft
    7 
    8 Introduction
    9 ---------------------------------------------------------------------
   10 Version is module that assists with storing past 'versions' of your
   11 content. It also contains approval processing tools that work with
   12 item permissioning.
   13 
   14 
   15 Requirements
   16 ---------------------------------------------------------------------
   17 Version uses a data 'source'. This 'source' is what version bases its
   18 processes upon. Although your source can be an array of data, you may
   19 find it easier to use an object. Version accepts both.
   20 
   21 If you are using an object, the variables of it _must_ be identical to
   22 the column names of the table that contains it. So if your object
   23 looks like this:
   24 $this->name
   25 $this->address
   26 $this->city
   27 then your database table needs to look like:
   28 
   29 name |  address  |  city
   30 
   31 If your variables differ, then your source data should be an array. You
   32 can then load the values however you wish.
   33 
   34 The variable/table column "id" is _required_. Version expects to find
   35 an variable named "id" when processing your data. 
   36 
   37 If you are going to use the approval functionality, I suggest two
   38 columns on your items table - one to store the item's creator's id and
   39 an approval flag.
   40 
   41 The creator id will let you check if the current user is the original
   42 author. Usually you want to give this person access to an item
   43 regardless of group id settings.
   44 
   45 The approval column makes it easier to ignore unapproved items when
   46 building lists.
   47 
   48 To use the approval functionality, you should familiarize yourself
   49 with item permissioning under the User module: the basics of which
   50 will be covered in this documentation.
   51 
   52 
   53 Getting Started
   54 ---------------------------------------------------------------------
   55 Start by requiring the Version class once:
   56 
   57 PHPWS_Core::initModClass('version', 'Version.php');
   58 
   59 Version is not a static class. You will need to instantiate it.
   60 
   61 $version = & new Version('source_table');
   62 
   63 The "source_table" is the database table you use to store your source
   64 data.
   65 
   66 After instantiating the version, you need to set the source.
   67 
   68 $version->setSource($my_item);
   69 
   70 Again, $my_item can be an object or an array.
   71 
   72 Your item needs to have its id set.
   73 
   74 Important: make sure to set the source at the proper time. For
   75 example, this would be bad:
   76 
   77 $version->setSource($new_item);
   78 $new_id = $new_item->save();
   79 $new_item->id = $new_id;
   80 
   81 The reason this will cause a problem was because Version expects to
   82 find the current id of the source. If you are saving a new item,
   83 version needs that information. You could either place the setSource
   84 function call AFTER the $new_item was saved and filled in with its new
   85 id or you could call
   86 $version->setSourceId($new_id)
   87 afterwards.
   88 
   89 
   90 Unapproved vs. Approved
   91 ---------------------------------------------------------------------
   92 There are two states for a version: approved and unapproved.
   93 
   94 You will need to determine whether your item is approved or not.
   95 
   96 ( Note: You should be familiar with restricted and unrestricted
   97   users. If not, please read the Permissions.txt file.)
   98 
   99 An item should be approved if:
  100 1) an unrestricted user submited a new or updated item or
  101 2) an unrestricted user approved an unapproved version.
  102 
  103 An item is not approved if:
  104 1) a restricted user submited a new item or updated item
  105    or
  106 2) an unrestricted user edited an unapproved item, not approving it.
  107 
  108 So, when a new item is posted, you need to check these
  109 conditions. Here is an example:
  110 
  111 if (isset($_POST['version_id'])) {
  112 
  113    // If the version_id is set, then the previous form was editing an
  114    // unapproved version. Regardless of who submitted it, it is not 
  115    // approved yet. More below
  116 
  117    $my_item->approved = 0;
  118 
  119 } elseif(Current_User::isRestricted('blog')) {
  120 
  121    // The user is a restricted admin. They can create and edit
  122    // items but all submission require approval. approved is again 0
  123 
  124    $my_item->approved = 0;
  125 
  126 } else {
  127 
  128    // If this is not an edit of a version and the user is not
  129    // restricted, then this item is pre-approved. Set approval to 1
  130 
  131    $my_item->approved = 1;
  132 
  133 }
  134 
  135 The above covers a posting of an item. Approval of an item is covered
  136 further in the document.
  137 
  138 
  139 Editing the Unapproved
  140 ---------------------------------------------------------------------
  141 Restricted users can edit unapproved item more than once. The changes
  142 will not go into effect until the item is approved.
  143 
  144 When you are in your edit function, you need to check to see if there
  145 is an unapproved version.
  146 
  147 Create your version as normal:
  148 $version = & new Version('my_mod_table');
  149 
  150 // $my_item is the ORIGINAL item object.
  151 // We aren't editing it, but we need it to grab the unapproved
  152 // item
  153 $version->setSource($my_item);
  154 
  155 Now call the 'isWaitingApproval' function:
  156 
  157 $approval_id = $version->isWaitingApproval();
  158 
  159 If an integer is returned, then that is the id of the unapproved
  160 version. (Note: you can only have one unapproved version per item).
  161 Now you just need to load that version.
  162 
  163 You can create a new version by entering the id on the second
  164 construction parameter:
  165 
  166 $unapproved_version = & new Version('my_mod_table', $approve_id);
  167 
  168 or you can just reset the version that was in use:
  169 
  170 $version->setId($approval_id);
  171 $version->init();
  172 
  173 However you do it, you will now have a version that contains the item
  174 information that is awaiting approval. You can retrieve it two
  175 ways. If you just want an array of values:
  176 
  177 $my_items_data = $version->getSource();
  178 
  179 Alternately, you can give version your current object and have it fill
  180 in the information.
  181 
  182 $my_item = & new My_Item;
  183 $version->loadObject($my_item);
  184 
  185 Now you can edit the data however you want. Just make sure of one
  186 thing - you need to make sure you are keeping track of that version
  187 id. If you don't then each user edit will create a NEW version. You
  188 don't want that, you want them to continue editing the same
  189 version. Just pass the version id to your edit function if needed:
  190 
  191 My_Module::edit($my_item, $version_id);
  192 
  193 Then make sure to include it as a hidden variable in your form:
  194 
  195 function edit($my_item, $version_id=0) {
  196     $form = & new PHPWS_Form;
  197     $form->addHidden('module', 'my_module');
  198 
  199     if (isset($version_id)) {
  200        $form->addHidden('version_id', $version_id);
  201     }
  202 ...
  203 }
  204 
  205 Now, looking back to our conditional above:
  206 
  207 if (isset($_POST['version_id'])) {
  208    $my_item->approved = 0;
  209 }
  210 
  211 It doesn't matter whether the user was restricted or not. The version
  212 id enforces an unapproved status.
  213 
  214 Now we just save our version.
  215 
  216 Saving a version
  217 ---------------------------------------------------------------------
  218 When an approved version is saved, it is like making a backup. You can
  219 restore these backups later if you wish.
  220 
  221 An unapproved version isn't made active until it is approved by an
  222 administrator (more on that later).
  223 
  224 Here is an example of saving a version.
  225 First we decide if we need to save the item.
  226 
  227 if ($my_item->approved || !$my_item->id) {
  228      $my_item->save();      
  229 }
  230 
  231 What the above means is:
  232 1) if $my_item is currently approved, then save the object or
  233 2) if the $my_item does not have and id (i.e. it is new)
  234 then save the item.
  235 
  236 We must have a successful save of a new, unapproved item so Version
  237 will have an id to reference. The "approved" parameter makes sure that
  238 this version is not used by the module.
  239 
  240 If the item was not approved and has an id, then don't save it.
  241 
  242 Next we save the version itself.
  243 
  244 $version = & new Version('my_item_table');
  245 $version->setSource($my_item);
  246 $version->setApproved($my_item->approved);
  247 $version->save();
  248 
  249 
  250 Here is what we have accomplished:
  251 1) If the user is restricted and
  252    a) if the item is new, we create the item as unapproved and create
  253       a new version or
  254    b) if the item is an update of an approved item, we don't create a
  255       new item but we do create a new unapproved version or
  256    c) if the item is an update of an unapproved item, we don't save
  257       the item but we update the previous unapproved version, however
  258 2) if the user is unrestricted and
  259    a) if the item is new, we create the item and create a new approved
  260       version (a backup) or
  261    b) if the item is updated, we update the approved item and create a
  262       new approved version (a backup) or
  263    c) if the item is an unapproved version, we leave the item alone
  264       and update the unapproved version.
  265 
  266 I realize this is complex but it gets easier the more you use it.
  267 
  268 
  269 Creating an Approval List
  270 ---------------------------------------------------------------------
  271 Before I go into approving something, let me briefly cover the
  272 creating an unapprove list.
  273 
  274 There is a class in version that assists you with approval. It is
  275 named, oddly enough, Version_Approval.
  276 
  277 First, construct your approval object:
  278 
  279 $approval = & new Version_Approval('my_mod', 'my_mod_table');
  280 
  281 Next you need to create four links:
  282 
  283 $approval->setEditUrl('index.php?module=my_mod&command=edit_unapproved');
  284 // Edit link is not required, but very handy
  285 
  286 $approval->setViewUrl('index.php?module=my_mod&command=view_version');
  287 // Add this if you want an expanded view link. Not required.
  288 
  289 $approval->setApproveUrl('index.php?module=my_mod&command=approve_item');
  290 
  291 $approval->setDisapproveUrl('index.php?module=my_mod&command=disapprove_item');
  292 
  293 These links direct the administrator back to your module to edit,
  294 view, approve, or disapprove of the version.
  295 
  296 All that is left is receiving the list:
  297 $template['TITLE'] = 'Approval List for My Module';
  298 $template['LIST'] = $approval->getList();
  299 
  300 Layout::add(PHPWS_Template::process($template, 'my_mod',
  301             'approval_list.tpl');
  302 
  303 Approval will then list each item's database columns along with their
  304 values. The default template will show up to six columns, not counting
  305 the item's id.
  306 
  307 If you want to limit which columns are shown, then set the view limit
  308 before calling getList:
  309 
  310 $approval->setColumns('title', 'author');
  311 
  312 Now only the title and author columns will be shown.
  313 
  314 If you wish to create a more presentable approval list, you can name a
  315 function to call within your object.
  316 
  317 You need to construct your approval object differently:
  318 
  319 $approval = & new Version_Approval('my_mod', 'my_mod_table',
  320                                    'my_item_class', 'special_view');
  321 
  322 The third parameter is your item's class. When the unapproved items
  323 are pulled from the version table, they will be transformed into
  324 objects of this class. The fourth parameter is the method to call in
  325 your object. Therefore we expect a result from:
  326 
  327 $result = $my_item->special_view();
  328 
  329 The result will be shown instead of the basic table column
  330 information.
  331 
  332 
  333 Approving and Disapproving Items
  334 ---------------------------------------------------------------------
  335 Earlier, we had your set approval and disapproval links. Let's cover
  336 the process after those links are clicked.
  337 
  338 First of all, make sure you are checking the permissions of the user
  339 who clicked those links.
  340 
  341 if (!Current_User::isUnrestricted('my_mod')) {
  342     Current_User::disallow('Attempted to approve an item.');
  343     return;
  344 }
  345 
  346 The above code will prevent monkey business.
  347 
  348 Next, let's go over approval. Get the version id of the approved item
  349 and construction an object.
  350 
  351 $version = & new Version('my_mod', $_GET['version_id']);
  352 
  353 The version id is added automatically to the links you created in the
  354 approval list.
  355 
  356 Now we can use getSource (see beginning) to get the data from the
  357 version, but I am going to use an object:
  358 
  359 $my_item = & new my_mod_item;
  360 $version->loadObject($my_item);
  361 
  362 Now since the item is approved:
  363 $my_item->approved = 1;
  364 
  365 and save
  366 $my_item->save();
  367 
  368 Now the approved version has updated the old item. To finish up, we
  369 save an updated copy of the version:
  370 
  371 // Set the source because we changed the approval variable
  372 $version->setSource($my_item);
  373 
  374 // Version is now approved
  375 $version->setApproved(TRUE);
  376 
  377 $version->save();
  378 
  379 Now we have a backup version (see next section).
  380 
  381 Disapproving an item is much easier. Make the version just as before:
  382 
  383 $version = & new Version('my_mod', $_GET['version_id']);
  384 
  385 and delete it:
  386 
  387 $version->delete();
  388 
  389 If the item was new, the delete function will detect this and remove
  390 the source item for you.
  391 
  392 Note: because version cleans up the source item when the last version
  393 is deleted, you don't want to delete the only version of an item. If
  394 you must then call delete with FALSE as a parameter like so:
  395 
  396 $version->delete(FALSE);
  397 
  398 
  399 Creator Permission
  400 -------------------------------------------------------------------
  401 After approving a new item, you may want to give the creator
  402 permission to edit their item. As long as the item has a key, this is
  403 simple. 
  404 
  405 $key = & new Key($my_item->key_id);
  406 $version->authorizeCreator($key);
  407 
  408 The authorizeCreator function will grab the creator id from the
  409 version and give item level permissions based on the key data.
  410 
  411 You should only call this authorizeCreator after an item has been
  412 approved. You won't save a key until afterwards.
  413 
  414 You may want to give a creator access to your item before it is
  415 approved. In that case, you should just check the current user against
  416 the creator. 
  417 
  418 if (Current_User::isUser($my_item->creator_id)) {
  419    let_user_see_edit_link();
  420 }
  421 
  422 This is why we recommend you store the creator id with your item.
  423 
  424 If you are working on the version, you could also do this:
  425 
  426 if (Current_User::isUser($version->getCreator())) {
  427    let_user_see_edit_link();
  428 }
  429 
  430 
  431 
  432 Accessing Unapproved Versions Externally
  433 --------------------------------------------------------------------
  434 Usually, the preceding information should be enough to allow version
  435 approval. There may be a time when you need to access unapproved
  436 versions on your own.
  437 
  438 To grab a list of unapproved versions, create your approval object:
  439 $approval = & new Version_Approval('my_mod', 'my_mod_subtable');
  440 
  441 If you want to add a conditional to your query, use addWhere (see
  442 Database.txt for more information on the Database class). For example,
  443 say we need versions related to a parent object with an id of 5:
  444 
  445 $approval->addWhere('parent_id', 5);
  446 
  447 Now only versions with parent_id 5 will be pulled from the version
  448 table.
  449 
  450 Finally we call our get function:
  451 
  452 $subversions = $approval->get();
  453 
  454 Our "subversions" variable should have an array of unapproved
  455 versions. If "subversions" is NULL, then no results were found.
  456 
  457 
  458 
  459 Restore List
  460 ---------------------------------------------------------------------
  461 Each approved version of an item creates a backup. You can create an
  462 administrative panel in your module to restore those backups.
  463 
  464 Remember our approval list? The Restore list is almost identical.
  465 
  466 First we require our Restore class:
  467 
  468 PHPWS_Core::initModClass('version', 'Restore.php');
  469 
  470 Next, create your restore object:
  471 
  472 $restore = & new Version_Restore('my_mod', 'my_mod_table', 
  473                                  $my_mod->id, 'my_mod_class', 
  474                                  'special_view');
  475 
  476 It is almost identical, however notice the third variable is the id of
  477 our item. Just like the approval list contructor, the last two
  478 parameters are optional. Since we used it the special_view function
  479 with our approval list, we might as well use it here as well.
  480 
  481 We have two links to set:
  482 
  483 $restore->setRestoreUrl($restore_link);
  484 // This is the url to our module that will restore the version
  485 
  486 $restore->setRemoveUrl($remove_link);
  487 // This is the url to our module that will remove one of the old
  488 // versions
  489 
  490 Now we just call grab our list:
  491 
  492 $content = $restore->getList();
  493 
  494 Layout::add($content);
  495 
  496 
  497 Restoring or Removing a Version
  498 -----------------------------------------------------------------------
  499 Like approval, check to make sure the user has the proper
  500 permissions. Now the easy part:
  501 
  502 $version = & new Version('my_mod_table', $_GET['version_id']);
  503 $version->restore();
  504 
  505 That's it*. To remove a version, just delete it:
  506 
  507 $version->delete();
  508 
  509 * Note: Sometimes you may not want ALL of the version to restore. For
  510   example, if the restored item was in a specific order that has since
  511   changed, you don't want to force it into the same position. In such
  512   a case, edit a version object's "source_data" array before calling
  513   the restore function.
  514 
  515 
  516 
  517 Flushing Old Versions
  518 ---------------------------------------------------------------------
  519 If you want to remove all previous versions (unapproved or otherwise)
  520 you can just call the "flush" function like so:
  521 
  522 Version::flush('my_mod_table', $item_id);
  523 
  524 All previous versions will be removed from the database forever (be
  525 careful!). You should perform a flush after permanently deleting a
  526 version's source.
  527 
  528 
  529 Conclusion
  530 ---------------------------------------------------------------------
  531 That wraps up the documentation for the Version module. Although the
  532 module requires a little foresight and planning, utilizing it can save
  533 you time and effort.
  534 
  535 If you have any questions, please email us at phpwebsite at appstate
  536 dot edu.