Document the flexifilter module

[GoogleCodeExporter]

The flexifilter module is a key module for site builders who want to create
highly custom filters. However, there are no documentation pages on it in
the Drupal handbooks, potentially making it difficult to use for new users.
Your task will be to create five documentation pages for it. You should
checkout CVS HEAD from the repository and become familiar with the module.
These are the five desired pages:

Page 1: Overview

On this page, you should give an overview of the module: what it does, how
it's useful, etc.

Page 2: Terminology

Here, you will define the basic terms of flexifilter, such as components,
conditions, flexifilters, and chunks.

Page 3: Step-through tutorial

Here, you will give a step-by-step tutorial on how to create a flexifilter.
You should assume that the user has absolutely no idea on how filters work
or anything of the sort. You should mention ways to keep
flexifilter-defined input formats secure.

Page 4: Example flexifilters

Here, you should give at least five examples of filters you can make with
the flexifilter module, and at least two step-by-step explanations of how,
exactly, to create them. If this spills out onto some sub-pages, that's fine.

Page 5: API documentation

Here, you will list useful API functions that the flexifilter module
provides, and will show module writers how to code for flexifilter. You
should mention flexifilter's hooks and at least three nice API functions to
use.

Note:

You should be working off Drupal 6 HEAD, as this contains the latest API
features, etc.

Resources:

Flexifilter module (http://drupal.org/project/flexifilter)
Article on the introduction of flexifilter
(http://cwgordon.com/introducing-flexifilter)
Dojo lesson on flexifilter (http://drupaldojo.com/lesson/flexifilter-module)

Mentor:

dmitrig01

Deliverables:

5 (or more) handbook pages, approved by the mentor, dmitrig01.

Original issue reported on code.google.com by cwgord...@cwgordon.com on 14 Jan 2008 at 3:28

[GoogleCodeExporter]

We still need a drupal.org issue to go along with this task.  But the task 
itself is
open.

Original comment by acli...@gmail.com on 14 Jan 2008 at 12:08

• Changed state: Open
• Added labels: Documentation
• Removed labels: Priority-Medium, Type-Defect

[GoogleCodeExporter]

I claim this task.

Original comment by birdman...@gmail.com on 21 Jan 2008 at 12:33

[GoogleCodeExporter]

Ok birdmanx35, it's yours.

Original comment by acli...@gmail.com on 21 Jan 2008 at 12:47

• Changed state: Claimed
• Added labels: ClaimedBy-birdmanx35, DueDate-2008-01-27

[GoogleCodeExporter]

Also, I'm a bit worried about the whole API thing (can't code, really), so I'd
appreciate it if I could get some help on that when the time comes. Just a 
heads-up.

Original comment by birdman...@gmail.com on 21 Jan 2008 at 12:54

[GoogleCodeExporter]

Just created a documentation profile placeholder at 
http://drupal.org/node/212410.

Can someone create a d.o. issue for this?

Original comment by birdman...@gmail.com on 21 Jan 2008 at 4:40

[GoogleCodeExporter]

Please post all work to the d.o issue at:
http://drupal.org/node/212512

Original comment by acli...@gmail.com on 21 Jan 2008 at 12:18

• Added labels: DrupalIssue-212512

[GoogleCodeExporter]

I just wanted to check in and see how this task is coming along.  Could you 
please
post the progress you've made so far to the issue for this task on drupal.org 
please,
so we can make sure you're on the right track.

Now that it's too late to claim another issue, we'll allow you to work on this 
task
until the final deadline of midnight PST on Feb. 4, 2008.  However, tasks must 
be
*reviewed* by this deadline as well, so it would be great if you could get your 
work
to us as soon as possible so we can start the review process.

Thanks

Original comment by acli...@gmail.com on 26 Jan 2008 at 3:50

[GoogleCodeExporter]

Hi Aclight. Life has been crazy lately, so I haven't gotten to this yet. I plan 
on getting a lot done this weekend, so 
I'll send updates when I have them.

Original comment by birdman...@gmail.com on 26 Jan 2008 at 4:19

[GoogleCodeExporter]

dmitrig01 just said that I could provide code exports for the examples, instead 
of
tutorials, as that is redundant. Just an update.

Original comment by birdman...@gmail.com on 28 Jan 2008 at 12:21

[GoogleCodeExporter]

Okay, I'd say I've done roughly 70% of the work now. I will get this work done 
on
time, and with enough room for it to be reviewed. I still need to do most of the
examples (which dmitrig01 said, after a discussion, that I could do just a code
export because it is redundant to do a tutorial when there is already a 
tutorials
section) and the tutorial.

http://drupal.org/node/212413 - The overview has been created, and I've done a 
bit
more than what the task requires, as that information is useful and easy to add.

http://drupal.org/node/212414 - The glossary has also been created, and 
dmitrig01 can
be credited for that great image.

http://drupal.org/node/212417 - The examples that require no work on my part 
have
been created- I still don't really grok flexifilter, so I have to sit down with 
it at
some point and create these examples. If someone has an export of any of the
examples, or another one, that would be beautiful, allowing me to spend more 
time on
the meat, the tutorial.

http://drupal.org/node/212419 - The API actually turned out to be the easiest 
part,
as most of the documentation was already done in the API.txt file. I improved 
on the
phrasing a little bit, I think, but that was about it.

As I said earlier, I haven't started the tutorial because that will take as 
much time
as the above four have taken me. I also still need to do the examples, as I've 
said
before. Sorry for being redundant, I'm tired and I need a to-do list.

Let me know what you think.

Original comment by birdman...@gmail.com on 28 Jan 2008 at 2:38

[GoogleCodeExporter]

Marking Needs Review.

Original comment by webchick...@gmail.com on 31 Jan 2008 at 10:56

• Changed state: NeedsReview

[GoogleCodeExporter]

This is not done yet, however a good portion is, so reviewing is good.

I'll get this finished on Saturday.

Original comment by birdman...@gmail.com on 31 Jan 2008 at 11:06

[GoogleCodeExporter]

Some notes. This is a very good start, but the documentation needs some 
scrubbing.
(You probably know that, from the comment above, so consider this a practical 
guide.)

http://drupal.org/node/212410

 -- At the very start, please define what Drupal filters are.

 -- "to further improve" is redundant.  Use "to improve."

 -- Drupal GHOP has no context here.  Link?

http://drupal.org/node/212414

 -- "Chunk grab on [ and ]" is confusing.  The chuck is not defined by the word AND
in the text string.  It is defined by the brackets, right?  So this should be 
"Chunk
defined by [bracket text]"

http://drupal.org/node/212417

-- Please describe the import/export process at the beginning.  Where do I 
import
files?  Through the UI?  What is the menu path?  Admin > Content > Flexifilter?

-- "If you wish to use them in your module, import them manually with 
Flexifilter,
and then export them."  This is confusing because the first sentence is about 
using
Flexifilters as Filters.  This is about using them as module code.  There should
probably be two sections of the documentation: Using Flexifilters and 
Implementing
Flexifilters into Modules.

-- "Link Formatting" is blank.

-- "Swear Filter" is blank.

http://drupal.org/node/212419

-- "hook_flexifilters allows modules to define default flexifilters. A array 
should
be returned, with each value of the array corresponding to an exported 
flexifilter
(as an array itself)."  I have no idea what this means.  What format is the 
array in?
 What are its keys?  Its required elements? Its allowed values?

-- "hook_flexifilter_components" text block needs to be formatted for easy 
reading on
this screen.  A sample return array should be added.

-- Sample for "hook_flexifilter_conditions" also.  What is the difference 
between
this hook and the other?  Why do I use each one?

-- "Useful API Functions" are not documented meanigfully.  What is $op?

-- Page ends in the middle of a sentence.

http://drupal.org/node/212416

-- "This is the tree" -- no, this is a page with links on it.

http://drupal.org/node/217228

-- How do I find the Flexifilter administration area?

http://drupal.org/node/217177

-- Give this list a header, like the related page has.

-- How do I find the Flexifilter administration area?

Original comment by agentric...@gmail.com on 3 Feb 2008 at 4:41

[GoogleCodeExporter]

Yep, I have a couple of things to do on the Examples today, and I'll use your 
suggestions. Thanks!

Original comment by birdman...@gmail.com on 3 Feb 2008 at 5:06

[GoogleCodeExporter]

Okay, I implemented some of your suggestions, but not all of them.

I'm almost 98% done with the task- just need to do the link filter (I'm a tad 
stuck
without dmitrig01, who is afk atm) and then I'll be done, so CNR.

Original comment by birdman...@gmail.com on 4 Feb 2008 at 12:41

[GoogleCodeExporter]

This is now 100% done. Feel free to review/close!

Original comment by birdman...@gmail.com on 4 Feb 2008 at 1:15

[GoogleCodeExporter]

Attached is the work done.

Original comment by birdman...@gmail.com on 4 Feb 2008 at 2:16

Attachments:

• flexifilterdocs.zip

[GoogleCodeExporter]

Great job.  This was +1ed in IRC, so I'm closing it up.  Thanks for your hard 
work.

Original comment by acli...@gmail.com on 4 Feb 2008 at 2:22

• Changed state: Closed
• Added labels: AdminChecked