Content-Item Controls (icon links to edit, delete, etc)

Each Content Item (such as a note, image, document or table) has a number of Control Icons attached to it.  The most common ones are:

• Edit  (to edit content or metadata)
• Delete
• Tag
• Move around the page - Up/Down/Top/Bottom
• Open in Single-Item View, on a separate tab
• Download
• View history

Common controls are made available to the individual plugins using methods provided by the pluginSupport class. 

Individual plugins are free to make use of those controls as they deem fit - though a uniform look is encouraged.

Some plugins also implement special controls; for example, the notes plugin (formatted HTML notes) also implements a revision (history) feature - and provides a control to access that feature.

EXAMPLE: outline of implementing a control in a plugin

The documents plugin (to store documents of any type, such as PDF or MS Word files), like all plugins, needs to provide a DELETE control.  All it has to do is:
 

1. Make a request to the pluginSupport class, which returns the control (HTML code, including graphs and links.)  The code for the request is:
              $this->pluginSupport->controlLinks_Delete($this->pluginCode, $docID, $categoryID);
    
2. Provide a method, with the standardized name of  deleteObject($objectID) , to carry out the actual deletion of the Content Item.  This method gets invoked by the control generated in step 1. 

NOTES

Every plugin is required to provide a set of standard methods to implement (its share of) the work to perform the actual actions of the various standard controls.  The Core module automatically takes care of the rest of the work. 

For example, the deleteObject($objectID) implemented by the  documents plugin takes care of deleting the actual document file, as well as deleting the record of that document kept by the plugin.  The higher-level method controlLinks_Delete, provided by the pluginSupport class, in addition to invoking the plugin-specific deleteObject method, also invokes methods provided by the Core module.  These methods take care of, for example, clearing records associated with general properties of the Content Item being deleted, such as its size and permissions.

In short: a lot of the work is done by the Core module, and accessed by individual plugins through the pluginSupport class.  This makes plugin implementation vastly easier.

Steps in Editing Metadata for a Document (outline)

1. The control icon by the document invokes JS function createDialogBox in viewer.php, with the last argument being the JS function populateEditMetadataBox
    
2. The JS function populateEditMetadataBox, in viewer.php, fetches from the server the HTML code to provide a way to edit the specified Content Item's metadata
    
3. The server gets contacted through the JS function fetchFromServer, in core.js, which uses the fetch API to contact userRequestsHandler.php
    
4. The call to  uses the following parameters:  plugin=cm&handler=editMetadata&mode=embed&itemType=d&itemID=1234  ,   where 1234 is the ID of the document in question.  The full server invocation is:    userRequestsHandler.php?plugin=cm&handler=editMetadata&mode=embed&itemType=d&itemID=1234
    
5. The "cm" specified in the above query string refers to the class contentManager (for now inside siteInitialization.php).   That's the class that provides the requested method handler_editMetadata (the "handler" prefix is implied.)
    
6. The method metadataEditor() in the document plugin is involved.  It fetches data about the document under consideration

Steps in the Addition of A New Content Item (Overview)

What happens when a user requests to add a new content item?  For example, when creating a note or a site link (annotated web bookmark)... or uploading a photo or document.

BRIEF SUMMARY FOR PLUGIN DEVELOPERS

Provide the following methods in your plugin class: handler_addContentModule() and  addObject() : 

1. handler_addContentModule() : assembles and returns HTML (typically a form) to let the user define the new content.
    
2. addObject() : takes care of the housekeeping operations involved in adding the new content item.  It must return the ID assigned the newly-added content item; in case of failure, the plugin is expected to throw an exception.

Plugins may either handle their own database tables (high-level API provided) or, as of version 3.1, take advantage of a new (RDF-style) triple store, which is strongly recommended.

EXAMPLES:   

If your plugin uses a form to create new content, you can copy and adapt, for example, the counterpart methods in the siteLinks plugin  (in the file plugins/siteLinks/siteLinks.php)   

If your plugin uploads files (such as photos or documents), see also  Uploading Content.

Detailed Steps in the Addition of A New Content Item

PART 1 - Letting the user specify what they want to add : CLIENT-SIDE, viewer.php

1. User clicks on one of the little circles with + signs,   , located in the controls below the various Content Items, as well as at the very top of the Category-viewer page (visible if the user has editing permission on that Category),
   In some cases (such as at the top of the Category-viewer) page, they are generated by the method controlLinks_AddItem() of the class pluginSupport , in the file plugins.php; in other cases, they are generated dynamically by the JavaScript function addItemList (defined in viewer.php).
    
2. Those icons are embedded within links of the form  <a href="javascript:addItemList(type, ID)"> </a> , where type (for example, "n") and ID (for example 12)  refer to the previous Content Item, i.e. the item (such as a note or image) immediately before the icon.  In case of insertions before the first item of the page (i.e. at the very top of the page), by convention type = ""
    
3. The addItemList JavaScript function (defined in viewer.php) toggles the visibility of the box used to add Content Items (initially hidden), if it already exists - or dynamically creates it otherwise
    
4. The content-addition box is a DIV element whose id is addItem_XYZ for some value XYZ,  where XYZ is of the form  "previousItemType_previousItemID" (e.g. "n_12"), or "0" if inserting at the very beginning of the page.  That ID value is used to uniquely identify the box to use, and it indirectly indicates the position (in the ordered list of Content Items attached to the current Category) after which to insert the new item
    
5. In some cases (such as at the top of the Category-viewer) page, the content-addition box is generated (in its initially-hidden state) in the PHP function contentAdditionBox (defined in viewer.php); in other case, it's generated dynamically by JavaScript.
    
6. For every Content Plugin that allows the addition of new content, there's a link to create or upload new content.  For example, for creating a new note:           
              <a href='javascript:addItem($addBlockID, \"n\")'>Create Note</a>      ("n" is the code for the "notes" plugin)
    
7. Most of those links invoke the JavaScript function  addItem , with the following arguments:
        * the ID of the content-addition box
        * the code identifying the plugin type
   
   HOWEVER, for a few plugins, the user is redirected to a specialized plugin page (e.g., the userTables and plots plugins do that), or to an alternate JavaScript function, addImmediateItem(), for Content Items that require no parameters at their creation (e.g. the clock plugin).
   The JavaScript function addImmediateItem() takes the following arguments:
        * the ID of the content-addition box
        * the code identifying the plugin type
        * the category ID

PART 2 - Specifying parameters to the newly-created Content Items (when applicable)

1. The JavaScript function  addItem creates and displays a dynamically-generated, plugin-provided DIV element (such as a form) that can be used to add a Content Item of the specified type at the requested position (order ID) on the page.
    
2. For more details on uploading files (such as documents or images), please see Uploading Content.   Here, we'll focus on Content Plugin that provide data-entry forms, such as the siteLinks (annotated web bookmarks) plugin.  In those cases, the JavaScript function  addItem replaces the original, generic "Add new content" box (for all plugin types) with one specific to the chosen plugin, with an actual data-entry form
    
3. The plugin-specific data-entry form, if applicable, is fetched from the server by the JavaScript function  obtainAddFormFromServer , which contacts ther server-side script pluginHandler.php using an  XMLHttpRequest() call

PART 3 - Letting the user specify what they want to add : SERVER-SIDE, pluginHandler.php

1. The plugin code and a method name ("addContentModule") are passed to the server-side script  pluginHandler.php , which dispatches the call to the appropriate plugin object (depending on the plugin code), and invokes a method called  handler_addContentModule()  in that plugin object
    
2. Every Content Plugin that provides a form to add new content, must include a method named   handler_addContentModule() 
    
3. Each  handler_addContentModule()  method must assemble and return an HTML form.  This form gets returned to the front-end   XMLHttpRequest() call, and back to the JavaScript function addItem , which inserts it in the page, in lieu of the original new-content addition box
    
4. The HTML form-generating function may opt to make use of the convenient formBuilder class (one of Brain Annex common modules)
    
5. No matter how the data-entry HTML form is generated, it must use the following script as a handler:  doAddContent.php?type=CODE  , where CODE is the plugin code.  The form must also pass hidden inputs for categoryID , order and redirect
    

PART 4 - Adding the new content specified by the user

1. The doAddContent.php is part of the core module.  The bulk of the work is done in the invocation of the method contentManager->addNewContentItem 
    
2. The addNewContentItem method (part of the contentManager class, for now hosted in the file siteInitialization.php) dispatches tasks to various housekeeping modules, such as permissions , resourceUsage and categories... and finally invokes the plugin-specific method addObject() , for the plugin that started the new content addition process.  This concludes the operations by the form handler.  The new Content Item is now created and appropriately catalogued - with most of the work done by the core modules, and just the bare minimun by the plugin itself!

Overview of the Steps in Uploading External Files (such as images or documents)

1. The content-presenting pages (for now viewer.php) offer pop-up boxes to add new content
    
2. The pop-up boxes offer a variety of links for the various types of content that the user may wish to add
    
3. Each link leads to an HTML form provided by the plugin for the requested type of content (for example, the "documents" plugin to upload new documents)
    
4. The front-end of the upload, including the drag-and-drop capabiltity and UI graphics, are handled by the dropzone software, while the back-end is taken care of by the  doAddContent.php script
    
5. The back-end upload script (doAddContent.php) contacts:
   a. the uploader module to take care of the actual upload
   b. the particular plugin in question to provide a name to save the file under
   c. the core module, to handle permissions, resource usage, setting the position of the uploaded item on the page, and to command the individual content-specific plugin to do its own management (such as maintaining a table of items and their metadata, creating thumbnails of uploaded images, etc.)

Detailed Steps

1. The main content viewer (for now, the Category-based viewer.php) instantiates the core module (aka the orchestrator module), which in turn initiates all plugins and other modules
    
2. The viewer page provides "+" clickable icons ("Add an item here").  Each of them has a unique ID, indicating the position on the page where to add the new Content (such as file uploads)
    
3. Clicking on one of those icons fires up the JavaScript function addItemList, with the position in the page passed as argument
    
4. The JavaScript function addItemList toggles the reveal/hide a box used to add Content Items.  The box's ID is addItem_n for some n, where n is the position on the page.  The reveal/hiding toggling is handled by the JavaScript function toggleBlockElement
    
5. The pop-up box to add Content Items is an HTML element created by the PHP function addBlock; it primarily contains HTML links (one per type of content item) that invoke JavaScript functions or PHP scripts
    
6. For the upload of external files (such as images, documents, audio, video), the JavaScript function is addItem, with 2 arguments: the ID of the pop-up box (representing the position in the page where to insert the new item) and the code for the plugin that handles that particular content type.  For example, for document upload, the involved plugin is "documents", with plugin code "d"
    
7. The JavaScript function addItem uses XMLHttpRequest to contact the pluginHandler.php script on the server.  Various arguments are passed, including the code for the plugin type (for example "d" for "documents") and the method to use, which for uploading is addContentModule
    
8. The pluginHandler.php script on the server receives the XMLHttpRequest, then selects the appropriate plugin (for example "documents") and invokes the passed method (addContentModule).   Each content plugin that provides file upload must implement method by that name: it generates and returns an HTM form to upload files specific to that plugin type
    
9. A string witth the above HTML form is returned to the server script (pluginHandler.php), and passed through XMLHttpRequest to the invoking JavaScript, which inserts the HTML form on the page
    
10. The forms for file uploads contain a <form> tag with class='dropzone' id='myDropzone_pluginCode' , where pluginCode varies by plugin.  The dropzone elements are used to interface with the dropzone software, which handles the front-end of the uploads, including the drag-and-drop graphics
     
11. The back-end of the uploads is handled by the doAddContent.php script.  It contacts the uploader module, which receives and processes the file just uploaded to the server.  The uploader also accepts a customizable function, named nameHandler, provided by the calling code in the doAddContent.php script
     
12. The above function, nameHandler, is where plugin-specific actions take place.  The nameMapping method of the plugin in question (for example, "documents") is invoked – the plugins decides what name to store the file under.  Next, the addNewContentItem method of the core module is invoked, with information about the just-uploaded file (such as its type, size and the original file name.)
     
13. The addNewContentItem method of the core module (in the file siteInitialization.php) performs various actions:
    a) enforcement, for example to make sure that the user isn't over their allotted storage quota (function isAddAllowed)
    b) it contacts the permissions module and categories module to set the permissions of the newly-uploaded content object (new uploads inherit the permissions of the Category they are uploaded into)
    c) it contacts the resourceUsage module to store the filesize
    d) it contacts the categories module to insert the new object in the specified position in the Category it was uploaded into
    e) it invokes the addObject method of the particular plugin in question, to let the plugin take care of accepting the uploaded content item.  Arguments passed include the metadata and the full name of the temporary file being used for the upload (e.g. "/tmp/phpE2qaT3") – since the upload process has not yet been completed
     
14. Examples of plugin-specific actions during uploads, performed by their addObject methods:
    A) The "images" plugin creates thumbnail versions of the uploaded images
    B) The "documents" plugin parses PDF documents, to extract the text inside them, page by page (useful for searches)
    C) Plugin-specific actions also include fairly general management, such as updating the plugin-maintained table to add the new item and its metadata (e.g. title or caption.)
     
15. If everything goes correctly, control is finally returned to the uploader module, and the upload is completed!

Overview of the Steps in Deleting Content

1. The content-presenting pages (for now viewer.php) offer clickable icons to delete content
    
2. The JavaScript function  doDeleteItem  is invoked, with the type and ID of the Content Item to delete
    
3. Highlight the Content Item slated to be deleted
    
4. Prompt the user for confirmation
    
5. If the deletion is confirmed, issue an AJAX call to the server, to the script   pluginHandler.php
    
6. ON THE SERVER SIDE:
   The script   pluginHandler.php  dispatches the deletion request to the method  doDeleteContentItem , provided by the class  contentManager (for now hosted in the file siteInitialization.php)
   It performs the following operations:
       A. Delete storage information about this object
       B. Let the appropriate plugin delete the given Content Item
       C. Remove all Tags that were attached to the deleted Content Item
       D. Delete from the permissions table
       E Delete triples with it this Content Item as subject
    
7. Upon completion of the AJAX call, update the page's DOM to eliminate the deleted Content Item