TextBook

From Textbook

This is a takeoff from the idea that sprouted here. This is not meant to replace the textpattern.org's Plugins section, but rather to supplement it where it has limitations, such as with the expansion and internationalization of plugin documentation.

If you see that a plugin is missing or needs updated to the latest version, please take it upon yourself to add it. Same goes if you see a mistake in the table, please fix it. If you need a TextBook account, please get one.

One more thing, as any smart web site owner should know, using plugins (however great they are) means you are willing to deal with any unexpected problems that might come with them. Sometimes plugins are new and buggy. Sometimes plugins are abandonded. Sometimes plugins don't work with new releases of Txp. Sometimes plugins are the cause of site security breaches. Sometimes plugins (depending on how they are developed) can get you into trouble with your Web host. You get the idea. Nevertheless, an effort is made to keep these tables representative of viable plugins, and are designed to provide you with all the relevant links to get help should you need it.

Contents 1 Plugin Tables 2 Table Editing Instructions 2.1 Table Specific Instructions 2.2 Common Instructions 2.2.1 Adding New Plugin Rows 2.2.2 Updating a Plugin Version 2.2.3 Retiring a Plugin (a plugin row)

Plugin Tables

• Plugins Alphabetical by Name
• Plugins Grouped by Purpose

Table Editing Instructions

First thing to note: Do not add any plugins to the tables that do not work with the current release of Textpattern!

Below are the rest of the instructions for adding to--and upkeeping--the plugin tables.

Table Specific Instructions

1. For the table, Plugins Alphabetical by Name, add new rows in alphabetical order by the plugin name.
2. For the tables, Plugins Grouped by Purpose, add new tables, or table sections, as necessary in a given group category. Add a new category if needed. For each table, add plugin rows to the relevant group, and then alphabetical by plugin name in the group.

Common Instructions

Following are instructions common to all tables. For easier handling, it is suggested you first apply the instructions to the Alphabetical by Plugin Name table, then simply copy/paste that row into the appropriate Group by Purpose table (mind the row colors).

Adding New Plugin Rows

1. Plugin Package or Not: If your plugin is more than a single text file or relies on other third-party applications, players, etc. then please package all the relevant components needed into a single zip file to be uploaded here in TextBook. (Mind copyright policies of respective products!)
2. Plugin Name: Make the plugin name a link to the article write-up at the plugin author's Website. Because this is an external link, you will use the following wiki syntax:

   [http://domain.tld/article-title Article Title]

   (note the space between the end of the URL and the link label) which gives the little arrow indicating external. If no such write-up exists, then use the author's name in the second column (not the plugin name) to add a link to the author's Website home page. If no Website exists at all, don't add any links in the first two columns!
3. Plugin Description: For the description, use the description that comes with the plugin, or revise it a little if you think it needs it. Don't go overboard; short and clear is what we want for the table. You can add detailed descriptions in the "documentation" links.
4. Uploading Plugin Files: Use TextBook's Special:Upload feature to upload either a .txt file, .zip file, or both (recommended where relevant). For each file you upload, name it using the convention of plugin name plus version number with the appropriate extension. For example,

   plugin_file_name-n.n.tld

   where "plugin_file_name" is the name of the plugin file, "n.n" is the plugin file version, and ".tld" is the file extension (either .txt or .zip); e.g., ajw_clean_feed-0.2.txt. When asked for a file description in the upload process, at the very least add "Plugin file," though a sentence about the plugin would be better. (Note: the wiki automatically makes the first character of the file name capitalized and loads these files into the "images" directory. There's no getting around either situation, so don't get confused nor go on a rampage--just ignore it.) If you uploading a zip file, you may see a warning that the "image" file is exeeding a recommended max byte size. Just ignore this message and upload anyway.
5. Linking Files in Table: Your files will be linked in the "Current" section of the plugin tables (be sure to notate the current plugin version too). There's a place for text files and a place for zip files; you only need to use one or the other. In the cell not used, add two dashes. Links use wiki syntax, which keeps code cleaner. The syntax will be exactly the same for each file type except you will changes the file extension as needed. Following is an example of the syntax to use for each link:

   [[media:plugin_file_name-n.n.txt|txt]]

   [[media:plugin_file_name-n.n.zip|zip]]

   again where "plugin_file_name" is the actual file name, and "n.n" is the version number.
6. File Management Link: Next to the link(s) just added, add the following link syntax:

   ([[:image:plugin_file_name-n.n.tld|man]])

   (note the beginning colon is necessary) and again replace "plugin_file_name," "n.n,", and ".tld" with the corresponding information. This will add a link to the edit page for the file where it can be replaced, edited, or deleted altogether; it's a nice file management feature the wiki provides (man=manage).
7. Documentation: For the Documentation field, create a new link using the following wiki syntax

   [[Docs for plugin_file_name Plugin|yes]]

   where "plugin_file_name" is the actual title of the plugin (important: do not add the version number in this case, just the plugin title only!). What this will do is create a new wiki page with the descriptive title, but show it as a link in the tables as "yes". Then follow the link (it will appear in red text) and add whatever kind of documentation you want to the page. This doesn't have to be the documentation that comes with the plugin (but can certainly include that), but might also be additional examples of use by commumity members. Anything that would help users understand the plugin better. Images too for that matter could be upload and embedded in the documentation page. If you do start content on the documentation page, copy the code for the breadcrumb navigation at the top of this page and paste into the top of the new documentation page.
8. Forum Thread: If the plugin has a Textpattern Support Forum thread started for it, provide the thread ID number and make it a link to the associated thread. Use the external link syntax:

   [http://forum.textpattern.com/viewtopic.php?id=xxxxxx xxxxxx]

   where "xxxxxx" is the forum thread ID number.
9. .org: This is meant to be a link to the plugin's entry (if one exists) at textpattern.org. Table fields currently indicate using "ID#" as the link label, which implies a plugin's article ID number, respectively. However, if ID numbers are not easily known, simply use the word "go" as a link to the destination article.
10. PayPal: If the author has a paypal account and accepts donations for the continued maintenance and improvement of their plugins, the author can provide a PayPal button that exactly reads "donate" to this field. Plugin authors are encouraged to add their buttons to support their work, and in return to help keep their plugin files in the archive updated.

Updating a Plugin Version

1. Leave the old plugin file that's archived in the wiki alone; in other words, don't change the name, don't delete it, etc.
2. Upload a new file (txt, zip, or both) with the new version name as described in step #3 above.
3. Begin editing the row in the Plugins Alphabetical by Name table first (as described in next step).
4. Change the file link values in the appropriate cells in the "Current" columns so everything points and reflects to the lastest file version you just uploaded.
5. Copy the newly updated row and paste it in the relevant Plugins Grouped by Purposes tables after. This will save you having to make manual edits twice. (Though you may need to adjust the row colors; just switch the row classes "eveno" and "oddo" accordingly.)
6. Finally, follow one of the "yes" links under the "Docs" column in any of the updated rows (the links all go to the same place) and add a link entry under a "Previous Versions" section that points to the previous version files in the wiki (like what used to be the current links in the table before). Note: the "Docs" page may be blank, that's fine, it means you're the first to save anything there. Go ahead and do so.

Retiring a Plugin (a plugin row)

1. Should a plugin ever go defunct or get integrated into Txp, do not delete the table row, instead, strike out the entries in the row fields so it's clear that it's no longer alive, and maybe replace the comments with an explanation of what has happened.
2. Perhaps after some time, and if even needed, we can start a new wiki page that lists retired/integrated plugins so that new developers can reference what is NOT needed in terms of plugins.

Search TextBook