Improve Wysiwyg API installation instructions [#485264]

First, let me say I'm willing to help with documentation.

Now that the editors go in sites/all/libraries, what are the implications for people upgrading? That information needs to be included on the installation handbook page: http://drupal.org/node/371459. In addition, the examples there now show the old path structure, so that needs to be changed too.

I thought the writer of the handbook page did a great job in trying to write, abstractly, how the external editor files should be placed into the file structure. But even though I read those excellent instructions over many times, I did not get it right with Tiny MCE. After I unzipped Tiny MCE i took out the tiny_mce directory under the jscripts directory and put it like: sites/all/libraries/tiny_mce. Wrong. With trial and error I got to the right answer was: not to mess the downloaded file at all except to change the outmost wrapper's name to: tinymce. So the right directory structure ends up being: sites/all/libraries/tinymce/jscripts/tiny_mce.

I think this is a situation where trying to write abstracted instructions to cover all cases will often lead to user frustration. I think it is probably better to just write out the specific instructions for each editor, even if it gets repetitive.

As I said, I'd be willing to help.

Shai Gluskin
Content2zero
I'm sgluskin on Twitter

Comment	File	Size	Author
#3	wysiwyg-HEAD.install-instructions.2.patch	3.63 KB	sun
#2	wysiwyg-HEAD.install-instructions.patch	2.99 KB	sun

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

sun

German

Karlsruhe

CreditAttribution: sun commented 8 June 2009 at 17:23

Title:	Updating the Excellent Wyiwyg Installation Handbook Page	» Improve Wysiwyg API installation instructions
Category:	bug	» task

Good catch! I did not write that page, so I already forgot that it existed. ;)

It seems we have to tackle several issues here:

Users have to create sites/all/libraries to begin with.
This should probably NOT be part of the editor installation, but the overall Wysiwyg API installation (first chapter)?
Regarding the directory structure, resp. where to extract/copy/place an editor library, you're right - that is probably not easy to understand when doing it for the first time. But I think that - once you understood how it should be done - it's pretty straightforward. An example for an arbitrary editor library probably would not hurt, but I think the generic description is very valuable to have.
I have seen other handbook pages that additionally use screenshots of directory structures (mostly using Windows Explorer) - do you think that would help?

Technically, I think we could additionally add the actual library location to the on-site installation instructions. Based on your example:

TinyMCE (Download)                                                           Not installed.

Extract the archive and copy its contents into a new folder in the following location:

sites/all/libraries/tinymce

So the actual library can be found at:

sites/all/libraries/tinymce/jscripts/tiny_mce/tiny_mce.js

If you think that this would help, I would try to achieve that.

Comment #2

sun

German

Karlsruhe

CreditAttribution: sun commented 8 June 2009 at 17:36

Status:

Active

» Needs review

File	Size
wysiwyg-HEAD.install-instructions.patch	2.99 KB

Attached patch implements 4. The wording could probably use some tweaking though.

Comment #3

sun

German

Karlsruhe

CreditAttribution: sun commented 8 June 2009 at 17:52

File	Size
wysiwyg-HEAD.install-instructions.2.patch	3.63 KB

- Also display installation instructions for an editor in case of an error.

- Always uncollapse the installation instructions if there are either no editors installed, or at least one editor is not installed properly.

Comment #4

Shai CreditAttribution: Shai commented 8 June 2009 at 18:51

Wow, you moved on this so quickly! Thanks.

One tweak would be to say explicitly, The TinyMCE zip file will expand to a directory named something like, "tinymce_3_2_4_1" (where the numbers refer to the downloaded version). Rename that directory to, "tinymce". Then place that directory into sites/all/libraries so that the resulting structure is sites/all/libraries/tinymce.

In that case you don't even need to mention jscripts/tiny_mce because they don't need to bury their noses past the directory it comes in. When I did it, I misinterpreted the instructions which warned against having the editor directory nested in another directory by its same name. I pulled tiny_mce out of the rest of the package. But I think with these instructions being more explicit about what to do with the downloaded package, it might be more confusing to paint the whole path down to the tiny_mce level. I could go either way on that.

Thanks.

Shai

Comment #5

sun

German

Karlsruhe

CreditAttribution: sun commented 8 June 2009 at 19:03

Hm. We can't provide explicit per-editor instructions, because the packaging process of those libraries may change (while the structure will likely keep the same). I.e. TinyMCE may be packaged in a sub-folder called "tinymce_3_2_3_1" now, and markItUP may be packaged in a sub-folder called "latest" now, but we don't know if or when those developers will decide to change their packaging process (which would make sense in both cases). Some editors come nicely packaged in a sub-folder that is named exactly the way we need it.

Comment #6

Anonymous (not verified) CreditAttribution: Anonymous commented 8 June 2009 at 19:20

Status:

Needs review

» Reviewed & tested by the community

Comment #7

Anonymous (not verified) CreditAttribution: Anonymous commented 8 June 2009 at 19:21

Knowing where a specific file should be found is helpful and also allows for the possibility that an editor may change their own configuration.

Comment #8

TwoD

Swedish

Sweden

CreditAttribution: TwoD commented 8 June 2009 at 19:25

Status:

Reviewed & tested by the community

» Needs review

We might not need explicit instructions per editor, but a single example would be nice, as it is a bit confusing sometimes.
A note stating that "Anything below the top folder of the editor package should rarely be changed as Wysiwyg API expects this directory structure to stay intact." should further indicate people do not need to mess with any files or folders in there.

Or simply include a link to this or similar issues where it's discussed hehe.