# -*- coding: UTF-8 -*-
#    This file is part of arena.
#
#    arena is free software: you can redistribute it and/or modify it
#    under the terms of the GNU General Public License as published by the
#    Free Software Foundation; either version 3 of the License or, at your
#    option, any later version.
#
#    arena is distributed in the hope that it will be useful, but
#    WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABLITY
#    or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
#    License for more details.
#
#    You should have received a copy of the GNU General Public License along
#    with arena.  If not, see <http://www.gnu.org/licenses/>.

## @file
#  This file defines and implements a viewpoint, which is a custom instance of
#  AnEngine that is responsible for displaying a view or template to a
#  remote user. 
#  
#  This engine will make use of the following query parameters, if they are
#  provided by the client:
#  - <tt>channel</tt>: The name of the channel to be displayed
#  - <tt>view</tt>: The name of the view to apply to the channel 
#  - <tt>title</tt>: The name of a post to be displayed
#
#  When using Apache's ModRewrite and the .htaccess file included with arena,
#  and when Site.Channels.cleanURLs is set to \p True in Configuration.py, then
#  these query parameters are parsed from the URL as follows:
#    <tt>http://yoursite/path/to/arena/channelname/title?view=viewname</tt>

from Plugins.Application.Arena.ArenaMediators import AnArenaMediator, \
    AnArenaMediatorError
from Local.Configuration import Site
from Library.String.Utilities import String
import urllib

## The application version
vpVersion = "v0.4"

## Represents an error that might occur within the viewpoint module itself.
class AViewpointError(AnArenaMediatorError):
    pass

## The main "engine" of arena, which drives all of its functionality.
class AViewpoint(AnArenaMediator):
    ## Constructor
    def __init__(Self, **params):
        AnArenaMediator.__init__(Self, **params)

    ## Initializer
    def init(Self):
        result = AnArenaMediator.init(Self)

        if result == True:
            # Establish private attributes
            # The application version
            Self._version = vpVersion
 
        return result
        
    ## Construct a URL for the remote client which contains the path to
    #  the running script, the name of the running script, and any additional
    #  query components provided.
    def url(Self, **queryComponents):
        if Site.Sessions.inCookie == False:
            queryComponents[Site.Sessions.cookieName] = Self._Session.id()
        
        # When used with ModRewrite and Apache, this code segment allows
        # channels and posts to be accessed via "clean" URLs, such as:
        #
        #    http://example.com/channelName/
        #    http://example.com/channelName/postTitle
        #    http://example.com/channelName/postTitle?view=viewName
        #
        # and so forth
        if Site.Views.cleanURLs:
            result = Self._path["client"] + "/"
            
            if len(queryComponents) > 0:
                if "channel" in queryComponents:
                    result += urllib.quote_plus(queryComponents["channel"], 
                      "&=$/")
                    result += "/"
                    del queryComponents["channel"]
                    
                if "title" in queryComponents:
                    result += urllib.quote_plus(queryComponents["title"],
                      "&=$/")
                    del queryComponents["title"]
                    
            if len(queryComponents) > 0:
                queryString = String.implode(queryComponents, "&")
                queryString = urllib.quote_plus(queryString, "&=$/")
                queryString = queryString.replace("&", "&amp;")

                result += "?" + queryString
                
        else:
            result = AnArenaMediator.url(Self, **queryComponents)
            
        return result        
