Documentation: Yet Another Case in Point (PageEar)

fitness trainer - August 31, 2008 - 16:34

Good People of Drupal,

Here's another instance where Drupal documentation fails the newbie.

Last night I came across the amusing PageEar module.

Fun little module; I figured I'd have it ready in case I should ever need it one day.

I downloaded it and installed it, and enabled it not only within the usual Administer-->Site Building-->Modules, but also within its own Settings Page at Administer-->Site Configuration-->PageEar.

Of course, nothing.

I mean, absolutely nothing.

Typical Drupal experience, so after a month of this I guess I'm kind of getting used to it -- no more multiple exclamation and interrogation marks. ;-)

Well!

Turns out that I had to set, from within Administer-->Site Configuration-->PageEar, the default Conditions-->Criteria setting from "never validate" to "always validate."

Despite enabling that prominent "Enable PageEar" checkbox up on top, that additional step was necessary.

Yet without an install or readme.txt, nor any documentation, it was left up to me to figure things out.

The only "documentation," so-called, was an external link to webpicasso.de/blog/ where the instructions had nothing to do with Drupal users!

The instructions for this module are not only inadequate...they're worse even than non-existent...they're entirely misleading.

Nice module, though; don't get me wrong.

But this latest case only underscores my belief that Drupal is not hard to learn; it's just that there is extremely bad documentation for it.

As for PageEar, still unresolved is how to set things so that PageEar is only displayed on certain pages and not everywhere.

But at least I know now that it's not my fault.

I mean, to leave out the most basic instructions...sheesh....

I'm not picking on PageEar, mind you; I've yet to encounter one module that didn't leave out something for me to figure out on my own.

After seventeen contribs, though, I figure I'd finally document just what I've been ranting about all this time.

Post Scriptum

fitness trainer - August 31, 2008 - 17:17

Okay, just for the record:

Turns out, I need the Condition module to go along with the PageEar module. It's nowhere mentioned as a requirement, but unless you want a PageEar on every webpage, you'll want to be able to create conditions stipulating the specifics of its appearance.

I'm now able to control which webpages my PageEar shows up on, using the Condition module.

so...

silverwing - August 31, 2008 - 17:29

This is the last line of the description:

Use the condition module to further restrict when the PageEar should be displayed (e.g. certain roles, PHP code).

~silverwing
_____________________________________________
zinzinny - more than tv (alpha)| MisguidedThoughts | showcaseCMS

Yeah...

fitness trainer - August 31, 2008 - 18:12

But do you realize that to a newbie such a description flies right by?

And do you know why it flies right by?

Because a newbie knows nothing of "certain roles, PHP code"...s/he just knows that this is a module for a page-ear/page-peel effect...and a newbie imagines that of course such a module wouldn't be a simplistic binary on/off affair...yet the module seems to need another simply to implement a most basic function, that of specifying which page(s) to show up on!

Does that make sense?? To have a simple on/off page-ear; it's either on all your pages or none at all??? Does it make sense that another module should be needed to simply specify which pages get the page-ear? Would "certain roles, PHP code" suggest "which pages" to a newbie???

Okay, sorry for the multiple interrogation marks, but I am extremely puzzled over the mindset here! Who would think that a module hasn't the most obvious and basic functionality (specifying which pages to affect) out-of-the-box? Who would think that another module, described as being for "certain roles, PHP code" would be the one that provided such functionality?

And why is the documentation linked to not relevant to Drupal users at all, instructing as it does to edit a .js file??

Come on, admit it: it's just all very mysteriously done.

How to help

zirvap - August 31, 2008 - 18:18

And why is the documentation linked to not relevant to Drupal users at all, instructing as it does to edit a .js file??

Because noone has made Drupal specific documentation yet. You can fix that, right now, if you want to, so that the next newcomer won't have to be confused.

If you want to be part of the solution, you can do the following:

  1. Take a look at the Handbook style guide at http://drupal.org/about/authoring
  2. Write a brief description of how to configure the module. Doesn't have to be more than what you've written in this thread.
  3. Go to http://drupal.org/node/206776, post your module description as a child page there. (You don't have to be a doc team member to add new handbook pages)
  4. In http://drupal.org/project/issues/pageear, post a request to get the Documentation link at http://drupal.org/project/pageear changed, so it points to your new handbook page

Future users of the Pageear module will bless you.

(Or more likely, most of them will take your handbook page for granted, while a minority will post long threads in the forum claiming that your documentation sucks, but them's the breaks. At least you will have that warm, fuzzy feeling of having helped, in some small way, to improve the documentation. That's what keeps me contributing, anyway.)

HUH?!?!

fitness trainer - August 31, 2008 - 21:45

So..."because no one has made Drupal-specific documentation yet"...thhaaaat's why that page was linked, 'cause "better sumthin' than nuthin'"???

I mean, the instructions there talk about going into the .js file and editing the code...I had to blink several times before I suspected that, you know, this is just another bit of ye olde Drupal madness. That's the thing about Drupal: documentation sucks and you can't trust any of them. You have to second-guess all of them: flawed until proven otherwise!

Okay, I'll do as you suggest and annotate the PageEar documentation as best I can.

Thanks again for encouraging me to participate. I don't mean to piss people off, but I'm pretty tickled myself you know, what with having to assume Drupal is a monkey in order not to go bananas myself! 'Cause if I'm expecting it to be intelligent...well.... ;-)

Okay, shush.

The "description flies right

Keyz - August 31, 2008 - 21:23

The "description flies right by"... so you mean that the mere word "PHP" makes every newbie blind to the instructions? In some cases with huge chunks of scary code on the page, yes maybe. But anyone who sits still for 30 seconds to assess what the description on Condition module's page says will understand it, and see that PHP use is one of several options to make use of the module.

Pages
TRUE if the any/all/none of the entered path(s) is/are (like) the current path.

No documentation was "linked to", inferring that it was to be followed as documentation for the Drupal module. A link to the original creator of the script was made to inform about where the script is from, and because it is suggested in the script's license agreement that a link be provided. The Drupal module did not say "here's a link to the documentation". As I stated before, whether right or wrong, I believe the module creator found PageEar module to be completely self-explanatory (to him or her), as it does work instantly out of the box, so long as you are content with its built-in functionality, and reference to the other module to enable more advanced options was made.

PageEar module offers a way to expand its functionality through integration with the Condition module. And no, offering expandability in this way is not strange. This is the "Drupal way". Within reason, everything is to be as modular and flexible as possible. If a common piece of functionality shared among a variety of different modules can be separated out into an "API" and eliminate the constant duplication of the same code in other modules over and over, then that is highly recommended. Now "any" module, by anyone, can hook into the functionality of Condition module to augment their own functionality. If a module is "required" the Drupal Modules page will inform you about the dependency up front. Yes this adds some additional requirements of understanding for end users. But as a result they benefit from smarter, leaner, more powerful, and all around better modules.

-- David
absolutecross.com
[new guide/lesson in progress: Creating a CCK and Views powered Drupal site - feedback welcome]

Yes

fitness trainer - August 31, 2008 - 22:11

"PHP" means what? It's a server scripting language...am I looking to get involved with server operations? No, I'm getting the PageEar module, which puts a page-ear on webpages. Would a newbie imagine that someone sophisticated enough to create such a module didn't bother putting in the ability to chose which pages get page-ears with that module??

I don't know what you mean by "no documentation was 'linked to'"...it's very clear there, right under "Resources," where it says "Read documentation"...now if it ain't PageEar's documentation, what's it doing on the PageEar module page???

I'm sorry to have to disagree with you, Dave, but there's no excuse for a link that says "read documentation" that has nothing to do with using the PageEar module in Drupal!

Similarly, the PageEar module homepage should say that the Condition module is needed so that you don't get all your webpages page-eared (or none at all). If you download a chat module, do you expect it to stick a chatbox on every single webpage of your site?? So why do you think PageEar is fine with that kind of global on/off behavior?

What's weirder than these weird situations actually existing is that you and others defend their existence! It's just mind-boggling that people actually think that way...I mean, "documentation"...hello?? What does "read documentation" mean anymore, then??? It says "read documentation" and takes you to instructions that have nothing to do with the module -- and you say that's perfectly fine!!

This is why Drupal is "hard" to learn...because it's hard to understand what the Dickens people could be possibly thinking, what with a "read documentation" hyperlink that goes to instructions having nothing to do with the module!

"PHP" means what? It's a

Keyz - August 31, 2008 - 23:41

"PHP" means what? It's a server scripting language...am I looking to get involved with server operations? No, I'm getting the PageEar module, which puts a page-ear on webpages. Would a newbie imagine that someone sophisticated enough to create such a module didn't bother putting in the ability to chose which pages get page-ears with that module??

No we're using a PHP-based content management framework here. Every Drupal admin knows "what" PHP is, regardless of whether they can program anything with it. This is a web application framework, not nursery school. The "option" for PHP use is mentioned in a plethora of locations in Drupal and within modules. And no, if it were not mentioned as a possible option, a newbie would not wonder why the option to enable/disable PageEar on certain pages was not "with" that module. If they had a need for it to show on only certain pages they might submit a feature request though. The ability to selectively choose what pages PageEar appears on is "not" a feature of the original PageEar script, and the commonly understood/used application of a page ear like this "is" on all pages of the site.

I don't know what you mean by "no documentation was 'linked to'"...it's very clear there, right under "Resources," where it says "Read documentation"...now if it ain't PageEar's documentation, what's it doing on the PageEar module page???

I didn't notice that link, noting instead the link in the description at the top of the project page. You are correct about this one. That link should not be there, and should be replaced with a new link to the Handbook page of documentation for the module (which needs to be created). I don't think "that" link is perfectly fine, and now that you pointed it out to me, I agree that "that" link should be changed to Drupal-specific documentation. The other links referencing the same pages though should remain. My bad for missing that one.

Similarly, the PageEar module homepage should say that the Condition module is needed so that you don't get all your webpages page-eared (or none at all). If you download a chat module, do you expect it to stick a chatbox on every single webpage of your site?? So why do you think PageEar is fine with that kind of global on/off behavior?

No, it should not say that Condition module is needed, it should be "recommended" as it currently is (with slight rewording as I mentioned). Condition module adds "additional" optional functionality. Many users would be quite content to use the module in its basic form, and they should not be told they "have" to install an optional module. Also, if unneeded for your specific purposes, you should never enable any modules you don't need, which just adds to the memory footprint of your site, and possibly degrades performance. The ability to selectively choose what pages PageEar appears on is "not" a feature of the original PageEar script, it is an added functionality by the Drupal modules.

What's weirder than these weird situations actually existing is that you and others defend their existence! It's just mind-boggling that people actually think that way...

We have explained to you why things are as they are. I explained why Condition is a separate module, the Drupal way, like it or not. I did not defend the lack of documentation, and in fact within my posts today have essentially completed most/all of the needed documentation for this module. I will choose not to take your words here as a personal attack, though they could certainly be interpreted as such.

Anyhow, I am completely done with this topic. I will check back in a few days to see if you've submitted the documentation that we've figured out here together. If not, I will submit it myself.

I wish you the best.

-- David
absolutecross.com
[new guide/lesson in progress: Creating a CCK and Views powered Drupal site - feedback welcome]

Hee Hee!

fitness trainer - September 1, 2008 - 20:10

I've just created a Handbook book page as per Zirvap's suggestion above at http://drupal.org/node/302741 -- without color commentary! =(

Speaking of which, I'm tired of having to assure you adults here that you needn't take things personally. In future, permit to recommend silent recital of Postel's Law twenty times before taking blood pressure, sahib.

Now, having dispensed with the pleasantries, may I continue with our disagreement:

Yes Condition ("Condtions", "Condition(s)" -- can somebody please make up their mind what the name is, exactly???) isn't technically necessary to get a page-peel effect. However, that can be a little like saying shoes needn't come in pairs because, after all, there are a great very many one-legged people in the world!

I certainly think the PageEar module project page should note that PageEar by itself only acts globally, either over every webpage of the site or none at all, without the addition of the Condition module. Given Drupal's ethos of fine-grained control, such a lack of options seems to really warrant, um, documentation.

Though I suppose I shouldn't be too surprised...did you know that bicycles come without kickstands nowadays? For some reason, the bike manufacturers assume everyone simply lays their bicycles on the floor or against a wall.

The new issue to PageEar has

Keyz - September 1, 2008 - 23:00

The new issue to PageEar has been posted, with the new README.txt: http://drupal.org/node/302793
The maintainer has not been back to Drupal.org since May though, so it is unknown how long it will take to see this in an official release (from his website it appears he's in Hong Kong until next month). At least it is easily found now by those seeking help in the Issue queue for PageEar. If the maintainer doesn't see the new issues and visit within a week, I'll send him a quick email.

There is also an outstanding licensing issue to be resolved with PageEar in the next release. This means it is not permitted for a module to be hosted on Drupal.org if it includes 3rd party code with a non-GPL license. So, that will involve adjusting the README.txt "Setup" instructions to include how to go to the 3rd party website, download the script, and place it in the module's directory. This is common for many license-incompatible modules, such as TinyMCE, FCKEditor, and others. Failing to do this may eventually get the module removed from Drupal.org.

Thank you for making the Handbook page. For future reference, there are some style guidelines that we stick to in writing documentation so that everything is consistent. A few important things to note in this case (please don't take this as being picky - just trying to teach you about how to write Documentation "by the book" haha):

  1. The section this page is posted in is correct. However it would be better to rename the page in the form all the others in the section are... Module name: 3-5 word description of function (and description only if necessary).
  2. Use ordered list HTML when writing numbered steps.
  3. Use > as the separator between menu items when specifying a path (not --> or >>). Surround paths with <em></em> tags.
  4. Include a linked version of the module name, to the project page, so people reading the Documentation can get to the module it is describing (e.g. someone may find that documentation page "before" finding the module's page itself, and thus be unable to click Back to return to the module).
  5. Most commonly, an HTML-formatted, easier to read version of the module's README.txt is included on this page, supplemented with extra info if any is available. Other tips and guides are added on sub-pages, or are added to the HowTo or Tutorial areas of the Handbook. Since the README.txt is done and I already have the HTML-formatted version prepared, please let me know if you'd like me to place its content in place on this page, and move your current content to a subpage, which will show as a link on the page. The module maintainer will probably do this, but we can save him the trouble.

-- David
absolutecross.com
[new guide/lesson in progress: Creating a CCK and Views powered Drupal site - feedback welcome]

!

fitness trainer - September 2, 2008 - 00:36

Wow, licensing issues...hope it gets resolved amicably soon, as this is a neat lil' module when very sparingly applied.

1-5. Sounds complicated, but okay, I'll keep in mind for future reference...and do whatever you think is best WRT what goes where; I don't really know "the system" here for "shelving" things just yet.

I updated the handbook page,

Keyz - September 2, 2008 - 05:55

I updated the handbook page, and also submitted an issue to the Drupal.org webmaster queue to have the Documentation link changed in the absence of the module maintainer. greggles helped out with that immediately and the Documentation link on the PageEar page is now fixed. He also mentioned (as I expected) the licensing issue that needs to be resolved. I assured him that even if the module maintainer does not, I will take care of it. Since this is important to not let get swept aside I'll move up my plan to contact the developer and send an email to him within the next day or so.

On the handbook page, I read more carefully through your original content of the page and felt it would be redundant to include it as-is (since the guide portion is essentially the same guide). I still have a copy of it of course (and it is permanently stored as a revision of the page, which Docs team can always view), so let me know if you'd like to have it. If you're sure you'd like to post it, you can as a subpage, though another Docs team member might delete it down the road if it's seen as a duplicate.

If you would, please submit the Issue I mentioned to you earlier to the PageEar issue queue, regarding the "subtle rewording" for the help text within the module.

Oh and off-topic... I'm sure you've noticed the new Drupal Essential Training DVD/video :) If you're not sure about it, stay tuned for my full review (though not sure when that will be yet).

-- David
absolutecross.com
[new guide/lesson in progress: Creating a CCK and Views powered Drupal site - feedback welcome]

Good Deal!

fitness trainer - September 3, 2008 - 03:14

Uh, okay, not sure what you mean by "submit the issue" regarding the "subtle rewording," but I'll retrace this thread and look into it...but cool, the updated Handbook page looks all nice and, um, "official." ;-) And yeah, I just noticed that Drupal Essential Training thread yesterday and had followed the link...lucky you with your free review copy!! Definitely will buy the DVD when it's released (damn, that's like $500 for Drupal materials this year alone, never mind all the stuff due next year!!) -- and pen my own acerbic review! ;-) Very much looking forward to your observations as well, of course!

Speaking of which...wasn't there some kind of "Miracle Drupal" DVD that was supposed to have been out by now?? I can't remember the exact title but the last time I saw its (sales?) landing page it was delayed again....

Just noticed this thread

Keyz - August 31, 2008 - 21:03

Just noticed this thread, so I'm pasting in my response which I added to fitness trainer's PageEar issue, so others can follow along:
-----

In the PageEar module itself (by default, as installed on its own) there is no Administer > Site configuration > PageEar > Conditions > Criteria, "always validate."

What happened was that you installed the optional add-on module, Condition, and didn't configure that - and as such the "condition" to display anything from PageEar was no longer present. I will grant you that the help text at the top of the page would benefit from a subtle rewording - it was perfectly clear to me, but maybe a newbie would assume it to be a "command" rather than a "suggestion". It would be better for it to say "Install the Condition module if you would like to add additional conditions...", as that would eliminate any hint of confusion.

This is your opportunity now to turn your criticisms of the documentation into action. Submit an issue to this module's issue queue, stating a suggested change to the wording of the help text. It takes no more than that - no one expects you to program anything or roll a patch or anything - just propose the exact wording of the change and why. You can also propose that a readme.txt file be added. If possible write at least some of the text you feel should be in it yourself (even if it has nothing to do with anything besides "This module does [copy and paste description from the project page]. To configure it make sure you go to Such and Such page. If you want to, you can install the _optional_ Condition module from such and such URL to further enhance this module's features." THAT is how you fix the documentation. Start the ball rolling. I expect you to do this - there's no reason not to. If you don't then eventually I or someone will. But there's absolutely no reason you can't. You say you want change - here's one simple and actionable step to begin with. Whenever you do figure something out, learn something, find a spot in documentation that ought to be reworded - do something with that knowledge. Post a feature request, bug report, whatever. This is open source. This is how it works.

I'm guessing you found this link to PageEar install instructions. The PageEar script itself is completely separate from Drupal - it's a generic JavaScript + Flash file that can be used on any website. The Drupal module for it is simply a front-end to the script that integrates it easily with Drupal. The steps for working with a module-based version of an external script are always different from the steps required to use the script in standalone HTML or within other systems.

Here's a basic walkthrough, using the "Requirement: Pages" mode of Condition module, which could also be included in the readme.txt of PageEar (in fact, please do include it):

  1. From the PageEar settings page at Administer > Site configuration > PageEar (admin/settings/pageear), click the "Add a condition first" link from within the "Conditions" fieldset (or if you prefer, go directly to the Condition module settings page at Administer > Site configuration > Conditions (admin/settings/condition) and click the "Add" link).
  2. For the name of the condition, type PageEar.
  3. Expand the "Requirement: Pages" fieldset, and choose either Except on the listed pages or Only on the listed pages, depending on your needs.
  4. If you chose Except on the listed pages, then enter the paths to the pages/sections of your site where you do NOT want PageEar to show up (it will show up then on every unlisted path). Conversely, if you chose Only on the listed pages, then enter paths to the pages/sections of your site where you want PageEar to show up. You can use the wildcard character * to flexibly configure your paths. An example path is user/* which would display PageEar (or not display, depending on the setting) on all user profile pages, such as example.com/user/1.
  5. Press the "Save Configuration" button.
  6. Return to the PageEar settings page at Administer > Site configuration > PageEar (admin/settings/pageear), and expand the "Conditions" fieldset. Change the select menu to the When ALL selected conditions are met option, and select the PageEar condition's checkbox below. Press the "Save Configuration" button. PageEar + Conditions are now successfully configured, and PageEar should now display (or not display) on the paths you have specified.

----

And to continue...

Mind you there is nothing "official" about this module or its documentation. It is a user-contributed module and is solely the responsibility of its creator as well as us, the community, to improve it, document it, etc. It has nothing to do with Drupal core, nor is it in any way remotely Drupal core's fault if it doesn't work, is badly documented, or any other issue. To use an analogy as you're very fond of doing... that's like purposely installing a random 3rd party program on your computer which subsequently causes your system to be unstable or crash, and then laying the blame on Microsoft (or Apple, Linux, etc... all of which, like Drupal core, have matured over the years into a stable, well-documented platform on which other applications can run). The OS maker provided the "framework" for the 3rd party application to function on, but whether that 3rd party application works or not at that point has very little to do with the OS - on the other hand a properly developed program for that platform is stable and works correctly (so if "blame" is to be laid anywhere, it can only be on the 3rd party application, or perhaps on the user if there were clear indications that the application was of dubious quality). I say this only because you often state things about "Drupal's" documentation being inadequate, when in fact Drupal's core's own documentation is fantastic. FANTASTIC. You may not lump the two together. Please refrain from trying to poke holes in my OS/applications analogy instead of seeing what I'm trying to say.

The documentation for non-official Drupal modules ranges from nearly-fantastic in some cases, to dismally bad in others. No one is required to use these unofficial modules - they are offered as a generous, free gift to us by those who take the time to create them and give them back to the community. They may be imperfect though, and doing our part to help fix that is our own responsibility.

-- David
absolutecross.com
[new guide/lesson in progress: Creating a CCK and Views powered Drupal site - feedback welcome]

No

fitness trainer - August 31, 2008 - 22:14

I did not install the Condition module at first. What makes you think I did??

I clearly stated that PageEar wasn't allowing me to specify particular pages to affect, presenting only a global on/off setting.

Then I followed-up, for the record, noting that it was only with installing the Condition module that I was able to create a "condition" that allowed for me to specify which pages PageEar should affect.

As for rectifying the instructions on the PageEar module homepage, yes, I'll be doing that very soon, you betcha. I'm off to the gym now, but will work on "proper" documentation tonight or tomorrow, as my social life allows. ;-)

Now, just to quickly address your point about the "officialness" of things Drupal: yes, I recognize now that something's inclusion on this site does not entail Drupal Association backing (I'm probably Exhibit A for that statement!). It's not clear at first as a newbie; as consumers, even of free products and services, we still expect some kind of a standard of quality. I'd not realized the extent and depth of the plug-n-pray or "garage band" nature of things, but now I do, oh boy do I!

So I do agree with your point, and should have been more careful (and will be) in excoriating Drupal documentation (in the future). ;-) I will no longer call it "official."

The options you speak of are

Keyz - August 31, 2008 - 23:21

The options you speak of are enabled only with the presence of Condition module. They would not appear until you installed Condition module. I installed PageEar not once, but on 2 completely separate copies of Drupal 6 to illustrate this for certain. If the option "somehow" showed up without Condition module installed, and you can reproduce this issue off a completely clean Drupal install, then you should submit a bug report to PageEar module outlining your exact Drupal configuration, steps you took, etc, so that it can be looked into.

  1. Condition options are not present until you install Condition module...
    (screenshot of PageEar settings page immediately after module installation)
  2. So long as Condition module is not yet installed, PageEar works out of the box, instantly, the moment you click "Enable PageEar" and press the "Save configuration" button.
    (screenshot of top right corner immediately after PageEar is enabled)
  3. If Condition module is installed, it now adds an option to PageEar's settings page. PageEar "does" still work at this point, since its settings have not been updated to take Condition module's presence into account. If you just save the PageEar settings as is, PageEar will now disappear from the page corner. Once you configure Condition following the steps I outlined in my other post, PageEar will show again, this time only on the pages you specify.
    (screenshot of PageEar settings "after" Condition module is installed)

-- David
absolutecross.com
[new guide/lesson in progress: Creating a CCK and Views powered Drupal site - feedback welcome]

Hoo's on First, Watts's on Second??

fitness trainer - September 1, 2008 - 20:34

I think the chronology here got screwed up somehow...maybe I have a bug, I dunno (hey, even stranger things have happened with the really buggy Live module). But I did not have the Condition module installed, though there was a Conditions sub-menu on the PageEar settings page.

Anyway, this is becoming another Abbott and Costello Moment. I'll see you at home plate. ;-)

Readme.txt

Keyz - September 1, 2008 - 00:10

Since it was mostly all written, I went ahead and just put this together for the readme.txt (an HTML formatted version can be made for the online documentation page). Please assess it and critique any area that is not understandable enough.
---------------

Description
=========
This module allows you to add a PageEar (also known as Page Peel, Peel Ad, Peel Away or Magic Corner) to your Drupal website.

This is a Drupal implementation of the excellent PageEar by WebPicasso Media:
http://www.webpicasso.de/blog/kostenloses-pagepeel/

Setup
=====
1) After installing PageEar module, proceed to the PageEar configuration page at:
Administer > Site configuration > PageEar (admin/settings/pageear)

2) Enable PageEar by checking the "Enable PageEar" checkbox

3) Choose a 100x100 and a 500x500 image to upload for the PageEar.

4) Customize the additional settings to your preference, and press the "Save configuration" button at the bottom of the page.

Using PageEar with Condition module
==============================

By default, PageEar module will display a PageEar on every page of your site.

The optional Condition module (http://drupal.org/project/condition) can be installed to further restrict when the PageEar should be displayed (e.g. only on specific pages, only for certain roles, only when certain PHP code returns TRUE, etc). After installing Condition module, new options will appear on the PageEar settings page.

Here is an example of the basic steps to configure PageEar + Condition module together, using the "Requirement: Pages" mode of Condition module:

1) From the PageEar settings page at Administer > Site configuration > PageEar (admin/settings/pageear), click the "Add a condition first" link from within the "Conditions" fieldset (or if you prefer, go directly to the Condition module settings page at Administer > Site configuration > Conditions (admin/settings/condition) and click the "Add" link).

2) For the name of the condition, type a name, such as PageEar.

3) Expand the "Requirement: Pages" fieldset, and choose either "Except on the listed pages" or "Only on the listed pages", depending on your needs.

4) If you chose "Except on the listed pages", then enter the paths to the pages/sections of your site where you do NOT want PageEar to show up (it will show up then on every unlisted path). Conversely, if you chose "Only on the listed pages", then enter paths to the pages/sections of your site where you want PageEar to show up. You can use the wildcard character * to flexibly configure your paths.
An example path is user/* which would display PageEar (or not display, depending on the setting) on all user profile pages, such as example.com/user/1.

5) Press the "Save Configuration" button.

6) Return to the PageEar settings page at Administer > Site configuration > PageEar (admin/settings/pageear), and expand the "Conditions" fieldset. Change the select menu to the "When ALL selected conditions are met" option, and select the PageEar condition's checkbox below. Press the "Save Configuration" button. PageEar + Conditions are now successfully configured, and PageEar should now display (or not display) on the paths you have specified.

--------------

-- David
absolutecross.com
[new guide/lesson in progress: Creating a CCK and Views powered Drupal site - feedback welcome]

The Semantics of "Optional"

fitness trainer - September 1, 2008 - 20:22

Well, I'm a bit partial to my own more concise effort at http://drupal.org/node/302741 -- but that's a very good readme.txt, yes. ;-)

My only (very minor) critique is that I believe someone wanting to implement PageEar wouldn't expect its simplistic everywhere/nowhere behavior, so I would make note of this fact at the very beginning, instead of later on on what would appear to be an "optional" addendum.

What's a life without smiles?

What's a PageEar without Drupalistic fine-grained control?

Anyway...while you're compiling instructions there, how about some for this situation, my friend: how to control the PageEar effect such that it is only displayed to the same IP address the first three or four visits? Don't want to forever annoy anyone with something crawling on the corner of their screen!

Would you like it if the

Keyz - September 1, 2008 - 20:38

Would you like it if the following line were added, very near the top of readme.txt? I have included the preceding line, to show where I intend to place the new line.

Since, as mentioned, PageEar works out of the box (if yours does "not" for some reason then that's a bug report to file, not a qualification to be added to documentation), this readme will not say that it "displays either on every page or no page at all" - it simply displays on every page.

----

This is a Drupal implementation of the excellent PageEar by WebPicasso Media:
http://www.webpicasso.de/blog/kostenloses-pagepeel/

By default, once enabled on its settings page, PageEar module will display a PageEar on every page of your site. If you need to control which specific pages or sections of your site should receive a PageEar instead of all pages, see instructions below on installing and using the Condition module, which will enable you to precisely control which pages/sections of your site will have a PageEar added.

Please let me know if this clarifies the optional "need" for Condition module, and I will submit this readme.txt for inclusion in the next available release of PageEar module.

-- David
absolutecross.com
[new guide/lesson in progress: Creating a CCK and Views powered Drupal site - feedback welcome]

Yes, Thanks

fitness trainer - September 1, 2008 - 21:31

That statement really would have clarified things for me a whole bunch. Much appreciated!

Now, if you have any ideas about how to control PageEar such that it only displays no more than three times to any one IP address.... ;-)

how to control the PageEar

Keyz - September 1, 2008 - 20:48

how to control the PageEar effect such that it is only displayed to the same IP address the first three or four visits? Don't want to forever annoy anyone with something crawling on the corner of their screen!

I don't know off the top of my head. This is quite a bit more complicated than the simplistic condition of showing on these pages but not those pages. This is likely something that can be done by pasting some pre-written (to be included in the readme.txt) PHP into a condition preset in Condition module. Or, a feature request can be made to integrate functionality like this into the module itself and avoid any pasting of PHP (I think to Condition module... whereby another fieldset might be made available that offers a few options to choose from, such as a number of visits to pages of the site before the condition becomes false instead of true. Again, this is programming/module-development territory, not my forte).

-- David
absolutecross.com
[new guide/lesson in progress: Creating a CCK and Views powered Drupal site - feedback welcome]

Ah, Okay

fitness trainer - September 1, 2008 - 21:34

I was just wondering whether the Condition module already had some settings which, when toggled appropriately, could achieve the desired effect...I'll ask over at the Condition module issue/request queue(s)....

Thanks again. This has been most productive, and I thank everyone for their patience when mine runs out!

Sorry guys, despite all of

jasonfnorth - December 7, 2008 - 08:35

Sorry guys, despite all of your hard work in sorting out documentation, I get NOTHING.

I followed the instructions exactly, and no Page Ear. :-( I've tried it without CONDITIONS installed, with CONDITIONS installed and configured for ALWAYS. I've tried 5 different themes to assure it isn't my theme. I've tried my own jpegs, and the stock jpegs. I've tried the current PageEar release, and the dev version. Regarding my installations, I've tried putting the PageEar module into drupa>Sites>All>Modules, and installing it from there, with no results, and then I removed it, and tried putting PageEar in drupal/modules and installing it from there... also no results. I've tried Firefox 3.0.4, and IE 7.

I'd pay someone to help me get this going!

The same with me

Munkas - July 8, 2009 - 12:03

I also tried EVERYTHING described above and Page Ear is still NOT working.

Any help would be appreciated.

Got page EAR skills? :D

jasonfnorth - December 8, 2008 - 10:12

Got page EAR skills? :D

 
 

Drupal is a registered trademark of Dries Buytaert.