pygal/help.py

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

# TODO: Add field descriptions including the filed list choices, if field has a list of limited values (e.g. flash: "fired", ...)
# TODO: Describe logic operator order and brackets if possible
# TODO: Expend Examples for pictures without flash and high f_number to get potentially good quality images.

HELP_UID = 'help'

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

**PyGal** is a File **Gal**ery visulisation tool implementes in **Py**thon.

It is designed to visualise images and videos. Nevertheless it is also possible to \
visualise audio files and all other files.


== Help
* [[faq|Frequently asked questions]]
* [[access|Access Conrtrol]]
* [[search|Help on Search]]

"""))

FAQ = mycreole.render_simple(_("""
= Frequently asked questions
==Repeat-Mode
On Problems with the Repeat-Mode, please check your Browser \
[[https://www.google.com/search?q=autoplay+enable+browser|properties]] \
for autoplay restrictions!
"""))

ACCESS = mycreole.render_simple(_("""
= Access control
Access Control is defined on folder level. The rights given for a folder \
are the rights for all items in that folder. The folder itself has no access \
restrictions. The content of a folder is defined by the accessable items \
recursive below that folder.

**Example:** If a user has only read access to the folder "bar" below the folder "foo", \
but not to "foo", he will see the folder "bar" inside the folder "foo" and all items in \
"foo/bar", but not the items in the folder "foo".
"""))

SEARCH = mycreole.render_simple(_("""
= Search
The search looks up full words in //Itemnames (name)// and //Tags (tag)// without giving \
special search commands in the search string.


== Search-Fields
The useful search fields depend on the item type. Therefore some fields are given twice or \
more in the different type depending lists.

=== General search fields
* rel_path (TEXT):
* name (TEXT):
* type (TEXT):
* favourite_of (KEYWORD):
* datetime (DATETIME):
* size (NUMERIC):
* tag (KEYWORD):

=== Image
* exposure_program (TEXT):
* exposure_time (NUMERIC):
* flash (TEXT):
* f_number (NUMERIC):
* focal_length (NUMERIC):
* lon (NUMERIC):
* lat (NUMERIC):
* height (NUMERIC):
* iso (NUMERIC):
* camera (TEXT):
* orientation (NUMERIC):
* width (NUMERIC):

=== Audio
* album (TEXT):
* artist (TEXT):
* bitrate (NUMERIC):
* duration (NUMERIC):
* genre (TEXT):
* title (TEXT):
* track (NUMERIC):
* year (NUMERIC):

=== Video
* ratio (NUMERIC):


== 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
** ...

== Examples
* [[/pygal/userview/search?q=type:video AND datetime:2018|type:video AND datetime:2018]] gives results with all videos in year 2018.
* [[/pygal/userview/search?q=datetime:[-2y to now]|datetime:[-2y to now]]] gives results with all item of the last two years.
* [[/pygal/userview/search?q=rel_path:2018*|rel_path:2018*]] gives results with all item having 2018 in their path.
* [[/pygal/userview/search?q=tag:Test|tag:Test]] gives results with all item having Test in their tags.
* [[/pygal/userview/search?q=datetime:2016 AND favourite_of:*|datetime:2016 AND favourite_of:*]] gives results with all item having 2018 in their tags or path and are favourite of someone.
"""))

help_pages = {
    'main': MAIN,
    'faq': FAQ,
    'access': ACCESS,
    'search': SEARCH,
}


def actionbar(context, request, current_help_page=None, **kwargs):
    actionbar_entries = (
        ('1', 'Main'),
        ('2', 'Faq'),
        ('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
            pygal.url_helpview(request, name.lower()),              # url
            True,                                                   # left
            name.lower() == current_help_page,                      # active
        )