[xwiki-users] FAQ Application tutorial is incomprehensible
Hi, I need to modify an XWiki application to add some functionality, but I am new to XWiki and I am having a really hard time understanding it. I'm running XWiki Enterprise 7.1.2. The FAQ application tutorial <http://platform.xwiki.org/xwiki/bin/view/DevGuide/FAQTutorialManual> looks promising, but the instructions are outdated and I can't figure out how to get a finished product that looks like what the tutorial has. The following instructions are particularly problematic:
In the code, change the word "Main" with the name of the space where you want you FAQ pages to be created
There is no word "Main".
If you click on "View the template document" and edit that page in wiki mode, you will see the following code: {{include document="FAQ.FAQClassSheet"/}}
The page is blank, I don't see any code.
Use the Create top level menu (when using the Colibri skin) or the Create Panel to create the FAQ.WebHome page
I don't see anything marked "Create". Is there an experienced XWiki developer who would be willing to go through the FAQ application tutorial and rewrite it to make sense for the latest version of XWiki? More generally, it would be very helpful to have a glossary that defines and relates terms like "application", "page", "document", "object", "property", "class", "template", and "template provider". These terms are used in the documentation with little or no explanation, which adds to the confusion. -Alex
Hello Alex, I will look over the manual FAQ tutorial this week and update it. I'll also add some links to the documentation pages for the terms you specified. Thank you, Manuel On Tue, Aug 25, 2015 at 5:12 AM, Alex Henrie <[email protected]> wrote:
Hi,
I need to modify an XWiki application to add some functionality, but I am new to XWiki and I am having a really hard time understanding it. I'm running XWiki Enterprise 7.1.2. The FAQ application tutorial <http://platform.xwiki.org/xwiki/bin/view/DevGuide/FAQTutorialManual> looks promising, but the instructions are outdated and I can't figure out how to get a finished product that looks like what the tutorial has. The following instructions are particularly problematic:
In the code, change the word "Main" with the name of the space where you want you FAQ pages to be created
There is no word "Main".
If you click on "View the template document" and edit that page in wiki mode, you will see the following code: {{include document="FAQ.FAQClassSheet"/}}
The page is blank, I don't see any code.
Use the Create top level menu (when using the Colibri skin) or the Create Panel to create the FAQ.WebHome page
I don't see anything marked "Create".
Is there an experienced XWiki developer who would be willing to go through the FAQ application tutorial and rewrite it to make sense for the latest version of XWiki?
More generally, it would be very helpful to have a glossary that defines and relates terms like "application", "page", "document", "object", "property", "class", "template", and "template provider". These terms are used in the documentation with little or no explanation, which adds to the confusion.
-Alex _______________________________________________ users mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/users
Hello again, I have finished updating the FAQ tutorial. You might need to clear your cache (Ctrl + F5 on most browsers) to see the updated screenshots. I have followed the updated tutorial myself and was able to successfully create a FAQ application. Thank you, Manuel On Wed, Aug 26, 2015 at 9:13 AM, Manuel Smeria <[email protected]> wrote:
Hello Alex,
I will look over the manual FAQ tutorial this week and update it. I'll also add some links to the documentation pages for the terms you specified.
Thank you, Manuel
On Tue, Aug 25, 2015 at 5:12 AM, Alex Henrie <[email protected]> wrote:
Hi,
I need to modify an XWiki application to add some functionality, but I am new to XWiki and I am having a really hard time understanding it. I'm running XWiki Enterprise 7.1.2. The FAQ application tutorial <http://platform.xwiki.org/xwiki/bin/view/DevGuide/FAQTutorialManual> looks promising, but the instructions are outdated and I can't figure out how to get a finished product that looks like what the tutorial has. The following instructions are particularly problematic:
In the code, change the word "Main" with the name of the space where you want you FAQ pages to be created
There is no word "Main".
If you click on "View the template document" and edit that page in wiki mode, you will see the following code: {{include document="FAQ.FAQClassSheet"/}}
The page is blank, I don't see any code.
Use the Create top level menu (when using the Colibri skin) or the Create Panel to create the FAQ.WebHome page
I don't see anything marked "Create".
Is there an experienced XWiki developer who would be willing to go through the FAQ application tutorial and rewrite it to make sense for the latest version of XWiki?
More generally, it would be very helpful to have a glossary that defines and relates terms like "application", "page", "document", "object", "property", "class", "template", and "template provider". These terms are used in the documentation with little or no explanation, which adds to the confusion.
-Alex _______________________________________________ users mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/users
2015-08-27 4:17 GMT-06:00 Manuel Smeria <[email protected]>:
I have finished updating the FAQ tutorial. You might need to clear your cache (Ctrl + F5 on most browsers) to see the updated screenshots.
I have followed the updated tutorial myself and was able to successfully create a FAQ application.
This looks much better, thank you! I was able to successfully complete the updated tutorial. About the XWiki data model: It seems that "document" and "page" are synonyms, and every page has: - A class definition (a schema for a new type of object, not a schema for what kinds of objects the page can have) - A bag of objects - A string of wikitext - A parent Usually a page will not have all of these. For example, a page that has wikitext should probably not have objects attached to it too. But it looks like there is nothing to prevent ordinary users from adding ?editor=object to the URL and attaching objects to the page anyway. Why is it not more restrictive? -Alex
Hi, On Mon, Aug 31, 2015 at 8:39 PM, Alex Henrie <[email protected]> wrote:
2015-08-27 4:17 GMT-06:00 Manuel Smeria <[email protected]>:
I have finished updating the FAQ tutorial. You might need to clear your cache (Ctrl + F5 on most browsers) to see the updated screenshots.
I have followed the updated tutorial myself and was able to successfully create a FAQ application.
This looks much better, thank you! I was able to successfully complete the updated tutorial.
About the XWiki data model: It seems that "document" and "page" are synonyms, and every page has: - A class definition (a schema for a new type of object, not a schema for what kinds of objects the page can have) - A bag of objects - A string of wikitext - A parent
Usually a page will not have all of these. For example, a page that has wikitext should probably not have objects attached to it too. But it looks like there is nothing to prevent ordinary users from adding ?editor=object to the URL and attaching objects to the page anyway. Why is it not more restrictive?
There is no such restriction or best practice. It all depends on what that page is used for and what are the objects inside that page used for as well. Some objects can be used to mark certain pages. Others can store extra data: structured content in general (defined in user created xclasses) or even page comments, tags, etc. Other objects can set the document's rights. Other objects can specify which is the sheet to apply when viewing or editing the current document. The document's content (what you call "A string of wikitext") can have static content or dynamic content (scripts/code) which can execute either independently of the objects in the page or by reading some data from those objects, processing it and/or displaying/presenting it as the (dynamic) content of the document you are viewing. There are enough cases when a document has both content and objects, as the ability to have structured content in your document is a very big plus in XWiki, compared to some other wiki platforms. XWiki is a flexible platform and it all comes down to the usecase you are using it for, i.e. what you want to achieve. Hope this helps, Eduard
-Alex _______________________________________________ users mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/users
2015-09-02 7:30 GMT-06:00 Eduard Moraru <[email protected]>:
There is no such restriction or best practice. It all depends on what that page is used for and what are the objects inside that page used for as well.
Some objects can be used to mark certain pages. Others can store extra data: structured content in general (defined in user created xclasses) or even page comments, tags, etc. Other objects can set the document's rights. Other objects can specify which is the sheet to apply when viewing or editing the current document.
The document's content (what you call "A string of wikitext") can have static content or dynamic content (scripts/code) which can execute either independently of the objects in the page or by reading some data from those objects, processing it and/or displaying/presenting it as the (dynamic) content of the document you are viewing.
There are enough cases when a document has both content and objects, as the ability to have structured content in your document is a very big plus in XWiki, compared to some other wiki platforms.
XWiki is a flexible platform and it all comes down to the usecase you are using it for, i.e. what you want to achieve.
If I understand you correctly, manual monitoring and moderation is the only way to prevent a user from, for example, adding a bunch of objects to a page that is supposed to be wikitext-only. I don't think I would have designed XWiki with such loose restrictions, but if this was the design philosophy from the beginning then it makes more sense. Thanks for the explanation! -Alex
Hi Alex, On 4 Sep 2015 at 19:56:31, Alex Henrie ([email protected](mailto:[email protected])) wrote:
2015-09-02 7:30 GMT-06:00 Eduard Moraru :
There is no such restriction or best practice. It all depends on what that page is used for and what are the objects inside that page used for as well.
Some objects can be used to mark certain pages. Others can store extra data: structured content in general (defined in user created xclasses) or even page comments, tags, etc. Other objects can set the document's rights. Other objects can specify which is the sheet to apply when viewing or editing the current document.
The document's content (what you call "A string of wikitext") can have static content or dynamic content (scripts/code) which can execute either independently of the objects in the page or by reading some data from those objects, processing it and/or displaying/presenting it as the (dynamic) content of the document you are viewing.
There are enough cases when a document has both content and objects, as the ability to have structured content in your document is a very big plus in XWiki, compared to some other wiki platforms.
XWiki is a flexible platform and it all comes down to the usecase you are using it for, i.e. what you want to achieve.
If I understand you correctly, manual monitoring and moderation is the only way to prevent a user from, for example, adding a bunch of objects to a page that is supposed to be wikitext-only.
Indeed that’s the general premise of a wiki and that’s how it differs from other tools: collaborating and creating content is hard, which is why wikis make it easy for users to do so without having to ask for permissions. Notifications, history and rollback features are the way to provide oversight. In the huge majority of cases, no action is required and serendipity happens :) In XWiki, wiki pages can contain either unstructured data or structured data (xobjects). There’s no fundamental difference between both types of data and users should be free to add and modify any type of data (provided they have edit rights on the page). You mention “a page that is supposed to be wikitext-only”. Who says that? :) Who says that a page which starts with wiki text cannot be improved by having some part of it structured? I’ve done this countless of times to provide more features. I personally would find it a pity to arbitrarily restrict permissions to only some users. That’s not the principle of wikis at heart. I’d say: always try to be the most open, and if it causes problems then close down a bit if there’s no other way. In addition, some companies are used to the traditional way of working and would prefer to close down things a bit. Because XWiki is a flexible platform and because it’s an Enterprise Wiki, it has a strong permission model. Recently (in XWiki 7.2M1 and 7.2M2), we’ve added a new permission called the Scripting Permission and it’s possible to give it only to some users. See http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki72M1#HScri... and http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki72M2#HScri... I hope the rationale is more clear! (not sure if I explained it right :)).
I don't think I would have designed XWiki with such loose restrictions, but if this was the design philosophy from the beginning then it makes more sense.
Thanks for the explanation!
Thanks -Vincent
-Alex
2015-09-04 15:59 GMT-06:00 [email protected] <[email protected]>:
On 4 Sep 2015 at 19:56:31, Alex Henrie
If I understand you correctly, manual monitoring and moderation is the only way to prevent a user from, for example, adding a bunch of objects to a page that is supposed to be wikitext-only.
Indeed that’s the general premise of a wiki and that’s how it differs from other tools: collaborating and creating content is hard, which is why wikis make it easy for users to do so without having to ask for permissions. Notifications, history and rollback features are the way to provide oversight. In the huge majority of cases, no action is required and serendipity happens :)
In XWiki, wiki pages can contain either unstructured data or structured data (xobjects). There’s no fundamental difference between both types of data and users should be free to add and modify any type of data (provided they have edit rights on the page).
You mention “a page that is supposed to be wikitext-only”. Who says that? :) Who says that a page which starts with wiki text cannot be improved by having some part of it structured? I’ve done this countless of times to provide more features.
I personally would find it a pity to arbitrarily restrict permissions to only some users. That’s not the principle of wikis at heart. I’d say: always try to be the most open, and if it causes problems then close down a bit if there’s no other way.
In addition, some companies are used to the traditional way of working and would prefer to close down things a bit. Because XWiki is a flexible platform and because it’s an Enterprise Wiki, it has a strong permission model. Recently (in XWiki 7.2M1 and 7.2M2), we’ve added a new permission called the Scripting Permission and it’s possible to give it only to some users. See http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki72M1#HScri... and http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki72M2#HScri...
I hope the rationale is more clear! (not sure if I explained it right :)).
It was confusing to me because I am actually using PhenoTips <https://phenotips.org/>, which is based on XWiki, but in the default configuration I can't see why anyone would want or need to input unstructured data into this application. It seems strange that the user can add ?editor=wiki, ?editor=object, or ?editor=class to the URL and leave the default PhenoTips editor behind. Making scripts unexecutable is a step in the right direction even if it does not lock down the application in the same way that a traditional web app would. In other words, PhenoTips is built on XWiki, but its highly structured data model does not seem to fit the wiki paradigm. Maybe in the future the PhenoTips developers will patch XWiki to allow greater lockdown, but it's not a dealbreaker for me. Thanks again, -Alex
Hi Alex, On 5 Sep 2015 at 00:32:54, Alex Henrie ([email protected](mailto:[email protected])) wrote:
2015-09-04 15:59 GMT-06:00 [email protected] :
On 4 Sep 2015 at 19:56:31, Alex Henrie
If I understand you correctly, manual monitoring and moderation is the only way to prevent a user from, for example, adding a bunch of objects to a page that is supposed to be wikitext-only.
Indeed that’s the general premise of a wiki and that’s how it differs from other tools: collaborating and creating content is hard, which is why wikis make it easy for users to do so without having to ask for permissions. Notifications, history and rollback features are the way to provide oversight. In the huge majority of cases, no action is required and serendipity happens :)
In XWiki, wiki pages can contain either unstructured data or structured data (xobjects). There’s no fundamental difference between both types of data and users should be free to add and modify any type of data (provided they have edit rights on the page).
You mention “a page that is supposed to be wikitext-only”. Who says that? :) Who says that a page which starts with wiki text cannot be improved by having some part of it structured? I’ve done this countless of times to provide more features.
I personally would find it a pity to arbitrarily restrict permissions to only some users. That’s not the principle of wikis at heart. I’d say: always try to be the most open, and if it causes problems then close down a bit if there’s no other way.
In addition, some companies are used to the traditional way of working and would prefer to close down things a bit. Because XWiki is a flexible platform and because it’s an Enterprise Wiki, it has a strong permission model. Recently (in XWiki 7.2M1 and 7.2M2), we’ve added a new permission called the Scripting Permission and it’s possible to give it only to some users. See http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki72M1#HScri... and http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki72M2#HScri...
I hope the rationale is more clear! (not sure if I explained it right :)).
It was confusing to me because I am actually using PhenoTips , which is based on XWiki, but in the default configuration I can't see why anyone would want or need to input unstructured data into this application. It seems strange that the user can add ?editor=wiki, ?editor=object, or ?editor=class to the URL and leave the default PhenoTips editor behind. Making scripts unexecutable is a step in the right direction even if it does not lock down the application in the same way that a traditional web app would.
In other words, PhenoTips is built on XWiki, but its highly structured data model does not seem to fit the wiki paradigm. Maybe in the future the PhenoTips developers will patch XWiki to allow greater lockdown, but it's not a dealbreaker for me.
ok, I understand what you mean now: you’d like the ability to lock down existing applications, i.e. prevent users of them from making structural changes to them. That’s a valid use case and we support it :) Basically there are 2 use cases: * Letting users make changes to applications because this allows multiple users to develop collaboratively apps using XWiki. The idea is that of refactoring and an app is never ever finished and can always be improved. * However you may only want some experienced users or devs to do that and not anyone. What happens is that the app has 2 types of wiki pages (aka documents): * Technical pages that make the app * Data pages which are created by the user when he/she uses the app So what we do is that when we develop apps we usually create 2 spaces, one for the technical pages and one for the data pages. In this manner we can set permissions very easily on the space containing the technical pages so that only some authorized group or users have edit rights on them. Maybe in your case all that is required is to ask the phenotips developers to not allow all users to have edit rights by default on the technical pages of this app (and restrict them to admins by default for example)? Thanks -Vincent
Thanks again,
-Alex
2015-09-05 3:17 GMT-06:00 [email protected] <[email protected]>:
ok, I understand what you mean now: you’d like the ability to lock down existing applications, i.e. prevent users of them from making structural changes to them.
That’s a valid use case and we support it :)
Basically there are 2 use cases: * Letting users make changes to applications because this allows multiple users to develop collaboratively apps using XWiki. The idea is that of refactoring and an app is never ever finished and can always be improved. * However you may only want some experienced users or devs to do that and not anyone.
What happens is that the app has 2 types of wiki pages (aka documents): * Technical pages that make the app * Data pages which are created by the user when he/she uses the app
So what we do is that when we develop apps we usually create 2 spaces, one for the technical pages and one for the data pages. In this manner we can set permissions very easily on the space containing the technical pages so that only some authorized group or users have edit rights on them.
Maybe in your case all that is required is to ask the phenotips developers to not allow all users to have edit rights by default on the technical pages of this app (and restrict them to admins by default for example)?
PhenoTips already prevents ordinary users from editing technical pages, period. What I really want is to go a step further and only allow the inline form editor (editor=inline) to be used to edit data pages. I do not want users to be able to add classes, objects, or wikitext to pages (editor=class, editor=object, editor=wiki) outside of what the editor written specifically for PhenoTips would allow. Again, this feature is not a dealbreaker, but it could avoid abuse of the system. -Alex
On Thu, Sep 10, 2015 at 3:50 AM, Alex Henrie <[email protected]> wrote:
2015-09-05 3:17 GMT-06:00 [email protected] <[email protected]>:
ok, I understand what you mean now: you’d like the ability to lock down existing applications, i.e. prevent users of them from making structural changes to them.
That’s a valid use case and we support it :)
Basically there are 2 use cases: * Letting users make changes to applications because this allows multiple users to develop collaboratively apps using XWiki. The idea is that of refactoring and an app is never ever finished and can always be improved. * However you may only want some experienced users or devs to do that and not anyone.
What happens is that the app has 2 types of wiki pages (aka documents): * Technical pages that make the app * Data pages which are created by the user when he/she uses the app
So what we do is that when we develop apps we usually create 2 spaces, one for the technical pages and one for the data pages. In this manner we can set permissions very easily on the space containing the technical pages so that only some authorized group or users have edit rights on them.
Maybe in your case all that is required is to ask the phenotips developers to not allow all users to have edit rights by default on the technical pages of this app (and restrict them to admins by default for example)?
PhenoTips already prevents ordinary users from editing technical pages, period. What I really want is to go a step further and only allow the inline form editor (editor=inline) to be used to edit data pages. I do not want users to be able to add classes, objects, or wikitext to pages (editor=class, editor=object, editor=wiki) outside of what the editor written specifically for PhenoTips would allow.
The simplest thing you could do is to add a skin extension [1] that hides the unwanted edit modes, either through CSS or through JavaScript. The second option would be to customize the skin [2] and hide the options directly from the skin (server side, in the .vm files). This will still allow some users to directly use a hand-crafter URL (i.e. by bypassing the UI) to access the other edit modes, but those would be isolated cases and should not be an issue. Thanks, Eduard ---------- [1] http://platform.xwiki.org/xwiki/bin/view/DevGuide/SkinExtensionsTutorial [2] http://platform.xwiki.org/xwiki/bin/view/DevGuide/Skins
Again, this feature is not a dealbreaker, but it could avoid abuse of the system.
-Alex _______________________________________________ users mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/users
Hi Alex, On 10 Sep 2015 at 02:51:06, Alex Henrie ([email protected](mailto:[email protected])) wrote:
2015-09-05 3:17 GMT-06:00 [email protected] :
ok, I understand what you mean now: you’d like the ability to lock down existing applications, i.e. prevent users of them from making structural changes to them.
That’s a valid use case and we support it :)
Basically there are 2 use cases: * Letting users make changes to applications because this allows multiple users to develop collaboratively apps using XWiki. The idea is that of refactoring and an app is never ever finished and can always be improved. * However you may only want some experienced users or devs to do that and not anyone.
What happens is that the app has 2 types of wiki pages (aka documents): * Technical pages that make the app * Data pages which are created by the user when he/she uses the app
So what we do is that when we develop apps we usually create 2 spaces, one for the technical pages and one for the data pages. In this manner we can set permissions very easily on the space containing the technical pages so that only some authorized group or users have edit rights on them.
Maybe in your case all that is required is to ask the phenotips developers to not allow all users to have edit rights by default on the technical pages of this app (and restrict them to admins by default for example)?
PhenoTips already prevents ordinary users from editing technical pages, period. What I really want is to go a step further and only allow the inline form editor (editor=inline) to be used to edit data pages. I do not want users to be able to add classes, objects, or wikitext to pages (editor=class, editor=object, editor=wiki) outside of what the editor written specifically for PhenoTips would allow.
ok, that’s interesting. I don’t remember anyone voicing this concern but I can understand it. Indeed ATM, we provide a single Edit permission which allows any editor to be used (object, class, wiki, WYSIWYG, rights, etc). We could decide in the future to be more fine-grained, and provide a additional separate permission for Form editing (aka inline editing). Thus a User or Group could not have Edit rights in general and have only Form Edit rights. Maybe you could open a jira issue at http://jira.xwiki.org on this so that we remember it and discuss it/implement it in the future? (or whoever wants to submit a pull request/patch). Thanks -Vincent
Again, this feature is not a dealbreaker, but it could avoid abuse of the system.
-Alex
2015-09-10 5:26 GMT-06:00 [email protected] <[email protected]>:
On 10 Sep 2015 at 02:51:06, Alex Henrie ([email protected](mailto:[email protected])) wrote:
PhenoTips already prevents ordinary users from editing technical pages, period. What I really want is to go a step further and only allow the inline form editor (editor=inline) to be used to edit data pages. I do not want users to be able to add classes, objects, or wikitext to pages (editor=class, editor=object, editor=wiki) outside of what the editor written specifically for PhenoTips would allow.
ok, that’s interesting. I don’t remember anyone voicing this concern but I can understand it. Indeed ATM, we provide a single Edit permission which allows any editor to be used (object, class, wiki, WYSIWYG, rights, etc). We could decide in the future to be more fine-grained, and provide a additional separate permission for Form editing (aka inline editing). Thus a User or Group could not have Edit rights in general and have only Form Edit rights.
Maybe you could open a jira issue at http://jira.xwiki.org on this so that we remember it and discuss it/implement it in the future? (or whoever wants to submit a pull request/patch).
Done. http://jira.xwiki.org/browse/XWIKI-12555 -Alex
On 11 Sep 2015 at 20:40:41, Alex Henrie ([email protected](mailto:[email protected])) wrote:
2015-09-10 5:26 GMT-06:00 [email protected] :
On 10 Sep 2015 at 02:51:06, Alex Henrie ([email protected](mailto:[email protected])) wrote:
PhenoTips already prevents ordinary users from editing technical pages, period. What I really want is to go a step further and only allow the inline form editor (editor=inline) to be used to edit data pages. I do not want users to be able to add classes, objects, or wikitext to pages (editor=class, editor=object, editor=wiki) outside of what the editor written specifically for PhenoTips would allow.
ok, that’s interesting. I don’t remember anyone voicing this concern but I can understand it. Indeed ATM, we provide a single Edit permission which allows any editor to be used (object, class, wiki, WYSIWYG, rights, etc). We could decide in the future to be more fine-grained, and provide a additional separate permission for Form editing (aka inline editing). Thus a User or Group could not have Edit rights in general and have only Form Edit rights.
Maybe you could open a jira issue at http://jira.xwiki.org on this so that we remember it and discuss it/implement it in the future? (or whoever wants to submit a pull request/patch).
Thanks! -Vincent
-Alex
participants (4)
-
Alex Henrie -
Eduard Moraru -
Manuel Smeria -
vincent＠massol.net