Public API of Silva

============================= DRAFT VERSION ================================

  Meta::

    Valid for:  Silva 0.9.2+
    Authors:    martijn faassen
    Email:      faassen+infrae.com
    CVS:        $Revision: 1.6 $ $Date: 2003/12/03 13:04:30 $

All objects

view()

  Render the object content as HTML as for viewing by the public
  (people who browse to the website). Note that navigation/layout
  information is not part of this.

  Example use in ZPT::

    <div tal:replace="structure here/view" />

absolute_url()

  A built-in Zope method to produce the absolute url to an
  object. This produces the full URL to the object as it could be used
  from other sites to reference your object.

  Example use in ZPT::

    <a tal:attributes="href here/absolute_url">Click here!</a>

get_title()

  Gives the title of the object. In case of containers (such as Silva
  Folder, Silva Publication and Silva Root), give the title of the
  object called 'index' if available.

  In case of versioned content like a Silva Document the title is
  versioned as well; 'get_title()' gives the title of the public
  version.

  Example use in ZPT::

    <h2 tal:content="here/get_title">Title</h2>

get_title_or_id()

  Gives the public title of the object, or if no title found, the id.

get_creation_datetime()

  Get the date and time of creation of the object.

get_modification_datetime()

  Get the last modification datetime of the object. Returns None if
  not supported.

get_xml()

  Render this object in Silva XML representation. The returned string is in
  UTF-8 encoding.

get_breadcrumbs()

  Return a list of objects starting from the Silva root up to and
  including the current object.

  Example use in ZPT::

    <tal:block tal:repeat="item here/get_breadcrumbs">
      <a tal:attributes="href item/absolute_url" 
         tal:content="item/get_title">Title</a>
      /
    </tal:block>

get_container()

  Get the nearest container in the acquisition hierarchy. This is actually
  defined on container objects, but thanks to Zope's acquisition you can
  get to it from anywhere, which is indeed the intended use.

  Example use in ZPT::

    <h2 tal:content="python:here.get_container().get_title()">Folder Title</h2>

container_url()

  Get the URL of the nearest container in the acquisition hierarchy.

  Example use in ZPT::

    <a tal:attributes="href here/container_url">Go to the nearest folder!</a>

get_root()
 
  Get the Silva root. Actually defined on the Silva Root, see comment
  at 'get_container()'.

  Example use in ZPT::

    <h2 tal:content="python:here.get_root().get_title()">Root Title</h2>

get_root_url()

  Get the url of the Silva root.

  The inconsistency will ('get_') will be removed in future versions
  of Silva.

  Example use in ZPT::

    <a tal:attributes="href here/get_root_url">To Silva Home</a>

get_silva_object()

  Get the nearest silva object (container or content) in the folder
  hierarchy. This is usually just 'here', so this method is currently
  just described for completeness.
 
silva_object_url()

  Get the URL of the nearest Silva object. This should normally be
  done with absolute_url(), it is just here for sake of completeness.

get_content()
  
  Get the nearest content object. Usually not very useful in a public
  page template, so this method is described for completeness' sake.

content_url()
 
  Get the URL of the nearest content object. Again described for
  completeness, not much practical use for a page template designer.

implements_content()

  Returns true if this object is a content object (not container or
  asset).

implements_versioned_content()

  Returns true if this object is a versioned content object.

implements_container()

  Returns true if this object is a container object.

implements_publication()

  Returns true if this object is a publication.

implements_publishable()

  Returns true if this object can be published directly (i.e not an
  asset but a content object or a container).

sec_is_open_to_public()

  Returns true if this object is viewable by the public. Note that
  this cannot be used to preclude access to a page (use Silva's UI for
  this). Its intended use is to give notifications in the public
  pages.

  Example in ZPT::

    <p tal:condition="here/sec_is_open_to_public">Open to everybody!</p>

sec_is_closed_to_public()
 
  Returns true if this object is not viewable by the public but only
  by those with Viewer access. Note that this cannot be used to
  preclude access to a page (use Silva's UI for this). Its intended
  use is to give notifications in the restricted pages.

  Example in ZPT::

    <p tal:condition="here/sec_is_closed_to_public">Restricted!</p>

Container

get_default()
  
  Return the 'index' object of this container, or None if no such 
  object can be found.
 
get_public_tree()

  Return a list of all published content (including containers) below
  this object (not including this object itself).

  This list is in an order reached by preorder traversal, and consists
  of pairs of depth, item. Take for instance the following tree::

     a
       b
         c
       d
         e
         f
          g
       h

   When 'get_public_tree()' is called on 'a', the following with be the
   result::

     [(0, b), (1, c), (0, d), (1, e), (1, f), (2, g), (0, h)]

   Example use in ZPT::

     <tal:block tal:repeat="pair here/get_public_tree">
       
       <img
          width="12" 
          height="14"
          tal:condition="indent"
          tal:define="indent python:pair[0]"
          tal:attributes="
            width python:indent * 24;
            src string:${here/silva_root}/globals/pixel.gif" />
         <a tal:define="item python:pair[1]" 
            tal:attributes="href item/absolute_url" 
            tal:content="item/get_title">Title</a>
         <br />
     </tal:block>

Content

is_default()

  Returns true if this object is the 'index' object of a container.

  Example use in ZPT::

    <p tal:condition="here/is_default">This is the index!</p>

Metadata

context.service_metadata.getMetadata(content_object):

  returns a metadata binding object for content object. See
  SilvaMetadata/API.txt for more details on this binding object.

content.get_metadata_element(set_name, element_name):

  Convenience Python script: returns value for metadata element
  'element_name' within set 'set_name'.

File

get_filename()

  returns the object's id, this is equivalent to getId()

get_file_size()
  
  returns size of uploaded file in bytes

get_mime_type()

  returns file's mime type

get_download_url()

  returns an URL for downloading the file. This usually is the absolute_url().

get_download_link(title_attr='', name_attr='', class_attr='', style_attr='')

  returns an HTML snippet, i.e. a complete <a ...> tag; if a xxx_attr
  parameteter is given the corresponding attribute xxx is set on anchor tag.

download(REQUEST)

  sets the correct headers and streams the file to the client (browser)

set_file_data(file)

  changes the file stored

getFileSystempath()

  returns the file name in the local filesystem if any. Returns None if the
  file object's data is stored in the ZODB.

Image

set_web_presentation_properties(web_format, web_scale):
  
  Sets format and scaling for web presentation

  web_format (str): either JPEG or PNG (or whatever other format 
      makes sense, must be recognised by PIL)
  web_scale (str): WidthXHeight or nn.n%

  raises ValueError if web_scale cannot be parsed.

set_image(file)

  upload (hi res) image

  file: file like object to read image's data from
  
set_zope_image(zope_img)

  upload (hi res) image from zope image object
  
  zope_img: OFS.Image.Image or Products.ExtFile.ExtImage.ExtImage instance

getCanonicalWebScale(scale=None)

  returns (width, height) of web image 

  scale (optional): scale identifier (WidthXHeight or nn.n%)
    if given overrides stored scale

getWebScale():

  returns stored scale identifier
    
canScale():

  returns true if scaling is possible (i.e. PIL is installed)
  
getDimensions()

  Returns tuple (width, heigt) of (hi res) image
        
  raises ValueError if there is no way of determining the dimenstions
  return 0, 0 if there is no image
  returns width, height otherwise
        
getFormat()
  
  returns hi res image format (PIL identifier) or unknown if there is no PIL

getWebFormat()

  returns web image's format

getImage(hires=1, webformat=0, REQUEST=None)

  returns image

  hires: bool, if true hi res image is returned, web image otherwise
  webformat: bool, if true image is returned in web format, original format
    otherwise
  REQUEST: [optional], if given image written to response, returned as a str
    otherwise

  This method allows to retrief a full scaled image in web format.

getFileSystemPath():

  returns file system path of ExtImage, None if image is stored in the ZODB

get_file_size()

  returns size of hi res image in bytes

get_scaled_file_size()

  return size of web image in bytes
