Public API of Silva

  Meta::

    Valid for:  Silva 1.0+
    Authors:    Martijn Faassen
    Email:      faassen+infrae.com
    CVS:        $Revision: 1.12 $ $Date: 2004/05/27 14:01:47 $

Draft version (incomplete)

  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">More....</a>
    
    get_title()

      Gives the title of the object. In case of containers (such as
      Silva Folder, Silva Publication and Silva Root), gives the title
      of the container. This may differ from the (possibly more
      extensive) title used in the container's index document. The index
      determines the content a user sees when requesting a container.

      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_short_title()

      Gives the short title of the object, if it exists. Otherwise
      get_short_title falls back to the title (and ultimately to the id,
      if no titles exist).

      The short title is useful for creating efficient and readable
      navigation such as breadcrumbs and menus.

      Example use in ZPT::
    
        <h2 tal:content="here/get_short_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>

      The breadcrumb trail will show the index document, which often has
      the same title as the folder. To turn this off use python, with
      an ignore_index argument::

        <tal:block tal:repeat="item python:here.get_breadcrumbs(ignore_index=None)">

    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>

  Publishable objects (Content and Containers, not assets)

    is_published()

      Returns true if the object is published.
      
    is_deletable()

      Returns true if object can be deleted from within Silva. An object
      is only deletable if it is not published and not approved.

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

    get_default_viewable()

      Return the viewable version of the deafult content object of this
      container. Returns None if no such object can be found.
     
    get_ordered_publishables()
 
      Gives all the publishables (containers and content objects) in this
      container, whether they're published or not.

    get_assets()
  
      Get all assets in this container.

    get_public_tree(depth)
    
      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 will 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">
          
          <p
            tal:define="indent python:pair[0]"
            tal:condition="indent"
            tal:attributes="
              style python:'padding-left: '+str(indent * 16)+'px';
          ">
            <a tal:define="item python:pair[1]" 
              tal:attributes="href item/absolute_url" 
              tal:content="item/get_short_title">
              Title
            </a>
          </p>
        </tal:block>
    
      Depth can be limited by using python and specifying a parameter of
      0 for the current container, or 1 for one level down, and so on.
    
      Example use in ZPT::
    
        <tal:block define="tree python:publication.get_public_tree(0)">
    
      This will return just the objects on the current level. A value of -1
      will get the entire tree. -1 is the default depth, which you get 
      when using a TALES path expression as in the first example.

    get_container_tree(depth)

      Give all the containers in the current container. This includes
      containers without any published content. Depth can be limited
      by using python and specifying a parameter of 0 for the current
      container, or 1 for one level down, and so on. See get_public_tree
      for more information.

    get_tree(depth)

      Give all objects in a tree in the current container, except index
      (default) documents. Unpublished objects will also be found. See
      get_public tree for more information.

    get_status_tree(depth)

      Give all objects in a tree in the current container. Instead of 
      containers, their indexes will be in the tree. Unpublished objects
      will also be found. See get_public_tree for more information.

    is_transparent()

      Returns true if this is something transparent; i.e. it will be
      'unfolded' in the sidebar, like a Folder. Publications are typically
      not transparent and will return false.
 
  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
    
    tag(**kw)
    
      returns an HTML snippet, i.e. a complete <a ...> tag; the keyword
      arguments provided will be rendered as html attributes. Use
      "css_class" to specify the class attribute.
    
    index_html(REQUEST)
    
      sets the correct headers and streams the file to the client (browser)
        
    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
    
    index_html(REQUEST)
    
      sets the correct headers and streams the web format image to the client
      (browser). In certain setup the client is redirected to the acutal
      image.

      Note: index_html is usually called by Zope when the client accesses the
      image direcly by URL (i.e. http://x.y.com/myimage.jpg). You can add
      query parameters to access the thumbnail or hires image:
      http://x.y.com/myimage?thumbnail or http://x.y.com/myimage?hires.

    getCanonicalWebScale(scale=None)
    
      returns (width, height) of web image 
    
      scale (optional): scale identifier (WidthXHeight or nn.n%)
        if given overrides stored scale (Note: if you pass an invalid scale
        a ValueError is raised)

    getCropBox()

      returns (x1, y2, x2, y2) -- the co-ordinates of the cropping area in
        relation to the hires image; or None if no cropping takes places

    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

    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.

    tag(hires=0, thumbnail=0, **kw)
    
      returns an HTML snippet, i.e. a complete <img .../> tag; the
      keyword arguments provided will be rendered as html attributes. Use
      "css_class" to specify the class attribute.

      hires: bool, if true an img-tag referencing the hires image is returned
      thumbnail: bool, if true an img-tag referencing the thumbnail image is
        returned
      if neither hires nor thumbnail is true an img-tag referencing the web
        image is returned (default)

    url(hires=0, thumbnail=0)
    
      returns url to the image
      
      hires: bool, if true the url of the hires image is returned
      thumbnail: bool, if true the url of the thumbnail image is returned
      if neither hires nor thumbnail is true the url of the web image is 
        returned (default)

      Note: you should *always* use this method when referencing a Silva
      image. If you do static serving via ExtFile this method will return
      static urls.

    getWebFormat()
    
      returns web image's format

    getWebScale()
    
      returns stored scale identifier

    getWebCrop()

      returns the stored crop identifier

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

      If scaling is possible, cropping and format conversions are also possible

    getFileSystemPath():
    
      returns file system path of ExtImage, None if image is stored in the ZODB

    getOrientation()

      returns 'square', 'landscape' or 'portrait' -- the image's orientation

    get_file_size()
    
      returns size of hi res image in bytes

    get_scaled_file_size()
    
      return size of web image in bytes
