====== IfAuthEx Plugin ======

---- plugin ----
description: Toggle DokuWiki page content based on users and groups with arbitrary boolean expressions
author     : Pietro Saccardi
email      : lizardm4@gmail.com
type       : syntax
lastupdate : 2023-02-08
compatible : Greebo, Hogfather, Igor, Kaos
depends    :
conflicts  :
similar    : ifauth, showif, condition, isauth, nodisp
tags       : acl, groups, hide, if, users

downloadurl: https://git.mittelab.org/proj/ifauthex-dokuwiki-plugin/-/jobs/artifacts/v0.3/raw/ifauthex.zip?job=package
bugtracker : https://github.com/mittelab/ifauthex-dokuwiki-plugin/issues
sourcerepo : https://git.mittelab.org/proj/ifauthex-dokuwiki-plugin
donationurl: https://www.mittelab.org/en/

screenshot_img : 
----

===== Installation =====

Please use the [[plugin:extension|extension manager]] to install the plugin, no configuration needed.

For manual install, use the URL above and refer to [[:Plugins]].

===== Examples/Usage =====

This plugin selectively renders portion of the wiki page for certain users or groups (or combination of these conditions). The content is not truly hidden, it is just not rendered (it is still visibile on the source).  To truly hide use the [[plugin:nodisp]] plugin.

  <ifauth @user>
    Visible only to logged in users
    <ifauth !testuser>
      Visible to all logged in users except ''testuser''
    </ifauth>
  </ifauth>

  <ifauth @admin>
    Visible only to admins
  </ifauth>

  <ifauth testuser>
    Visible only to the user ''testuser''
  </ifauth>

  <ifauth @user && !@admin>
    Visible only to logged in users who are not admins
  </ifauth>

  <ifauth !eviluser>
    Hidden to ''eviluser''
  </ifauth>

  <ifauth @経営企画本部 && !@企画部>
    Visible to the corporate planning division but not the planning department.
    This requires the ''mbstring'' extension to be loaded.
  </ifauth>

  <ifauth !@user>
    Hidden to logged in users
  </ifauth>

  <ifauth !@user || testuser>
    Visible only to ''testuser'' or when you are not logged in
  </ifauth>

  <ifauth @staff && @admin>
    Visible only to members of the staff who are admin too
  </ifauth>

In the examples above
  * these are all groups: ''user'', ''admin'', ''staff'', ''経営企画本部'', ''企画部''
  * these are all users: ''testuser'', ''eviluser''


===== Syntax =====

Basic syntax:
  <ifauth EXPR>Content to selectively display</ifauth>

The content will be rendered only if the access condition described by ''EXPR'' is satisfied.
''EXPR'' is built using the standard PHP logical operators NOT ''!'', AND ''&&'', OR ''||'' and the parentheses ''(SUBEXPR)''. The access conditions are described using the following literals:
  * ''@group'' true if and only if the viewing user is a member of ''group''
  * ''user'' (not preceded by ''@''): true exclusively if ''user'' is the viewer of the page

You can form arbitrary expressions such as the ones in the examples above, or more sophisticated such as ''(usr1 || @grp1 || usr2) && (@grp2 || !@grp3 && @grp4)''.

In user names and group names, you can use letters, numbers, dots ''.'', dashes ''-'', and underscores ''_''. In fact, you can use anything matched by the regular expression ''[\w.-]+'', including UTF-8 multibyte characters (although that requires the ''mbstring'' extension to be active).

If you need to use any other character, you must wrap the user name in double quotes, e.g. ''%%"user name with space"%%'', see [[#Quoting names|below]].

  * **Not quoted whitespace in the expression is ignored.**
  * **For compatibility with the [[plugin:ifauth|ifauth Plugin]], you may use a comma '','' instead of the OR operator ''||''.**
  * **Multibyte strings in UTF-8 require ''mbstring'' to be loaded.**

==== Quoting names ====

If you have user or group names which contains characters other than those mentioned above (''[\w.-]+''), you can still specify them, but you have to quote them. The rules are as follows:

  * Wrap the whole name in double quotes ''%%"user or group name"%%''.
  * If you have a backslash in the name, you must double it: ''%%"DOMAIN\\Users"%%'' identifies ''DOMAIN\Users''.
  * If you //really// have a double quote in a name, you must escape it with a backslash: ''%%"A quote \" in the name"%%'' identifies ''%%A quote " in the name%%''.

Quotes go around the user name and group name; logical operators (e.g. ''!'') and the in-group operator ''@'' remain outside, as in ''%%@"DOMAIN\\Admins" && !"DOMAIN\\EvilAdmin"%%''.

===== Remarks and limitations =====

  * **Pages using IfAuthEx cannot be cached.**\\ Obviously, they need to be re-rendered depending on who's viewing. You do not need to add ''%%~~NOCACHE~~%%'', it's done automatically.
  * **The "hidden content" will still be readable in the source of the page,**\\ if the user is allowed to edit the page content. The plugin is meant to tailor the page to different users, not to guarantee secrecy. If that's what you are looking for, you may want to create a separate page with different access rights.
  * **The plugin removes ''<p>'' tags around its content,**\\ in the attempt of removing any extra unspecified markup.
  * **Starting from v0.3, you can now nest the ''<ifauth>'' classes.**
  * **Non-existent groups and users always evaluate to false.**\\ Watch out for misspelled groups. e.g. @user**s** <code>
<ifauth @users && !@admin>
  This content will be accidentally visible to admins.
</ifauth>
</code>
  * **Malformed expressions will not render.**\\ If your expression is not valid, the content won't render.<code>
<ifauth me && someoneelse &&>
  This will never render, did you forget something?
</ifauth>
</code>
  * **Sections are unaffected by IfAuthEx**.\\ This means that independently of where you put ''<ifauth>'', sections start after a header and end before the next header. This has some consequences:
    * When you edit a section, you might find an open ''<ifauth>'' tag without corresponding ''</ifauth>'' (because it is in the //next// section).
    * If the //first// page header is inside a hidden ''<ifauth>'' block, a (possibly empty) section will be opened. This is needed because the next header will close any previously opened section, independently of whether it has been displayed or not.

===== Compatibility with the ifauth plugin =====

This plugin intends to replace the [[plugin:ifauth|ifauth Plugin]], but
it's an independent reboot. By design, it features exactly the same syntax,
plus the extra logical operators, borrowed from PHP. You can just deactivate
ifauth, and activate ifauthex.

The case for writing a different plugin is because ifauth can only "or" the
conditions that are specified. We had the need of specifying precisely the
condition ''@members && !@admin'', and this simple expression already cannot
be specified in ifauth. So we generalized the syntax to arbitrary Boolean
expression (in for a penny...).

===== Development =====
(Consider a request for an 'else' option to go with the 'if' please? So you would have one option or the other.)

Goes without saying, this plugin **does not use ''eval''**.

The plugin contains internally a relatively simple tokenizer and lexer/parser, which generates an abstract syntax tree and can evaluate it depending on the operations defined. It is not super efficient or the most flexible, but it does the job and it's reconfigurable. It is implemented in ''ifauthex/lib/'', in the files ''tokenizer.php'', ''parser.php'', ''exceptions.php''.

The grammar for this specific application is independently defined in ''ifauthex/lib/grammar.php'', so tokenizer, lexer and parsers could be reused for other plugins.

=== Change Log ===

[[https://git.mittelab.org/proj/ifauthex-dokuwiki-plugin/-/releases|Release list]]

{{rss>https://git.mittelab.org/proj/ifauthex-dokuwiki-plugin/tags?format=atom description}}