| 1 |
Simplelist Developer Documentation
|
| 2 |
----------------------------------
|
| 3 |
I've tried to make extending simplelist fairly simple, but there are some details to go over. First off, to extend simplelist
|
| 4 |
you're going to need to write either a Filter or a Display class. (Well, or both, but that's just a+b.)
|
| 5 |
|
| 6 |
To understand how the module fits together, let me do a quick diagram:
|
| 7 |
|
| 8 |
--------------------------
|
| 9 |
' '
|
| 10 |
--<<-----' Controller Class '<<-----
|
| 11 |
// ' (SimpleListController) ' \\
|
| 12 |
1. Requests data from --------------------------- 4. Returns HTML to
|
| 13 |
// ^^ \\ \\
|
| 14 |
VV 2. Returns data to \\ \\
|
| 15 |
------------------------ // \\ ---------------------------
|
| 16 |
' ' // 3. Gives data ' '
|
| 17 |
' Filter Class '--->>-- to format---->>' Display Class '
|
| 18 |
' ' ' '
|
| 19 |
------------------------ ---------------------------
|
| 20 |
|
| 21 |
When a simplelist is requested (by either a menu item for a page or hook_block for a block), the controller class is
|
| 22 |
created and loads the simplelist data from the database. Then it creates a filter class based on the simplelist table's
|
| 23 |
filter_name field and passes it the simplelist data that it needs to create an array of data via the class' 'get_node_data'
|
| 24 |
method. Currently all the filter classes return nodes, but they just needs to return an array.
|
| 25 |
|
| 26 |
Once the array is returned, the controller creates the appropriate Display class based on the simplelist_display's
|
| 27 |
display_name field, and passes the array to it (with the simplelist data) via the class' 'render' function. The rendered
|
| 28 |
HTML is then passed back to the controller, which either returns it to the page or packages it up into the block data.
|
| 29 |
|
| 30 |
Thusly, to expand simplelist to do something different, you just need to create a new Filter and Display class based on the
|
| 31 |
SimpleListFilterParent or SimpleListDisplayParent. Once you've created the class and the supporting hooks, the controller will
|
| 32 |
use it just like any other class.
|
| 33 |
|
| 34 |
How to make a new Filter:
|
| 35 |
-------------------------
|
| 36 |
To make a new filter, you need to create two things. First is a module file that implements hook_simplelist_filter_info (and
|
| 37 |
possibly hook_simplelist_filter_require), and the second is a class that inherits from SimpleListFilterParent. (And the third is
|
| 38 |
simpletests!)
|
| 39 |
|
| 40 |
But first, you need to figure out where you want to store the filter's parameters. A filter could have very simple parameters
|
| 41 |
- for instance, a filter that only displays nodes created in the last n days would only have a parameter for the number of days,
|
| 42 |
a sort order and direction. However much data you need, you can write it to two places, either encoding it into the filter_data,
|
| 43 |
sort_name, and sort_data fields, or creating a new table in your module's install file and writing to that. Either will work,
|
| 44 |
although for simple amounts of data serializing to form_data (such as in SimpleListFilterNodeByUser) will work fine.
|
| 45 |
|
| 46 |
Hook_simplelist_filter_info needs to return an array of arrays, one internal array for each filter class you're implementing.
|
| 47 |
The array should have three items with specific keys - 'name' is a the name of the class you're implementing. 'title' is the
|
| 48 |
english name of the class to display to the user - don't forget to use t(). 'provides' indicates what type of object you're
|
| 49 |
returning. If it's a node, use 'node', if it's a comment, use 'comment', if it's a term, use 'term', for a user use 'user'.
|
| 50 |
(Currently there's not a ton of support for this, but I want to figure some out.)
|
| 51 |
|
| 52 |
Hook_simplelist_filter_require doesn't return anything - it just contains the require_once() calls for each of your classes.
|
| 53 |
Once something calls hook_simplelist_filter_require, all of your filter classes should be loaded by php. If you were to put your
|
| 54 |
filter class inside of your module file, then you wouldn't need to implement this hook at all.
|
| 55 |
|
| 56 |
The filter class you write needs to override these five functions:
|
| 57 |
|
| 58 |
get_node_list($simple_list, $count, $offset, $paged)
|
| 59 |
$simple_list is an object containing the various fields in the simple_list table,
|
| 60 |
with node types stored in ->node_types as an array and terms in ->terms as an array.
|
| 61 |
$count is an integer containing how many items to return.
|
| 62 |
$offset is an integer containing the start point for this query. (Think db_query_range($query, $offset, $count).)
|
| 63 |
$paged is a boolean - if true, we're expecting you to call pager_query instead of db_query_range.
|
| 64 |
|
| 65 |
And what it should return is an array of whatever your filter returns. Generally that's nodes, but it could be comments.
|
| 66 |
Keep in mind that you're going to be sorting the data as well.
|
| 67 |
|
| 68 |
The next four are all static functions:
|
| 69 |
|
| 70 |
get_filter_form($simplelist)
|
| 71 |
$simplelist is an object containing the various fields in the simple_list table.
|
| 72 |
|
| 73 |
And what it should return is a form array containing fields you need the user to set to configure your filter. Note that
|
| 74 |
aside from the autocomplete option, all of the fancy options having to do with special javascript aren't going to work - this
|
| 75 |
is a limitation on how the form elements are loaded via AHAH. (Autocomplete works because I'm specificly forcing the javascript
|
| 76 |
file for autocompletes to load on the page.)
|
| 77 |
|
| 78 |
Every filter class has a caching engine for nodes, intended to keep the overhead from node_load low. So, do a query to get a
|
| 79 |
list of your node ids, and then use each nid with $this->caching_engine->fetch_node($nid). The engine will handle the cache for
|
| 80 |
you, and you'll get back a node object, fully loaded.
|
| 81 |
|
| 82 |
get_filter_form_validate(&$form, &$form_state)
|
| 83 |
$form is the form array for the simplelist.
|
| 84 |
$form_state is the standard form_state array.
|
| 85 |
|
| 86 |
This is just a standard validate function, really. Check over the values that were set in the fields you specified in get_filter_form(),
|
| 87 |
and use form_set_error() if you've got any problems.
|
| 88 |
|
| 89 |
get_filter_form_submit($form_id, &$form_state)
|
| 90 |
$form_id is the usual form id.
|
| 91 |
$form_state is the standard form_state array.
|
| 92 |
|
| 93 |
This too is a standard submit function. The simplelist id is stored in $form_state['values']['slid'], because even if this
|
| 94 |
is a new simplelist, by the time this function is called the basic data has already been written.
|
| 95 |
|
| 96 |
I recommend that you write the form data to the filter_data field in the simplelist table - pack a stdClass object or an array,
|
| 97 |
and serialize it to the field. Additionally, sort information should be written to sort_name and sort_data, although most of the
|
| 98 |
time sort_data is 'ASC' or 'DESC'.
|
| 99 |
|
| 100 |
clear_existing_settings($slid, $form_id='', &$form_state=NULL);
|
| 101 |
$slid is the simplelist id for the simplelist you're cleaning.
|
| 102 |
$form_id is the form id.
|
| 103 |
$form_state is the form_state array.
|
| 104 |
|
| 105 |
If someone is editing an existing simplelist and changing their filter from this one to another one, this is the function where
|
| 106 |
the module asks for you to clean up the data you've written. So, for instance, if you've written data to the filter_data of the
|
| 107 |
simplelist, you would include the line:
|
| 108 |
|
| 109 |
db_query("UPDATE {simplelist} SET filter_data = '' WHERE slid = %d", $slid);
|
| 110 |
|
| 111 |
which would remove that data.
|
| 112 |
|
| 113 |
How to Make a new Display:
|
| 114 |
--------------------------
|
| 115 |
|
| 116 |
To make a new display, you need to create a module that implements hook_simplelist_display_info, possibly implements
|
| 117 |
hook_simplelist_display_require, create a module that inherits from SimpleListDisplayParent, and finally don't forget to
|
| 118 |
write your simpletests.
|
| 119 |
|
| 120 |
Storing your display parameters is a little trickier than with filters - although there are a few fields for common display
|
| 121 |
parameters like the number to show or the path, there isn't a standard field to write data to. So, if you need to store more
|
| 122 |
than what I provide you'll need to define your own extra table in the install file of your module.
|
| 123 |
|
| 124 |
hook_simplelist_display_info returns an array of arrays, each inner array describing one of your display classes. The three
|
| 125 |
required keys are 'name' - with the value being the name of your display class; 'title' - with the value being the human-readable
|
| 126 |
name of your class, for display to the admin; and 'accepts' - with the value being the type of objects it's expecting to recieve.
|
| 127 |
Current expected values are 'node', 'comment', 'term', and 'any' - if you think your class can handle whatever it's passed, 'any'
|
| 128 |
indicates that. There currently are no support for requiring that the display match what the current filter provides, but I'm
|
| 129 |
planning for it.
|
| 130 |
|
| 131 |
hook_simplelist_display_require returns nothing, and once it's been called, I expect that all of your display classes have been
|
| 132 |
included with require_once or the like. If the classes you're defining are already included - for instance, if you include the
|
| 133 |
class in the module file - then you don't have to implement this hook.
|
| 134 |
|
| 135 |
To create a new display class, first create a class that inherits from SimpleListDisplayParent. Once you've created it, you'll
|
| 136 |
need to override the following five methods:
|
| 137 |
|
| 138 |
render($simple_list, $node_array);
|
| 139 |
$simple_list is an object loaded with simplelist settings
|
| 140 |
$node_array is an array of objects, most often nodes.
|
| 141 |
|
| 142 |
This function takes a simplelist and an array of objects, and returns an html block of those objects. You could think of it
|
| 143 |
as a generalized theme function, and it's important to wrap whatever you're doing with the nodes with theme functions. You can
|
| 144 |
always use the standard simplelist node theme function as follows:
|
| 145 |
|
| 146 |
theme(array("simplelist__$simple_list->name", "simplelist"), $node, $simple_list);
|
| 147 |
|
| 148 |
The display data from the simplelist_display table for the type of display you're doing is set in $simple_list->display,
|
| 149 |
so for instance the display format field is in $simple_list->display->display_format.
|
| 150 |
|
| 151 |
get_display_form($simplelist, $format='block')
|
| 152 |
$simplelist is an object loaded with simplelist settings
|
| 153 |
$format is either 'block' or 'page', and indicates which kind of display is being set up.
|
| 154 |
|
| 155 |
This function returns a form api array that describes the settings the user can make for this display. Note that
|
| 156 |
aside from the autocomplete option, all of the fancy options having to do with special javascript aren't going to work - this
|
| 157 |
is a limitation on how the form elements are loaded via AHAH. (Autocomplete works because I'm specificly forcing the javascript
|
| 158 |
file for autocompletes to load on the page.)
|
| 159 |
|
| 160 |
get_display_form_validate(&$form, &$form_state)
|
| 161 |
$form is the form array for the simplelist.
|
| 162 |
$form_state is the standard form_state array.
|
| 163 |
|
| 164 |
This is just a standard validate function, really. Check over the values that were set in the fields you specified in get_display_form(),
|
| 165 |
and use form_set_error() if you've got any problems.
|
| 166 |
|
| 167 |
get_display_form_submit($form_id, &$form_state)
|
| 168 |
$form_id is the usual form id.
|
| 169 |
$form_state is the standard form_state array.
|
| 170 |
|
| 171 |
This too is a standard submit function. The simplelist id is stored in $form_state['values']['slid'], because even if this
|
| 172 |
is a new simplelist, by the time this function is called the basic data has already been written.
|
| 173 |
|
| 174 |
clear_existing_settings($slid, $form_id='', &$form_state=NULL, $format='block');
|
| 175 |
$slid is the simplelist id for the simplelist you're cleaning.
|
| 176 |
$form_id is the form id.
|
| 177 |
$form_state is the form_state array.
|
| 178 |
$format is either 'block' or 'page'.
|
| 179 |
|
| 180 |
If someone is editing an existing simplelist and changing their display from this one to another one, this is the function where
|
| 181 |
the module asks for you to clean up the data you've written. So, if you've written data to a new table that you defined for this display,
|
| 182 |
this is where you would find that row and delete it.
|
| 183 |
|
Parent Directory
| 
Revision Log
| 
Revision Graph