module Scrivito
  #
  # This helper contains methods, which are available in both your views and your controllers.
  #
  # @api public
  #
  module ControllerHelper
    #
    # Returns the (URL-)path of a CMS object.
    #
    # @api public
    #
    # @param target [Obj, Link, Array<Link>, Binary]
    #   If +target+ is an +Array+ of +Links+, it must be non-empty.
    #   Only the first {Link} of the +Array+ is used.
    # @param options [Hash] include url settings such as path parameters or the protocol.
    #
    # @return [String]
    #
    # @note +scrivito_path+ is also a helper method.
    #
    def scrivito_path(target, options = {})
      CmsRouting.new(request, self, scrivito_engine).path_or_url(target, "path", options)
    end

    #
    # Returns the absolute URL of a CMS object.
    #
    # @api public
    #
    # @param target [Obj, Link, Array<Link>, Binary]
    #   If +target+ is an +Array+ of +Links+, it must be non-empty.
    #   Only the first {Link} of the +Array+ is used.
    # @param options [Hash] include url settings such as path parameters or the protocol.
    #
    # @return [String]
    #
    # @note +scrivito_url+ is also a helper method.
    #
    def scrivito_url(target, options = {})
      CmsRouting.new(request, self, scrivito_engine).path_or_url(target, "url", options)
    end

    #
    # Returns whether the GUI is in the +editable+ view.
    #
    # @api public
    #
    # @return +true+ if the current visitor is an authenticated editor, the selected workspace is
    #   editable and the display mode is +editing+.
    # @return +false+ otherwise.
    #
    # @note +scrivito_in_editable_view?+ is also a helper method.
    #
    def scrivito_in_editable_view?
      EditingContextMiddleware.from_request(request).editable_display_mode?
    end

    #
    # Returns the current user.
    #
    # @api public
    #
    # @return [Scrivito::User] if the {Scrivito::Configuration.editing_auth} callback returns an
    #   instance of {Scrivito::User}.
    # @return +nil+ otherwise.
    #
    # @note +scrivito_user+ is also a helper method.
    #
    def scrivito_user
      Scrivito::EditingContextMiddleware.from_request(request).editor
    end
  end
end