The Pincette jQuery plugin

Methods

Options

Components

Meta-data

Parameter Substitution

This jQuery plugin makes it possible to integrate the Pincette document management functionality in any web-site. It only uses WebDAV to communicate with a Pincette-server, which facilitates deployment on web-sites regardless of the technology they use. However, it will not work with just any WebDAV-server. Because of cross-domain requirements all WebDAV-calls are encoded in the GET-method using JSONP.

The plugin looks for its components within a given element and attaches behaviour to them (example). Several component sets may be active on a page. Their state is isolated which means they don't interfere with each other. The fact that the Pincette plugin doesn't work like a monolithic box makes it easier to integrate it in any conceivable layout and style.

Methods

init

This is the default method, i.e. when the plugin is called without giving it a method. The method initializes the components in finds in the given element. It has an options argument that may be omitted. The state object is associated with every component and can be retrieved through the jQuery function data with the key pincette.

The options argument may also be an array of objects. In this case each entry is supposed to have a rootUrl field. Entries with a more specific rootUrl will inherit missing fields from all entries that are less specific and above it. The URL-parameter path is used to select the most specific entry available. If the parameter is absent / will be assumed. This mechanism makes it possible to instantiate a page in many different ways, avoiding a see of pages.

Example:

(
  function($)
  {
    $(document).ready
    (
      function()
      {
        $('div.main').pincette
        (
          'init',
          {
            rootUrl: 'https://www.pincette.biz/',
            searchResultMaxHeight: true,
            searchUrl: 'https://www.pincette.biz/',
            uploadUrl: 'https://www.pincette.biz/upload.xml',
            fields:
              {
                dc_creator: {load: 'https://www.pincette.biz/meta/properties/'},
                dcterms_issued: {type: 'date'},
                re_keyword: {load: 'https://www.pincette.biz/meta/properties/'},
                Magazine: {load: false}
              },
            searchLimit: 100,
            sortDocuments: ['score', 'dc_title'],
            sortFolders: ['name']
          }
        );
      }
    )
  }
)(jQuery);

pickUrl

If you want to insert a link on a web-page which refers to a document in Pincette or perform any other operation with it, you can call this method. It will pop up a dialog box containing a kind of file chooser. The given element should have components that the init method can initialize (example). It doesn't alter the element itself, but works on a clone it makes instead.

When the user double-clicks on a document or presses OK when a document is selected, the callback onChoose will be called with a response object. This method expects an options object, which is the same as for the init method, but with the extra onChoose property.

Example:

$('.pincette-url-picker').pincette
(
  'pickUrl',
  {
    rootUrl: 'https://www.pincette.biz/',
    onChoose:
      function(response)
      {
        // Do something with response.
      }
  }
);

Options

allGroupsLabel (default: null)

When the search results are grouped per meta-data there will also be a folder that shows all results regardless of the meta-data. This option defines the label to use for that folder. See also the groupBy option.

afterLoadFolder (default: null)

This function is called after a folder has been loaded. It will receive two arguments. The first is the url that was loaded. The second is a state object.

builtInCommands (default: null)

When this array of command-names is present the list of built-in commands will be limited to it. The available commands are: check-in, check-out, copy, cut, delete, link, meta-data, mkcol, paste-document, paste-folder, relations, rename, send-mail, sharing-read, sharing-write, show-link, show-bindings, subscribe-rss, uncheck-out, upload-document, upload-folder, versions.

commands (default: [])

An array of commands that will be added to the menus which are attached to the folders and documents. A command is an object with the following properties:

action(response, state)

The function that is called when the command is triggered. It will receive two arguments. The first is the response object corresponding to the folder or map the command is triggered on. The second is a state object.

filter

With this object the command can be excluded for certain folders of documents. It has the following properties:

action(response, state, command): The function called when all other filter criteria pass. It should return true to include the command. The function receives three arguments. The first is the response object which corresponds to the folder or document. The second is a state object. The third is the command object itself.
filenamePattern: A regular expresssion that has to be matched by the URI-decoded path of the URL in the href property of the response object of the corresponding folder or document.
neededMethods: An array of HTTP-methods in capital letters, which means the command will only be selected for a resource if its supported-method-set WebDAV-property contains all of those methods.
resourceTypes: This is one of activity, collection, document, principal, version-history or view.
types: An array of MIME types. If the MIME type of the document is not in this array the command will be excluded.

label

The label of the command.

name

The technical name of the command.

privileges

The privileges the user should have for the corresponding folder of document. The command will be excluded if it has neither privileges nor parentPrivileges. It is also excluded if the user doesn't have the required privileges. The following privileges are available:

audit: Read audit information of the entire system. This is only defind for the root folder.
bind: Add a new name-binding to a resource within a folder.
checkin: Check in a folder or document.
checkout: Check out a folder or document.
delete-version: Delete a version of a folder or document.
label: Label a folder or document or a version of it.
read: Read the contents of a document of folder, i.e. the list of resources in it.
read-acl: Read the Access Control List of a folder or document.
read-current-user-privilege-set: Read the privileges the current user has for the folder or document.
unbind: Remove a name-binding to a resource within a folder.
uncheckout: Revert the check-out of a folder or document.
write-acl: Update the Access Control List of a folder or document.
write-content: Update the contents of a document.
write-properties: Update the WebDAV-properties of a document of folder.

parentPrivileges

The privileges the user need for the parent folder of the corresponding folder or document. For example, in order to be able to rename a document the user needs the bind and unbind privileges for the parent folder, because the existing name-binding will be replaced with a new name-binding.

defaultMediaType (default: null)

When a document is opended Pincette will try to convert it to this MIME type when it is set. If there is no conversion module in Pincette from the actual MIME type of the document to this one, the document will be returned in its original format.

displayResultEntry(response, parent, state, item) (default: null)

Set this callback if you want to override the default processing of folder and document response objects. The following arguments are passed to the callback:

response: A response object.
parent: The parent element to which the created element should be appended.
state: A state object.
item: If the parent element contains a template element, a clone of it is passed here.

extraSearchExpr (default: null)

This is a fixed search expression that is anded with the expression that corresponds with what the user has entered. It is a way to constrain the search space. The following example constraints the result set to three file formats:

extraSearchExpr:
  {
    op: 'or',
    expressions:
      [
        {field: 'getcontenttype', op: '=', value: 'application/xhtml+xml'},
        {field: 'getcontenttype', op: '=', value: 'application/pdf'},
        {field: 'getcontenttype', op: '=', value: 'text/plain'}
      ]
  }

fields (default: {})

Meta-data fields that need special attention can be configured here. This is useful when an advanced search form is on the page. You can set the type of a field, which may result in another widget for editing it or cause different sorting. At the moment only the types date, time and number are recognized. You can also specify whether the field should be preloaded or not and from which URL. This has to be a special Pincette URL that contains properties. The /meta/properties/ URL contains all properties and property values and is the most obvious URL to use. There is also the /meta/browse/<name1>/<value1>/<name2>/<value2>/ URL with which you can constrain the set of properties to those that occur together with the ones given in the URL. This is for more advanced situations.

Example (see meta-data section for the meaning of the fields):

fields:
  {
    dc_creator: {load: 'https://www.pincette.biz/meta/properties/'},
    dcterms_issued: {type: 'date'},
    re_keyword: {load: 'https://www.pincette.biz/meta/properties/'},
    Magazine: {load: false}
  }

groupBy (default: null)

This is a meta-data field by which the search results are grouped. For each meta-data value that occurs there will be an item in the pincette-folders component. See also the allGroupsLabel option.

help (default: null)

This is an object with two properties. The url property should refer to a help-file. The optional type property should contain the MIME type of the help-file.

initialUrl (default: rootUrl)

If this option is set the corresponding folder will be loaded during initialization. The preload option should also be set.

limitMetaFolders (default: null)

Pincette can contain many meta-data properties. When browsing the /meta/browse/ folder the list of properties can be limited with this array of meta-data names.

loadLimit (default: null)

With this option the number of documents that are shown when a folder is loaded can be limited. This is useful when there are many large folders, which may cause the browser to have difficulties rendering everything. When the option is not set all documents are always shown.

missingMetaDataProperty (default: null)

A boolean meta-data property that is set when a meta-data dialog box is saved while there are missing meta-data. This property can be used to search for documents that have missing meta-data.

openDocument(response) (default: null)

This callback lets you override what should happen when the user clicks on a document. The only argument is a response object.

preload (default: true)

Loads the folder set in the initialUrl option or the search based on the URL-parameter during initialization.

rootUrl (default: root URL of the page)

The URL set here will become the top-folder for browsing folders in the application.

searchLimit (default: 100)

Search results are retrieved in one pack and placed in the pincette-documents component, which scrolls when the default style is applied. Since the number of results can be quite large, the set can be limited with this option.

searchResultMaxHeight (default: false)

This is a convenience option that makes sure that the pincette-folders and pincette-documents components fill the remainder of the window. It is relevant only for a stand-alone deployment that doesn't have a footer. For other cases similar logic can be implemented with jQuery.

searchUrl (default: rootUrl)

In Pincette searches can be confined to a folder and everything under it. This way specific applications can be made. That is the purpose of this option.

shareWithGroupsOnly (default: false)

When set to true the sharing wizard will only list groups to share with. Otherwise the users will also be in the list.

showDetails(response, details, actionElement, state) (default: null)

Set this callback if you want another way of showing document details. The following arguments are passed:

response: The response object that corresponds to the document.
details: A clone of the pincette-details component.
actionElement: The element on which the show details action was triggered.
state: The state object.

showHidden (default: false)

When set to true hidden documents and folders are shown.

showUnreadable (default: false)

When set to true documents and folders for which the user has no read privilege are also shown when a folder is loaded.

sortDocuments (default: ['score', 'dc_title', 'name'])

The documents in a search result or in the contents of a folder can be sorted hierarchically according to the fields in this array. Besides meta-data names the names score and name are allowed. The former is the search score, the latter is the name of the document.

sortFolders (default: ['name'])

This works like the sortDocuments option, but the score and meta-data fields are not relevant for folders.

topIsPathParameter (default: false)

When this option is set and the path URL-parameter is present, then the rootUrl will be set to use it. This has the effect that when the user triggers the pincette-top-action the folder corresponding to the path will be loaded. This is useful in situations where the user doesn't have any access rights for higher folders. Clicking on Top would then yield an empty folder and nothing to go to.

uploadUrl (default: null)

When this URL is set the action menus may contain an upload item, depending on the access rights of the user. The URL in this option will receive the POST requests. It should be somewhere in Pincette. The contents of the file is actually a small Pincette form that look like this:

<?xml version='1.0' encoding='UTF-8'?>
<form xmlns="urn:be-re:forms">
  <action>be.re.repo.mod.Uploader.upload</action>
</form>

urlPicker (default: $('.pincette-url-picker'))

The element that will be used internally by certain functions.

useUrlParameters (default: true)

A search link can be distributed. It contains URL-parameters that are used to pre-fill search fields. It is also possible to preset the initial folder through the URL-parameter path. With this option you can decide whether any of this should happen or not. If the preload option is also turned on the search or folder load will be executed immediately.

Components

The components are elements the initialization will look for and attach behaviour to. They are distinguished purely by a class name. Components are optional though some central ones would be needed in order to have a useful deployment.

Besides the component class name an element's class attribute may also contain a path. It can't be used for styling purposes. Instead it is used to select the most specific occurrence of a component based on the rootUrl option. This can reduce the number of pages, because it allows to have several instances of the same page. So a component could be declared as follows:

<div class="pincette-advanced-search /home/">

The rest of this section enumerates the components by their class name.

pincette-add-list-index

When a long scrollable list is ordered alphabetically this component can be used to add a vertical index to it. All begin letters that occur in the list will appear in the index. When the user hits a letter the list will scroll to first entry that begins with it. The index appears at the right side and the letters will be evenly spread over the height of the list's view port. The index will not appear whenever the list is not ordered alphabetically.

The component should be placed on the element that contains the list entries. In the entry elements there should be an element with the class pincette-list-index-item. The text in this element is used to extract the begin letter. The following example shows a folder and document presentation where the document list has an index.

<div class="pincette-results">
  <div>
    <div class="pincette-folders">
       <div class="template">
         <div>$[name]&#160;<span class="pincette-checked-out" /></div>
         <div><span class="pincette-response-box-menu pincette-button
small grey">&#9662;</span><span class="icon">&#5171;</span></div>
      </div>
    </div>
  </div>
  <div>
    <div class="pincette-documents pincette-add-list-index">
      <div class="template">
        <div class="pincette-preview">$[preview]</div>
        <div class="info">
          <p class="title
pincette-list-index-item">$[dc_title:-$name]&#160;<span
class="pincette-checked-out" /><span class="pincette-missing-meta-data" /></p>
          <p class="author">$[dc_creator]</p>
          <p class="details-block">
            <span class="pincette-show-details-action pincette-button
small grey">Details</span>
            <span class="pincette-response-box-menu pincette-button small
grey">&#9662;</span>
          </p>
        </div>
        <div class="description">
          <p><span class="score">$[score]</span>$[score?( &#8212;
)()]$[fragments:-$dcterms_abstract]</p>
          <p class="keywords">$[re_keywords]</p>
        </div>
      </div>
    </div>
  </div>
</div>

pincette-advanced-search

Search fields other than the full-text search field should be placed in this element. The element will be searched for input elements with the name attribute set to one of the meta-data names or application-specific meta-data names. If the element contains a tabular structure and if this structure has cells in which there is an element with the classes add or delete, logic will be applied that can duplicate and delete a row. This is useful when some fields can occur more than once in a search. Tabular structures are recognized via the display CSS property. An example:

<table class="pincette-advanced-search">
  <col span="1" />
  <col span="1" />
  <col span="1" />
  <tbody>
    <tr>
      <td rowspan="1" colspan="1">Author</td>
      <td rowspan="1" colspan="1"><input type="text"
name="dc_creator" size="40" /></td>
      <td class="add-delete" rowspan="1" colspan="1"><span
class="add">+</span><span class="delete">&#8211;</span></td>
    </tr>
    <tr>
      <td rowspan="1" colspan="1">Keyword</td>
      <td rowspan="1" colspan="1"><input type="text"
name="re_keyword" size="40" /></td>
      <td class="add-delete" rowspan="1" colspan="1"><span
class="add">+</span><span class="delete">&#8211;</span></td>
    </tr>
    <tr>
      <td rowspan="1" colspan="1">Date of appearance</td>
      <td colspan="2" rowspan="1">
        <input type="text" name="dcterms_issued" size="20" />
        <span style="padding-left: 1em; padding-right:
1em">until</span>
        <input type="text" name="dcterms_issued" size="20" />
      </td>
    </tr>
  </tbody>
</table>

pincette-advanced-search-action

This element will pop up the advanced search form in a dialog box.

pincette-back-action

The navigation history is maintained in the response object. This element lets the user go back one step in the history. An example:

<span class="pincette-back-action" />

pincette-bad-value

The class added to meta-data input elements that don't contain a valid value.

pincette-box-menu

This component is used together with the pincette-response-box-menu component. The latter causes a modal box to pop up instead of an ordinary menu. The box is supposed to have a template element, in which there should be an element with the class item. This is an example:

<div class="pincette-box-menu">
  <div class="pincette-title-bar">
    <div>
      <div class="pincette-button red close">Close</div>
    </div>
    <div>Actions</div>
    <div />
  </div>
  <div>
    <div>
      <div class="template">
        <div class="item" />
        <div class="arrow" />
      </div>
    </div>
  </div>
</div>

pincette-button

This is merely a style component. The contents of the element will be wrapped with two nested div elements, which allows the styling of 3D border effects. It will also attach a click handler that adds the class clicked for 500 milliseconds.

pincette-cancel-action

With this element the user can abort a running search. An example:

<button class="pincette-cancel-action" type="button">Cancel</button>

pincette-checked-out

This element is shown when a resource is checked out and hidden otherwise. See also the example in pincette-add-list-index.

pincette-check-in

When this element is present the check-in command will pop up a dialog box in which a comment can be entered for the new version. It should contain a textarea element. An example:

<div class="pincette-check-in">
  <div class="label">Comment</div>
  <div><textarea name="comment" rows="10" cols="40"/></div>
</div>

pincette-clear-action

With this element the user can clear all search fields. An example:

<button class="pincette-clear-action" type="button">Clear</button>

pincette-close

An element with this class is dynamically added to certain pop-ups. When clicked it will close the pop-up. Since the element can occur in various contexts and should always look the same a styling as follows is suggested:

.pincette-close
{
  background: url("../images/close.png") no-repeat !important;
  background-position: bottom left !important;
  cursor: pointer;
  display: block !important;
  height: 16px !important;
  margin: 0px !important;
  padding-right: 5px !important;
  padding-top: 5px !important;
  width: 16px !important;
}

pincette-confirmation-box

This component is used as a template for situations where confirmation has to be asked from the user. Any message that is to be displayed is appended to an element with the class text somewhere in the template. This is an example:

<div class="pincette-confirmation-box">
  <div class="text" />
  <div>
    <div class="ok pincette-button small grey">Yes</div>
    <div class="cancel pincette-button small grey">No</div>
  </div>
</div>

pincette-count

This element will be refreshed with the number of found documents. An example:

<span>Number of results: <span class="pincette-count" /></span>

pincette-details

This element is used to display the details of one document. Text in it is subjected to parameter substitution. An example:

<div class="pincette-details">
  <div>
    <div>
      <div class="label">Title</div>
      <div class="value">$[dc_title]</div>
    </div>
    <div>
      <div class="label">Name</div>
      <div class="value">$[name]</div>
    </div>
    <div>
      <div class="label">Author</div>
      <div class="value">$[dc_creator]</div>
    </div>
    <div>
      <div class="label">Keywords</div>
      <div class="value">$[re_keyword]</div>
    </div>
    <div>
      <div class="label">Abstract</div>
      <div class="value">$[dcterms_abstract]</div>
    </div>
  </div>
</div>

pincette-documents

The documents in a result set are added to this element. It may contain a template element that will be used to display each item in the result set. An example:

<div class="pincette-documents">
  <div class="template">
    <div class="pincette-preview">$[preview]</div>
    <div class="info">
      <p class="title">$[dc_title:-$name]</p>
      <p class="author">$[dc_creator]</p>
      <p class="details-block">
        <span class="pincette-show-details-action">Details</span>
        <span class="pincette-response-menu"><img
src="images/work.png" /></span>
      </p>
    </div>
    <div class="description">
      <p><span class="score">$[score]</span>$[score?(
&#8212; )()]$[fragments:-$dcterms_abstract]</p>
      <p class="keywords">$[re_keywords]</p>
    </div>
  </div>
</div>

pincette-field

This class is meant for input fields. When you set it the field will be wrapped with a span element with the class pincette-field-wrapper. Next to the input field a span element with the class clear is added. This element clear the input field when clicked and sets the class cleared on it. If the input field has a value for the alt attribute this value will be used as the hint when the input field is cleared.

pincette-folders

The folders in a result set are added to this element. It may contain a template element that will be used to display each item in the result set. An example:

<div class="pincette-folders">
   <div class="template">
     <div>$[name]<span class="pincette-response-menu"><img
src="images/work.png" /></span></div>
     <div><span class="icon" /></div>
  </div>
</div>

pincette-forms

The simple and advanced search forms may reside together in this element. This is not required, however. The state object will be initialized with this element when present, which provides quick access to the forms. The element is also used by the pincette-show-forms-action component.

pincette-forward-action

The navigation history is maintained in the response object. This element lets the user go forward one step in the history. An example:

<span class="pincette-forward-action" />

pincette-help-action

The user can open a help-file with this element if the help option is set. An example:

<span class="pincette-help-action" />

pincette-is-activity

This class is added to items in a result-list that correspond to activities. It can be used for styling.

pincette-is-collection

This class is added to items in a result-list that correspond to WebDAV-collections (folders). It can be used for styling.

pincette-is-document

This class is added to items in a result-list that correspond to documents. It can be used for styling.

pincette-is-principal

This class is added to items in a result-list that correspond to principals. It can be used for styling.

pincette-is-search-result

This class is added to items in a result-list that correspond to documents when a search has been performed. It can be used for styling. It will appear together with the pincette-is-document class.

pincette-is-version-history

This class is added to items in a result-list that correspond to version histories. It can be used for styling.

pincette-is-view

This class is added to items in a result-list that correspond to views. It can be used for styling.

pincette-loading

This element is shown when there is activity with the server and hidden otherwise. An example:

<span class="pincette-loading" />

pincette-message-box

This component is used as a template for situations where a message has to be shown to the user. Any message that is to be displayed is appended to an element with the class text somewhere in the template. This is an example:

<div class="pincette-message-box">
  <div class="pincette-title-bar">
    <div>
      <div class="ok pincette-button red close">Close</div>
    </div>
    <div />
    <div />
  </div>
  <div class="text" />
</div>

pincette-me-action

Clicking on this element will pop up the pincette-user box with the personal details.

pincette-meta-data

An element with this class is used in a dialog box to edit meta-data of a document. Its structure should be similar to the advanced search form element. Since the element is used in a dialog box its initial display type should be none. The input and textarea elements can have the class pincette-mandatory, which means the dialog box can't be committed until they have a value. When the user tries to commit the dialog box in this case, the fields with a missing value will receive the class pincette-missing-value. The fields that didn't pass validation get the class pincette-bad-value. This is an example:

<div class="pincette-meta-data">
  <div>
    <div>
      <div class="label">Identification</div>
      <div class="value">
        <input name="dc_identifier" type="text" size="30"
class="pincette-mandatory" />
      </div>
    </div>
    <div>
      <div class="label">Author</div>
      <div class="value">
        <input name="dc_creator" type="text" size="30" />
      </div>
      <div>
        <span class="add">+</span><span class="delete">&#8211;</span>
      </div>
    </div>
    <div>
      <div class="label">Issued</div>
      <div class="value">
        <input name="dcterms_issued" type="text" size="30" />
      </div>
    </div>
    <div>
      <div class="label">Keyword</div>
      <div class="value">
        <input name="re_keyword" type="text" size="30" />
      </div>
      <div>
        <span class="add">+</span><span class="delete">&#8211;</span>
      </div>
    </div>
    <div>
      <div class="label">Abstract</div>
      <div class="value">
        <textarea name="dcterms_abstract" rows="15" cols="40" />
      </div>
    </div>
  </div>
</div>

pincette-missing-meta-data

This element is shown when a document has missing meta-data and is hidden otherwise. The list of mandatory meta-data is extracted from the component pincette-meta-data. See also the example in pincette-add-list-index.

pincette-name-box

This component is used as a template for situations where the user has to enter a name. The input element should have the name name. As such this is a special kind of dialog box. This is an example:

<div class="pincette-name-box">
  <div class="pincette-title-bar">
    <div>
      <div class="cancel pincette-button red close">Close</div>
    </div>
    <div />
    <div>
      <div class="ok pincette-button red close">Done</div>
    </div>
  </div>
  <div class="label">Name</div>
  <div class="field">
    <input class="pincette-field" name="name" type="text" />
  </div>
</div>

pincette-navigation

This is the container for navigation elements such as the history actions, the current path and the top action. Those elements don't have to be in this container, but if it is present it is searched for a pincette-response-menu component that will carry the menu for the folder that is currently loaded. An example:

<div class="pincette-navigation">
  <div>
    <span class="pincette-top-action">Top</span>
    <span class="pincette-back-action" />
    <span class="pincette-forward-action" />
  </div>
  <div>
    <div class="pincette-path">
      <span class="template">
        <span class="name">$[name]</span>
        <span class="separator" />
      </span>
    </div>
    <span class="pincette-response-menu"><img src="images/work.png" /></span>
  </div>
</div>

pincette-path

This element displays the path of the current folder. If it contains a template element it will be used to represent each segment in the path. Each segment will also be active in the sense that the user can click on it to load that folder. An example:

<div class="pincette-path">
  <span class="template">
    <span class="name">$[name]</span>
    <span class="separator" />
  </span>
</div>

pincette-path-segment

This class is added to the elements that represent a path segment inside the element with the class pincette-path. Each clone of the template element will get this class.

pincette-preview

With this element the user can display a larger version of the preview by clicking on it. An example:

<div class="pincette-preview">$[preview]</div>

pincette-preview-box

When this component is present the pincette-preview action will pop up this component after adding an img element to it. This is an example:

<div class="pincette-preview-box" />

pincette-response-box-menu

This component works like the pincette-response-menu component, but it pops up a modal box instead of a menu.

pincette-response-menu

This element will get a menu attached to it. The menu will act on the corresponding response object of a document or folder. The presence of menu-items is determined by command-filters, privileges and parentPrivileges. If there is no menu-item that qualifies the whole element will be hidden. An example:

<span class="pincette-response-menu"><img src="images/work.png" /></span>

pincette-search-action

This element triggers a search. It will typically be a button. An example:

<button class="pincette-search-action" type="button">Search</button>

pincette-sharing

If this element is present the internal sharing command will be available. It expects to find the elements with classes read and write. In those there should be a select element for the principals that currently have the respective privilege, an input element that is used for all the principals and two elements with the classes up and down, which are used to add or remove principals from the selected list. Since this element is used in a dialog box its initial display type should be none. This is an example:

<div class="pincette-sharing">
  <div>
    <div class="read">
      <p>Read</p>
      <div>
        <select name="selected" multiple="true" size="10" />
      </div>
      <div class="arrows"><span class="up" /><span class="down" /></div>
      <div>
        <input name="principals" type="text" />
      </div>
    </div>
    <div class="write">
      <p>Write</p>
      <div>
        <select name="selected" multiple="true" size="10" />
      </div>
      <div class="arrows"><span class="up" /><span class="down" /></div>
      <div>
        <input name="principals" type="text" />
      </div>
    </div>
  </div>
</div>

pincette-show-details-action

This element will cause the details of a document to be displayed when clicked on. An example:

<span class="pincette-show-details-action">Details</span>

pincette-show-form-action

With this element the user can show or hide the pincette-forms component. An example:

<span class="pincette-show-form-action" />

pincette-show-search-url-action

When the user clicks on this element a box will pop up containing the search URL of the last search. It can be copied and distributed to other users. An example:

<span class="pincette-show-search-url-action">Search link</span>

pincette-simple-search

The simple search form is for full-text searches. The query is built with the input element that has the name contains. Three additional input elements may be present with the following names:

abstract: A checkbox that adds document abstracts as search targets.
contents: A checkbox that adds the document contents as a search target.
title: A checkbox that adds document titles as search targets.

At least the contents input element should be present, otherwise there is no search target at all. These input elements may be hidden. An example:

<div class="pincette-simple-search">
  <p><input type="text" name="contains" size="60" /></p>
  <p>
    <span style="white-space: nowrap">
      <input type="checkbox" name="contents" checked="true" />
      <span style="padding-right: 2em"> Inhoud</span>
      <input type="checkbox" name="title" checked="true" />
      <span style="padding-right: 2em"> Titel</span>
      <input type="checkbox" name="abstract" checked="true" />
      <span style="padding-right: 2em"> Samenvatting</span>
    </span>
  </p>
</div>

pincette-sort

This component contains a list of entries with the class pincette-sort-criterion. When clicked the loaded document list will be sorted according to the chosen criterion. The class attribute should also have the name of the criterion between square brackets. When the name is preceded by an exclamation mark a descending order is generated. The name normal is used for the natural sorting of the list. The name getlastmodified corresponds to the WebDAV-property with the same name and indicates the moment the document was last modified. All the meta-data names are also allowed. Here is an example:

<div class="pincette-sort">
  <div class="pincette-title-bar">
    <div>
      <div class="cancel pincette-button red close">Close</div>
    </div>
    <div>Sort criterion</div>
    <div />
  </div>
  <div class="body">
    <div class="pincette-sort-criterion [normal]">Normal</div>
    <div class="pincette-sort-criterion [getlastmodified]">&#8593; Last
modified</div>
    <div class="pincette-sort-criterion [!getlastmodified]">&#8595; Last
modified</div>
  </div>
</div>

pincette-sort-action

Clicking on this element will pop up the pincette-sort box.

pincette-title-bar

This component is useful at the top of modal boxes. If the element contains an element with class close, then the close function will be attached to it. The following example show a dialog box where the ok and cancel buttons both have the close functionality.

<div class="pincette-name-box">
  <div class="pincette-title-bar">
    <div>
      <div class="cancel pincette-button red close">Close</div>
    </div>
    <div />
    <div>
      <div class="ok pincette-button red close">Done</div>
    </div>
  </div>
  <div class="label">Name</div>
  <div class="field">
    <input class="pincette-field" name="name" type="text" />
  </div>
</div>

pincette-top-action

When the user clicks on this element the folder set in the rootUrl option is loaded. An example:

<span class="pincette-top-action">Top</span>

pincette-upload

This component is used for uploading files. It should have an input element of type file and with the name files[]. Optionally it can also contain an input element of type checkbox and with a name composed as type:<MIME type>. In this case Pincette will attempt to convert the uploaded document to the target type if such a transformer is configured in Pincette.

The component should also have an element with the class files. In there, for each uploading file an entry will be created with the following form:

<div class="pincette-upload-entry">
  <div class="filename"><name of the file></div>
  <div class="progress">
    <div class="progress-bar">
      <div class="bar"><div/></div>
    </div>
    <div class="control">
      <div><span class="cancel"/></div>
    </div>
  </div>
</div>

The div element within the one with the class bar will see its width evolve from 0 to 100%.

This is an example of the upload component:

<div class="pincette-upload">
  <div class="pincette-title-bar">
    <div>
      <div class="pincette-button red close">Close</div>
    </div>
    <div />
    <div />
  </div>
  <div class="files">
    <input type="file" name="files[]" value=" " />
    <span>As PDF: </span>
    <input type="checkbox" name="type:application/pdf" />
  </div>
</div>

pincette-user

This component is a dialog box to modify details of a user. It should have input elements with the names displayname, which is the human-readable name, email, password and again. The latter two should of type password. The input elements are all optional.

pincette-versions

This element is used as a pop-up to show the versions of a document or folder. The versions in a result set are added to it. It may contain a template element that will be used to display each item in the result set. Its initial display type should be none. This is an example:

<div class="pincette-versions">
  <div>
    <div class="template">
      <div>$[getlastmodified]</div>
      <div>$[creator-displayname]</div>
      <div>$[comment]</div>
    </div>
  </div>
</div>

Meta-data

There are three kinds of meta-data names: those defined in DublinCore, names specific to Pincette and free names, which users have added to the /meta/properties/ folder in Pincette.

DublinCore

dc_contributor

dc_coverage

dc_creator

dc_date

dc_description

dc_format

dc_identifier

dc_language

dc_publisher

dc_relation

dc_rights

dc_source

dc_subject

dc_title

dc_type

dcterms_abstract

dcterms_accessRights

dcterms_accrualMethod

dcterms_accrualPeriodicity

dcterms_accrualPolicy

dcterms_alternative

dcterms_audience

dcterms_available

dcterms_bibliographicCitation

dcterms_conformsTo

dcterms_created

dcterms_dateAccepted

dcterms_dateCopyrighted

dcterms_dateSubmitted

dcterms_educationLevel

dcterms_extent

dcterms_hasFormat

dcterms_hasPart

dcterms_hasVersion

dcterms_instructionalMethod

dcterms_isFormatOf

dcterms_isPartOf

dcterms_isReferencedBy

dcterms_isReplacedBy

dcterms_isRequiredBy

dcterms_issued

dcterms_isVersionOf

dcterms_license

dcterms_mediator

dcterms_medium

dcterms_modified

dcterms_provenance

dcterms_references

dcterms_replaces

dcterms_requires

dcterms_rightsHolder

dcterms_spatial

dcterms_tableOfContents

dcterms_temporal

dcterms_valid

Pincette

re_company

re_keyword

re_manager

re_status

Parameter Substitution

Some elements may contain parameters that refer to information in response objects. They will be replaced with the values in those objects. Besides meta-data names the following names are allowed:

href: The URL of a document or folder.
name: The name of a document or folder.
preview: The preview of a document or folder. This parameter will be replaced with an img element.
score: The full-text search score of a document.

Parameters that are not available in the response object are discarded. This is the parameter syntax:

$[name]: Replaces the parameter with the value of the response property name.
$[name:-value]: Uses the value of the name parameter if available or value instead.
$[name1:-name2]: Uses the value of name1 if available or name2 instead if available. Otherwise the parameter is discarded.
$[name?(value1)(value2)]: If name is available use value1 and value2 otherwise.

The Response Object

The response object always corresponds to a document or a folder. It contains information retrieved from the server. The following properties are available:

acl

An array of access control entries with the following properties:

grant: A boolean indicating if the privilege is granted or denied.
principal: A Principal object.
privilege: An object representing the privilege. It has the properties localName and namespaceURI.
protected: A boolean indicating whether the entry may be modified or not.

checkedOut

Indicates whether the resource is checked out or not.

errors

An array of objects that represent errors for properties that couldn't be fetched. The properties in the objects are:

error: The WebDAV error element as a DOM-tree.
message: The error message.
prop: The qualified name of the property, which is an object with the properties namespaceURI and localName.
status: The status code for the property.

getcontenttype

The MIME type of the document.

fragments

An snippet of text that represents search fragments. The terms are surrounded with a span element with the class term.

href

The absolute URL of the resource.

isCollection

A boolean indicating if the resource is a WebDAV-collection or not.

name

The name of the resource. It is URI-decoded.

meta

An object that maps meta-data names to arrays of values.

previews

An array of objects with the following properties:

height: The height in pixels of the preview.
href: The URL of the preview.
stableHref: An absolute URL for the preview that doesn't change. It is only set if the document has the meta-data property dc_identifier.
mimeType: The MIME type of the preview.
width: The width in pixels of the preview.

privileges

An array of WebDAV privilege names. The local name of a privilege element is used here.

referredBy

An array of objects with two properties: the relation name and the href, which is a document or folder URL.

referredByVersions

An array of objects with two properties: the relation name and the href, which is a version URL.

referringTo

An array of objects with two properties: the relation name and the href, which is a document or folder URL.

resourceTypes

An array of resource type names.

stableHref

An absolute URL for the document that doesn't change. It is only set if the document has the meta-data property dc_identifier.

The State Object

The state object contains some internal management data such as the navigation history, activity with the server, etc. It also has a property for each component that was found during initialization. The value of such a property is a jQuery object representing the element in the document. The names of the properties are constructed with the component names. The pincette- prefix is stripped. The remainder is used to create a mixed-case name. For example, for the component pincette-simple-search the name of the property becomes simpleSearch.

Properties

dav: A WebDAV client object.
options: The options object passed during initialization.

Methods

abortSearch(): Aborts a running search.
addActivity(): Adds an activity to the activity indicator. If there was no activity yet the indicator is shown.
getGroups(done): Retrieves the user groups from the server. They are loaded only once. The done argument is a function that is called with the array of groups sorted in a case-insensitive manner.
getUsers(done): Retrieves the users from the server. They are loaded only once. The done argument is a function that is called with the array of users sorted in a case-insensitive manner.
refresh(url, success, failure): Gets the properties of one document or folder. The first argument is the URL. The second and third are the multi-status callbacks.
removeActivity(): Removes an activity from the activity indicator. If there are no more activities left the indicator will be hidden.

Template Elements

Template elements have the class template. The default style sheet makes sure they are not visible. Such elements can occur inside elements that will receive a dynamic list of things. For each item in the list a clone of the template element is made with the template class removed. The text in template elements is subjected to parameter substitution.

WebDAV Client

$.pincette.webdav.Client

All methods are asynchronous and return an XMLHttpRequest object.

new $.pincette.webdav.Client()

Constructs a new Client object.

acl(url, acl, success, failure)

Sets the Access Control List for the url argument.

bind(url, newBinding, success, failure)

Creates an additional binding to an existing resource. Afterwards both the URLs url and newBinding denote the same resource.

checkIn(url, success, failure)

Creates a new version of the document or folder.

checkOut(url, success, failure)

Checks out the document or folder. This prepares for a new version. Note that versioning for a resource may be set to automatic in which case an explicit check-out is not necessary unless you want to make a long-term reservation or if you know that a lot of updates will follow.

copy(source, destination, success, failure, multiSuccess, multiFailure, multiDone)

Copies a resource from the source URL to the destination URL. The URLs should be within the same server. The operation is completely handled by the server. The multiDone function is called when the response was a multi-status response and after all response entries were processed. The function has no arguments.

create(url, success, failure)

Creates a new resource on the server.

deleteUrl(url, success, failure)

Deletes a resource from the server.

get(url, success, failure)

Gets the contents of a resource. The contents is obtained via the success callback.

getAcl(url, success, failure)

Gets the Access Control List of the url. The function success is called with only the acl argument.

getMetaData(url, success, failure)

Gets the meta-data for the url argument.

getNames(collection, success, failure)

Gets the names of the resources in the collection denoted by the collection URL. The success function is called with only an array of names.

getPreviewSet(url, success, failure)

Gets the set of previews for the url argument.

getPrincipals(collection, success, failure)

Gets the list of principals from a principal collection denoted with the collection URL. This is either /groups/ or /users/. The success function is called with only an array of Principal objects.

getProperties(url, properties, success, failure)

Gets the properties for the url argument. The properties argument is an array of objects with the properties localName and namespaceURI.

getVersions(url, properties, success, failure, loaded)

The getVersions report for the url argument. The loaded function is called when all multi-status response entries have been processed. It has no arguments.

mkcol(url, success, failure)

Creates the collection denoted by url.

move(source, destination, success, failure, multiSuccess, multiFailure, multiDone)

Moves a resource from the source URL to the destination URL. The URLs should be within the same server. The operation is completely handled by the server. The multiDone function is called when the response was a multi-status response and after all response entries were processed. The function has no arguments.

propfind(url, properties, depth, includeCollection, success, failure, loaded)

This is the general method for retrieving properties in all circumstances. The arguments are the following:

url: The resource of which the properties are requested.
properties: An array of objects with the properties localName and namespaceURI. The various WebDAV specifications define which properties exist.
depth: A string indicating the number of levels that should be visited. The value "0" means that the properties are requested for only the url. With the value "1" the properties of the resources that are directly contained within url are added to this. The value "infinity" adds any level to the result.
includeCollection: Determines if the properties of url itself are included or not.
loaded(): This function is called without arguments after all properties have been fetched.

proppatch(url, properties, success, failure, done)

With this method the properties of the url argument can be updated. The properties argument is a response object. The done function is called after processing all multi-status responses. The function has no arguments.

rebind(url, newBinding, success, failure)

Replaces a binding to an existing resource. After this the URL url no longer exists, while the new URL newBinding is created.

report(url, body, depth, success, failure)

The low-level method for calling WebDAV-reports. The body is the XML document expressing the report request. The success and failure functions are either general or multi-status callbacks, depending on the response of the server. When the depth is not null the server is supposed to return a multi-status response.

runChain(done)

This method executes the WebDAV-operation chain that was recorded with the startChaining method. All operations are executed sequentially. At the end the done callback is called if present.

search(url, expressions, properties, success, failure, loaded)

The search report for the url argument. The loaded function is called when all multi-status response entries have been processed. It has no arguments. The expression object works with the following properties:

expressions: An array of subexpressions. It can be used in conjunction with the and and or operators.
field: The name of a field. It can be used in conjunction with the relational operators and the value property. A name is either a WebDAV name (the local name part), a meta-data name prefixed with meta. or the name contains, in which case only the = operator is allowed.
op: When the operator is or or and this property is combined with the expressions property, the contents of which are the operands for the operator. When the operator is a one of the relational operators <, >, <=, >=, = or != this property is combined with the field and value properties.
value: The value for an expression with a field property.

Expressions with the field contains are full-text queries. They should be either top-level expressions or a subexpression of a top-level and operator.

Example:

{
  op: 'and',
  expressions:
    [
      {field: 'contains', op: '=', value: 'some text'},
      {field: 'meta.dc_creator', op: '=', value: 'Me Myself and I'},
      {
        op: 'or',
        expressions:
          [
            {field: 'getcontenttype', op: '=', value: 'application/xhtml+xml'},
            {field: 'getcontenttype', op: '=', value: 'application/pdf'},
            {field: 'getcontenttype', op: '=', value: 'text/plain'}
          ]
      }
    ]
}

setDefaultFailure(failure)

The default failure callback that will be called when no failure callback was passed to a method.

startChaining()

Sometimes the result of a WebDAV-operation is needed before some action can be taken. Since the operations run asynchronously a callback is passed to them. However, if a rather long sequence of inter-dependent operations is needed the nesting of callbacks can be tedious. In such a case this method can be used. After it has been called the WebDAV-operations that follow are not executed immediately. Rather they are recorded in a chain. The runChain can be called at some point to execute and flush the recorded chain.

unbind(url, success, failure)

Removes a binding to a resource. The resource will be deleted when there are no other bindings left.

uncheckOut(url, success, failure)

Reverts a preceding check-out of a document or folder. All changes to the resource that were done when it was checked out are lost.

$.pincette.webdav.Principal

This object represents a user or a group.

new $.pincette.webdav.Principal(displayname, value)

Constructs a new Principal object. The displayname is a human-readable name. The value is either a URL, which refers to a user or a group, a property object with the properties localName and namespaceURI or one of the symbolic names all, authenticated and unauthenticated.

The arguments correspond to object properties with the same name.

toString()

Returns the displayname property.

Success and Failure Callbacks

These are general callbacks that are called at completion of a WebDAV-call to the server. They have the following signatures:

failure(status, text, method, headers): The arguments represent the status code, the text of either the response body or the exception, the method that was called, which makes it possible to do some generic error handling for several methods and the headers, which is an object with lower-case header names as keys and arrays as values.
success(status, responseText, headers): The arguments represent the status code, the text in the response body and the headers, which is an object with lower-case header names as keys and arrays as values.

Multi-status callbacks

Some methods process multi-status responses from the server, e.g. the propfind method. For each entry in the response the optional callbacks success and failure are called depending on the status code for the entry. In the argument list of a method success always comes before failure.

failure(href, status, method, error, responsedescription)

href: The URL of the document or folder.
status: The status code returned for the document of folder.
method: The method that was called.
error: An optional DOM-element containing error information.
responsedescription: An optional DOM-element containing a human-readable description of the response.

success(response)

The argument is a response object.

Script Files

The following script files should be loaded by the page in the given order:

jquery.min.js

jquery-ui.custom.min.js

jquery.fileupload.js

util.js

webdav.js

pincette.js

Demo

The URL below is a demo of the plugin. You can login with demo/demo.

https://demo.pincette.net/