patt/help.py

from django.utils.translation import gettext as _
import mycreole
import patt
from themes import color_icon_url

# TODO: Search: Describe search fields
# TODO: Search: Describe logic operator order and brackets if possible
# TODO: Search: Extend Examples with useful features.
# TODO: Search for specific content: Describe search possibilities (also in pygal)


HELP_UID = 'help'

MAIN = mycreole.render_simple(_("""
= PaTT

**PaTT** is a **P**roject **a**nd **T**eamorganisation **T**ool.

It is designed to store Tasks in relation to Projects and Users.

== Help
* [[creole|Creole Markup Language]]
* [[access|Access Control for the site content]]
* [[search|Help on Search]]

== Items

=== Task properties:
* State
* Targetdate
* Priority
* Progress
* Name
* Description

=== Project properties:
* Project Leaders
* Project Members
* State
* Name
* Description

"""))

CREOLE = mycreole.mycreole_help_pagecontent()
CREOLE += mycreole.render_simple("""
= PaTT Markup
{{{[[task:number]]}}} will result in a Link to the given tasknumber.

{{{[[tasklist:number]]}}} will result in a Link to the tasklist of the given projectnumber.
""")

ACCESS = mycreole.render_simple(_("""
= Superuser(s)
* Are able to view, create and edit everything!
* Only a Superuser is able to create a project.
= Non-Staff-Users
* Are able to read their own tasks, which are in the state "Open" or "Finished" and the related project(s) to these tasks.
* They don't get project role permissions (Projectleader, -member, ...), even if they have a role.
* They don't get permission to change any content.
= Projectleader(s)
* Are able to view and edit everything related to the project.
* They are able to create tasks for the project for any user with a projectrole.
= Projectmember(s)
* Are able to view everything related to the project.
* They are have limited modify permission to their own task related to that project.
* They are able to leave taskcomments at every task related to the project.
* They are able to create tasks related to the project for themselves.
= Projectvisitor(s)
* Are able to view everything related to the project.
* They are have limited modify permission to their own task related to that project.
"""))

SEARCH = mycreole.render_simple(_("""
= Search
The search looks up full words in //Tasknames (name)// and //Taskdescriptions (description)// without giving \
special search commands in the search string. The search will result in a tasklist.


=== Task search fields
* task_id (NUMERIC):
* assigned_user (TEXT):
* assigned_user_missing (BOOLEAN):
* name (TEXT):
* description (TEXT):
* state (TEXT):
** The state of a Task. It is one of the following states: Open, Finished, Closed, Cancelled
* targetdate (DATETIME):

=== Project related fields
* project_id (NUMERIC):
* project_name (TEXT):
* project_description (TEXT):

=== Comment related field
* comment (TEXT):


== Search syntax (Whoosh)
=== Logic operators
* AND
** **Example:** "foo AND bar" - Search will find all items with foo and bar.
* OR
** **Example:** "foo OR bar" - Search will find all items with foo, bar or with foo and bar.
* NOT
** **Example:** "foo NOT bar" - Search will find all items with foo and no bar.
=== Search in specific fields
A search pattern like //foo:bar// does look for //bar// in the field named //foo//.

This search pattern can also be combined with other search text via logical operators.
=== Search for specific content
* **Wildcards:**
* **Range:**
** From To:
** Above:
** Below:
* **Named constants:**
** //now//: Current date
** //-[num]y//: Current date minus [num] years
** //+[num]mo//: Current date plus [num] months
** //-[num]d//: Current date minus [num] days
** ...

== Examples
* [[/patt/tasklist/search?q=project_id:1|project_id:1]] gives results with all tasks of project number #1.
* [[/patt/tasklist/search?q=project_id:1 AND assigned_user:dirk|project_id:1 AND assigned_user:dirk]] gives results with all tasks of project number #1 which are assigned to 'dirk'.
* [[/patt/tasklist/search?q=assigned_user:dirk+AND+targetdate:[2000+to+%2b5d]|assigned_user:dirk AND targetdate:[2000 to +5d] ]] gives results with tasks having a targetdate within the next 5 days and assigned to 'dirk'.
"""))

help_pages = {
    'main': MAIN,
    'creole': CREOLE,
    'access': ACCESS,
    'search': SEARCH,
}


def actionbar(context, request, current_help_page=None, **kwargs):
    actionbar_entries = (
        ('1', 'Main'),
        ('2', 'Creole'),
        ('3', 'Access'),
        ('4', 'Search'),
    )
    for num, name in actionbar_entries:
        context[context.ACTIONBAR].append_entry(
            HELP_UID + '-%s' % name.lower(),                        # uid
            _(name),                                                # name
            color_icon_url(request, num + '.png'),                  # icon
            patt.url_helpview(request, name.lower()),               # url
            True,                                                   # left
            name.lower() == current_help_page,                      # active
        )