Merge pull request #81 from NacreData/master

Update smart_links.rst

docs/topics/smart_links.rst

@@ -2,15 +2,15 @@
 Smart links
 ===========
 
+
 To configure: |Setup tab| |Right arrow| |Smart links button|
 
 To use: |Document icon| |Right arrow| |Smart links link|
 
 Smart links are usefull for navigation between documents.  They are rule
-based but don't created any organizational structure just show the documents
+based but don't create any organizational structure, just show the documents
 that match the rules as evaluated against the metadata of the currently
-displayed document.  They are global, the smart links are dependant
-on the current document the user is viewing.
+displayed document.  
 
 .. figure:: /_static/screenshots/smart_links_screenshot.png
    :alt: Smart links screenshot
@@ -20,6 +20,164 @@ on the current document the user is viewing.
    permit file number as the current document being viewed by the user.
    Notice how the current document is also highlighted with a black border.
    
+**Details**
+
+To create a Smart Link, a user with adequate permissions first clicks on the 
+"Settings" tab in the top menu, then click on the "Smart Links" button. The screen
+for creating a new (or editing an existing) Smart Link requires you to name the 
+Link and to ensure it is enabled if you wish to user it. Optionally, "Dynamic title"
+may be created. The Dynamic title is entended to contain references to attributes 
+of a document or it's metadata. Let's cover some simpler cases and come back to 
+dynamic references below. 
+
+*Static Links* 
+
+Smart links don't actually have to be overly smart. As a gentle introduction, lets
+create a simple "static" link which will show all the documents added in the year
+2014. We'll use the title "Added in 2014", leave the dynamic title empty, and ensure
+that "Enabled" is checked. 
+
+To have the link actually do something, we have to add one or more "condition". 
+Conditions are translated by the system into clauses in a query (search) of the 
+document database. There is a "Create condition" link in the right-bar of the Smart
+Link screen. For our simple case, the value of the "Inclusion" drop down does not 
+matter; we can leave it at the default "AND". For "Foreign document data" we will 
+enter:
+
+  document.date_added
+
+For "Operator" we will select "contains". 
+
+For "Expression" we will enter:
+
+  2014
+
+Underneath this field, "negated" should be unchecked and "enabled" should be checked. 
+Save the condition then go to the documents tab. Click on the filename of any file 
+listed there. Click on the "Smart link" tab under the submenu. A list of all 
+documents entered in 2014 (if any) should be shown. 
+
+There are a number of other document attributes which can be used in searches, with
+some important caveats: 
+
+* date_added: (discussed above)
+
+* comments: this is next to useless at present, since instead of searching through 
+  text of all comments you can instead search for the "id" of comments. 
+
+* description: enclose the text you want to search for in 'single' or "double" quotes.
+
+* document_type: can be used if Document Types have been defined and assigned to docs
+  as they have been uploaded. The search is performed against the "id" of the document_type 
+  and not against the textual description of the Document Type. This limitation,
+  however, is hidden if used in a dynamic link as demonstrated below. 
+  
+* documentcheckout: a meaningful query clause can be consructed by choosing this 
+  documnet attribute and testing if it "is equal to" 1 (for "true" or "is checked out")
+  or 0 (for "false" or "is not checked out")
+  
+* documentrenamecount: this attribute is reported by the system as available for 
+  searching but it's utility is not clear
+  
+* folderdocument: This attribute searches agains the "id" of the folder to which 
+  a document may have been added, not against the textual name of a folder and thus 
+  is useful primarily in dynamicly defined links (see below). 
+  
+* id: each document has a unique numeric id which can be used in searches
+
+* indexinstancenode: ??
+
+* metadata: ?? (see below) 
+
+* queuedocument: ??
+
+* recentdocument: this attibute appears to hold an integer (simple number like 1,2,3)
+  indicating the relative order in which documents were added to the system. This 
+  may be of some use for finding documents which were added before or after a given
+  document. 
+  
+* tagged_items: using this attribute by entering in an integer value appears to 
+  perform a search equivalent to "if document has at least one tag and this id number"
+  
+* tags: the "id" value of the corresponding tags are used. A tag will be matched if it
+  is alone or among several tags assigned to a document. 
+  
+* uuid: of little value, since these are by definition unique.
+
+* versions: ??
+
+
+You can also define Smart Links based on Metadata types and values which you have 
+defined. For this to work, it appears to be necessary to give the metadata type "Name" 
+(also known as "Internal name") which is all lowercase. The "Title" can be uppercase.
+
+For instance, if a metadata type is defined with these values:
+  Name: priority
+  Title: Priority
+  Default: 5
+  Lookup: (1,2,3,4,5,6,7,8,9,10)
+Then I can assign various documents different priorities and create a "Smart Link" 
+to find the high priority links by defining the condition as 
+  Inclusion: and 
+  Foreign document data: is greater or equal to
+  Expression: 5
+
+*Dynamic Smart Links*
+
+Links which are truly Smart are created by referencing the current value of the 
+document you are viewing and not a static value in at least one of the conditions.
+
+For instance, the last example above can be modified so that the Smart Link is:
+  Inclusion: and 
+  Foreign document data: is greater or equal to
+  Expression: metadata.priority
+  
+By including "metadata.priority" as the Expression instead of a static value, we 
+now have a Smart Link which will find all other documents with a Priority metadata
+value greater than or equal to the one we are viewing. 
+
+Here's an example by Mathias from the forums 
+(<https://groups.google.com/forum/#!topic/mayan-edms/nO5DFB1udhc>) which 
+demonstrates how to find other documents in the same project, if "project" has 
+been defined as a Metadata type. This example shows how to use the Dynamic Title 
+feature also.
+
+Title: Same project 
+Dynamic title: u'All documents of: %s' % getattr(metadata, 'project', 'None') 
+
+Condition: 
+Inclusion: and 
+Foreign document data: metadata.project 
+Operator: equal 
+Expression: metadata.project 
+
+The document attributes listed above which use the "id" value to do matching are
+more useful for dynamic than static conditions. For instance we can set both the
+foreign and current document Expressiong to "document.document_type" to get a 
+Smart Link to all other documents of the same Document Type as the current one. 
+
+*Combining Conditions*
+
+In theory we should be able to add multiple conditions and choose "and" or "or" 
+to define how they interact with the previous condition. There does not appear 
+to be a mechanism for defining parenthises to group conditions, but such subtleties
+are far beyond the current state of this funcitonality as even the simplest cases
+appear not to work. Defining to conditions, each of which yeild a set with 
+documents in common, and then combining them with "and" yeilds no documents at all.
+Switching to "or" returns the same documents multiple times. 
+
+*Tricky Smart Links*
+
+Advanced users can explore ways to use regular expressions in Smart Links. For 
+example, one might want easy access to documentation for software features not
+yet in production by using:
+
+Foreign document data: document.description
+Operator: is in regular expression (case insensitive)
+Expression: r'test|experimental|development'
+
+
+
 .. |Setup tab| image:: /_static/setup_tab.png
  :alt: Setup tab
  :align: middle