The Pincette jQuery plugin

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, for versions of Internet Explorer lower than 10 it will not work with just any WebDAV-server. Because of cross-domain issues with those browsers all WebDAV-calls are encoded in the GET-method using JSONP. For all other browsers the calls are plain WebDAV-calls.

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 the given element and can be retrieved through the jQuery function data with the key pincette-init.

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',
            passUrl: 'https://www.pincette.biz/pass.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.

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

Set this callback if you want to do something additional after 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

The constructed item.

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.

afterSearch (default: null)

This function is called after a search has been performed. It will receive two arguments. The first is the url from which the search was started. The second is a state object.

afterUpload (default: null)

When this callback is set it is called after every individual upload. The first parameter url is the URL of the uploaded document. The second parameter 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: actions-per-day, activity, all-actions, annexes, attach-workflow, average-response-time-per-day, check-in, check-out, copy, cut, delete, downloads-per-day, downloads-per-folder, downloads-per-minute, edit-user, edit-workflow, expand, link, meta-data, meta-data-add-value, mkcol, new-group, new-user, new-workflow, next-workflow, paste-document, paste-folder, previous-workflow, recent, rename, send-mail, send-pass, sharing-bind, sharing-read, sharing-read-version-history, sharing-write, sharing-write-documents, sharing-unbind, show-bindings, show-groups, show-link, subscribe-rss, uncheck-out, unique-visitors, unlock, uploads-per-day, 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 an array with the following possible values: activity, collection, document, principal, version-history or view. A resource can have multiple resource types, e.g. collection and principal in case of a group. You can use the exclamation mark to exclude some resource types. For example, [collection, !principal] excludes the groups.

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:

all

All privileges.

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.

read-version-history

Read the version history of a document or folder.

unbind

Remove a name-binding to a resource within a folder.

uncheckout

Revert the check-out of a folder or document.

write

This privileges implies the privileges bind and unbind for folders and write-content and write-properties for documents.

write-acl

Update the Access Control List of a folder or document.

write-content

Update the contents of a document.

write-documents

This privilege is only defined for folders, but doesn't have an impact on the folders themselves. When privileges are inherited from a folder the write-documents privilege will be converted to write for documents and propagated as such for folders.

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.

defaultFailure (default: null)

When the server returns a low-level error a message box pops up. With this failure callback something else can be done instead.

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}
  }

filter(response) (default: null)

When the function is present and returns false the folder entry that corresponds to the response object is removed from the displayed list.

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.

passUrl (default: null)

The URL that is used to issue temporary passes for people who are not users of the system. This way protected documents can be shared with others. A pass is always accessed with the credentials of the user who issued the pass.

preload (default: true)

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

recentAgeInDays (default: 15)

Determines the period in which the most recent modified documents are shown.

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. The names of the fields may be preceded by an exclamation mark, which indicates reverse sort order.

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.

urlPickerRootUrl (default: rootUrl)

This is an alternative URL for the URL picker. The picker can be made more or less restrictive with it.

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-locked"/><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-chart

With this component a chart with an X-axis and an Y-axis can be shown. There should an element with the class chart inside it, as shown here:

<div class="pincette-chart">
  <div class="pincette-title-bar">
    <div>
      <div class="pincette-button red close">Close</div>
    </div>
    <div />
    <div />
  </div>
  <div>
    <div class="contents">
      <div class="chart" />
    </div>
  </div>
</div>

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-date-box

This box is used to pick up a date. There should be controls with the names year, month and day. An example:

<div class="pincette-date-box pincette-dialog-box">
  <div class="pincette-title-bar">
    <div>
      <div class="cancel pincette-button red">Close</div>
    </div>
    <div>Date</div>
    <div>
      <div class="ok pincette-button red">Done</div>
    </div>
  </div>
  <div class="contents">
    <div>
      <div class="label">Year</div>
      <div class="field"><select name="year" /></div>
    </div>
    <div>
      <div class="label">Month</div>
      <div class="field"><select name="month" /></div>
    </div>
    <div>
      <div class="label">Day</div>
      <div class="field"><select name="day" /></div>
    </div>
  </div>
</div>

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-events

With this component events from the Pincette audit trail are shown. There should be a template element that is used for each event. In the template you can add elements with special classes that denote the event components. The classes are occurrence, which is the timestamp of the event, user, operation, which should be combined with the classes get or update, and finally path, which isd the subject of the event. This is an example:

<div class="pincette-events">
  <div class="pincette-title-bar">
    <div>
      <div class="pincette-button red close">Close</div>
    </div>
    <div>Activity</div>
    <div>
      <div class="pincette-button red period">Period</div>
    </div>
  </div>
  <div>
    <div class="contents">
      <div class="template">
        <div class="occurrence" />
        <div class="user" />
        <div class="operation get">&#8595;</div>
        <div class="operation update">&#8593;</div>
        <div class="path" />
      </div>
    </div>
  </div>
</div>

pincette-expand

Certain functions such as Expand or Show groups display a folder tree. This component is used for it. It should have a template element that is used for each entry, like this for example:

<div class="pincette-expand">
  <div class="pincette-title-bar">
    <div>
      <div class="pincette-button red close">Close</div>
    </div>
    <div>Folders</div>
    <div />
  </div>
  <div>
    <div class="contents">
      <div class="template">
        <div class="name">$[name]&#160;</div>
        <div><span class="icon">&#5171;</span></div>
      </div>
    </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-locked

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

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-meta-data-add-value

With this element a value can be added to a meta-data property in the folder /meta/properties/. It should contain an input element with the name new. When the user types something the subelement with class values will show the existing values of the property that match. This way almost double values can be avoided. This is an example:

<div class="pincette-meta-data-add-value pincette-dialog-box">
  <div class="pincette-title-bar">
    <div>
      <div class="cancel pincette-button red">Close</div>
    </div>
    <div>Add value</div>
    <div>
      <div class="ok pincette-button red">Done</div>
    </div>
  </div>
  <div class="body">
    <div class="values" />
    <div><input name="new" type="text" /></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</div>
    </div>
    <div />
    <div>
      <div class="ok pincette-button red">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-new- user

This component is a dialog box to create a new user. It should have input elements with the names name, which is the username, displayname, which is the human-readable name, email, home, which is the home folder, group, which is the first group the user will belong to, password and again. The latter two should of type password. The input elements are all optional.

Next to the home input element you can place an element with the class pincette-browse. When clicked it will open a URL-picker in which you can choose the home folder.

An example:

<div class="pincette-new-user pincette-dialog-box">
  <div class="pincette-title-bar">
    <div>
      <div class="cancel pincette-button red close">Cancel</div>
    </div>
    <div>New user</div>
    <div>
      <div class="ok pincette-button red close">Save</div>
    </div>
  </div>
  <div class="body">
    <div>
      <div>
        <div class="label pincette-mandatory">Username</div>
        <div class="value">
          <input class="pincette-field" name="name" type="text" />
        </div>
      </div>
      <div>
        <div class="label">Name</div>
        <div class="value">
          <input class="pincette-field" name="displayname" type="text" />
        </div>
      </div>
      <div>
        <div class="label">E-mail</div>
        <div class="value">
          <input class="pincette-field" name="email" type="text" />
        </div>
      </div>
      <div>
        <div class="label pincette-mandatory">Password</div>
        <div class="value">
          <input class="pincette-field" name="password" type="password"
/>
        </div>
      </div>
      <div>
        <div class="label pincette-mandatory">Again</div>
        <div class="value">
          <input class="pincette-field" name="again" type="password" />
        </div>
      </div>
      <div>
        <div class="label">Language</div>
        <div class="value">
          <select name="language" />
        </div>
      </div>
      <div>
        <div class="label">Group</div>
        <div class="value">
          <select name="group">
            <option value="" label="" />
          </select>
        </div>
      </div>
      <div>
        <div class="label">Home folder</div>
        <div class="value">
          <input class="pincette-field" name="home" type="text" />
          <span class="pincette-browse pincette-button small
grey">Browse</span>
        </div>
      </div>
    </div>
  </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-period-box

This box is used to pick up a date range. It should contain an element with class from and another with class to. In those elements there should be controls with the names year, month and day. An example:

<div class="pincette-period-box pincette-dialog-box">
  <div class="pincette-title-bar">
    <div>
      <div class="cancel pincette-button red">Close</div>
    </div>
    <div>Period</div>
    <div>
      <div class="ok pincette-button red">Done</div>
    </div>
  </div>
  <div class="label">From</div>
  <div class="contents from">
    <div>
      <div class="label">Year</div>
      <div class="field"><select name="year" /></div>
    </div>
    <div>
      <div class="label">Month</div>
      <div class="field"><select name="month" /></div>
    </div>
    <div>
      <div class="label">Day</div>
      <div class="field"><select name="day" /></div>
    </div>
  </div>
  <div class="label">To</div>
  <div class="contents to">
    <div>
      <div class="label">Year</div>
      <div class="field"><select name="year" /></div>
    </div>
    <div>
      <div class="label">Month</div>
      <div class="field"><select name="month" /></div>
    </div>
    <div>
      <div class="label">Day</div>
      <div class="field"><select name="day" /></div>
    </div>
  </div>
</div>

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-reporter

This component is used to show output messages for certain functions. It should have a block-level element of class messages. A block-level element containing the message will be added to it for each message. Such an element may have the class error. Here is an example:

<div class="pincette-reporter">
  <div class="pincette-title-bar">
    <div>
      <div class="ok pincette-button red close">Close</div>
    </div>
    <div>Report</div>
    <div />
  </div>
  <div class="body">
    <div class="messages" />
  </div>
</div>

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 commands will be available. It should contain two elements with the classes all and granted respectively. Both should have a template element with the class name. The elements that are generated from the templates can be clicked on. They will always be moved to the other side.

The element can have an optional checkbox with the name propagate. When checked for a folder the changes will be applied as well to the entire contents of the folder. This is an example:

<div class="pincette-sharing pincette-dialog-box">
  <div class="pincette-title-bar">
    <div>
      <div class="cancel pincette-button red close">Close</div>
    </div>
    <div>Sharing</div>
    <div>
      <div class="ok pincette-button red close">Done</div>
    </div>
  </div>
  <div class="body">
    <div class="all">
      <div class="heading">All</div>
      <div class="principals pincette-add-list-index">
        <div class="template name pincette-list-index-item" />
      </div>
    </div>
    <div class="granted">
      <div class="heading">Granted</div>
      <div class="principals pincette-add-list-index">
        <div class="template name pincette-list-index-item" />
      </div>
    </div>
  </div>
  <div class="propagate">Propagate <input type="checkbox"
name="propagate" /></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-sign-out

This is a class that can be given to an anchor element with an href attribute. When clicked confirmation will be asked before opening the link in the attribute. The URL should be a logout-URL.

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</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-statistics

This component is used to show statistics where an X-axis and an Y-axis are correlated. The element should have a template element that is used to represent the (x,y) tuples. In it there should be two elements with the classes x-axis and y-axis respectively. At runtime an additional class will be added to those elements. It is formed with the prefix pincette-is- followed by the type of the axis. Available types are string, integer, duration, date and time.

If there is an element with the class period it will be used to change the period over which the data is collected. It expects to find the pincette-period-box component under the element that was used during initialization. Likewise, if some element has the chart class it will be used to show a chart of the collected data. For this to work there should be a pincette-chart component. Here is an example:

<div class="pincette-statistics">
  <div class="pincette-title-bar">
    <div>
      <div class="pincette-button red close">Close</div>
    </div>
    <div>
      <div class="pincette-button red chart">Chart</div>
    </div>
    <div>
      <div class="pincette-button red period">Period</div>
    </div>
  </div>
  <div>
    <div class="contents">
      <div class="template">
        <div class="x-axis" />
        <div class="y-axis" />
      </div>
    </div>
  </div>
</div>

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</div>
    </div>
    <div />
    <div>
      <div class="ok pincette-button red">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-trash

This is meant for a button that opens the trash folder in Pincette if there is any.

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, home, which is the home folder, password and again. The latter two should of type password. The input elements are all optional.

Next to the home input element you can place an element with the class pincette-browse. When clicked it will open a URL-picker in which you can choose the home folder.

An example:

<div class="pincette-user pincette-dialog-box">
  <div class="pincette-title-bar">
    <div>
      <div class="cancel pincette-button red close">Cancel</div>
    </div>
    <div>User</div>
    <div>
      <div class="ok pincette-button red close">Save</div>
    </div>
  </div>
  <div class="body">
    <div>
      <div>
        <div class="label">Name</div>
        <div class="value">
          <input class="pincette-field" name="displayname" type="text" />
        </div>
      </div>
      <div>
        <div class="label">E-mail</div>
        <div class="value">
          <input class="pincette-field" name="email" type="text" />
        </div>
      </div>
      <div>
        <div class="label">Password</div>
        <div class="value">
          <input class="pincette-field" name="password" type="password"
/>
        </div>
      </div>
      <div>
        <div class="label">Again</div>
        <div class="value">
          <input class="pincette-field" name="again" type="password" />
        </div>
      </div>
      <div>
        <div class="label">Language</div>
        <div class="value">
          <select name="language" />
        </div>
      </div>
      <div>
        <div class="label">Home folder</div>
        <div class="value">
          <input class="pincette-field" name="home" type="text" />
          <span class="pincette-browse pincette-button small
grey">Browse</span>
        </div>
      </div>
    </div>
  </div>
</div>

pincette-user-meta-data

An element with this class is used in a dialog box to edit meta-data of a user. 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 fields that didn't pass validation get the class pincette-bad-value. This is an example:

<div class="pincette-user-meta-data
pincette-dialog-box">
  <div class="pincette-title-bar">
    <div>
      <div class="cancel pincette-button red close">Close</div>
    </div>
    <div>Meta-data</div>
    <div>
      <div class="ok pincette-button red close">Done</div>
    </div>
  </div>
  <div class="body">
    <div>
      <div>
        <div class="label">Company</div>
        <div class="value">
          <input class="pincette-field" name="re_company" type="text" />
        </div>
      </div>
    </div>
  </div>
</div>

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>

pincette-workflow

With this component a workflow is edited. It should contain a template element with controls in it with the names user and status. Each row is a step in the workflow scheme. An example:

<div class="pincette-workflow pincette-dialog-box">
  <div class="pincette-title-bar">
    <div>
      <div class="cancel pincette-button red close">Cancel</div>
    </div>
    <div>Workflow</div>
    <div>
      <div class="ok pincette-button red close">Save</div>
    </div>
  </div>
  <div class="body">
    <div>
      <div class="template">
        <div>
          <div class="label">User</div>
          <div class="value">
            <input class="pincette-field" name="user" type="text" />
          </div>
        </div>
        <div>
          <div class="label">Status</div>
          <div class="value">
            <select name="status" />
          </div>
        </div>
        <div class="controls">
          <span class="add">+</span>
          <span class="delete">&#8211;</span>
          <span class="up">&#8593;</span>
          <span class="down">&#8595;</span>
        </div>
      </div>
    </div>
  </div>
</div>

pincette-workflow-step

This component is the dialog box that lets the user step throw the workflow scheme. At each step a comment can be entered and a due date. Therefore, there should be a textarea element with the name re_comment and an input field with the name re_dueDate. This field should be declared as a date field in the initialization of PincetteWeb. Here is an example:

<div class="pincette-workflow-step
pincette-dialog-box">
  <div class="pincette-title-bar">
    <div>
      <div class="cancel pincette-button red close">Close</div>
    </div>
    <div>Workflow step</div>
    <div>
      <div class="ok pincette-button red close">Done</div>
    </div>
  </div>
  <div class="body">
    <div>
      <div>
        <div class="label">Comment</div>
        <div class="value">
          <textarea class="pincette-field" name="re_comment" />
        </div>
      </div>
      <div>
        <div class="label">Due date</div>
        <div class="value">
          <input class="pincette-field" name="re_dueDate" type="text" />
        </div>
      </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

Pincette

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.

getcontentlength

The size in bytes of the document.

getcontenttype

The MIME type of the document.

getlastmodified

The time the document was last modified as a Date object.

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.

owner

The user who owns of the document.

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.

launchAction(action, response)

Calls a context-menu action with the name action, which should be one of the names mentioned in the builtInCommands option. The second argument is the response object that corresponds to the resource on which the action will be performed.

loadFolder(url)

Loads the folder denoted by url and displays the result in the folder area. The navigation history will be updated.

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.

search(expressions, sortFields)

Performs a search starting from the currently loaded folder and displays the result in the document area. The expressions parameter is an array of search expressions. The sortFields parameter is as described in the sortDocuments option.

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.

addLabel(url, label, depth, multiSuccess, multiFailure, success, failure, done)

The method adds a label to a resource and optionally everything under it. If the resource already has the label on another version the result will be two versions with the same label. A label can be any string. If the done function, without arguments, is present it will be called when all labels have been set. The success function is called instead of multiSuccess when the label is added only on the resource itself.

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.

exists(url, success, failure)

Calls success with a response object if the resource exists or null otherwise.

get(url, success, failure)

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

getAcl(url, success, multiFailure, failure)

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

getAllBindings(url, success, multiFailure, failure)

Calls success with an array of URLs, which are all the bindings a resource has in the repository.

getDefaultFailure()

Returns the default failure function that has been set.

getHome(url, success, multiFailure, failure)

Calls success with home URL if there is any.

getMetaData(url, multiSuccess, multiFailure, failure)

Gets the meta-data for the url argument.

getNames(collection, success, multiFailure, 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, multiSuccess, multiFailure, 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, multiSuccess, multiFailure, 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.

listFolder(collection, properties, success, failure)

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

lock(url, timeoutInSeconds, success, failure)

Locks a document so it can't be update by someone else. The timeoutInSeconds argument determines how long the lock will last. A negative value indicates the lock should be held infinitely. Note that the server impose a limit on the duration of the lock. The success function is called with an object with the following properties:

depth

0 or infinity

owner

The username of the user that acquired the lock.

root

The URL of the root of the lock. Since Pincette only supports locking for documents this will be the same as the request URL.

scope

exclusive or shared

timeout

The timeout string as defined in RFC 4918.

token

The token that should be used to call updating methods that are locked.

type

Currently the value will always be write

mkcol(url, success, failure)

Creates the collection denoted by url.

mkcols(url, success, failure)

Creates the collections denoted by url if they don't already exist.

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, multiSuccess, multiFailure, loaded, failure)

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, lockToken, multiSuccess, multiFailure, 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. The optional lockToken argument should contain the token obtained with the lock method.

put(url, body, headers, lockToken, success, failure)

A resource can be updated with the contents of the string in body. The headers is a name/value map of HTTP-headers. The optional lockToken argument should contain the token obtained with the lock method.

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.

removeLabel(url, label, depth, multiSuccess, multiFailure, success, failure, done)

The method removes a label from all versions of a resource and optionally everything under it. If the done function, without arguments, is present it will be called when all labels have been removed. The success function is called instead of multiSuccess when the label is removed only from the resource itself.

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, multiSuccess, multiFailure, loaded, failure)

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.

setEndActivity(fn)

Set the action to perform when server activity has ended.

setLabel(url, label, depth, multiSuccess, multiFailure, success, failure, done)

The method set a label on a resource and optionally everything under it. If the resource already has the label on another version that version will loose the label. A label can be any string. If the done function, without arguments, is present it will be called when all labels have been set. The success function is called instead of multiSuccess when the label is set only on the resource itself.

setStartActivity(fn)

Set the action to perform when server activity is about to start.

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.

When one of the steps in the chain fails the chain is broken, unless the failure method returns true. This can be used in scenarios where some operation is only an attempt, in which case a failure should be ignored.

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.

unlock(url, token, success, failure, done)

Removes the lock from a resource. The token argument should be obtained with the lock method.

$.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:

Demo

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

https://demo.pincette.net/