Commit 1e156b5a authored by jcnventura's avatar jcnventura

Improve the documentation

parent 64aadf58
********************************************************************
D R U P A L M O D U L E
********************************************************************
Name: Printer-friendly Pages module
Maintainer: Joao Ventura <joao at venturas dot org>
Author: Matt Westgate <drupal at asitis dot org>
********************************************************************
INSTALLATION:
INSTALLATION
------------
1. Decompress the print-n.x-n.n.tar.gz file into your Drupal modules directory (usually sites/all/modules, see http://drupal.org/node/176044 for more information).
Decompress the print-n.x-n.n.tar.gz file into your Drupal modules
directory (usually sites/all/modules, see http://drupal.org/node/176044 for
more information).
2. Enable the print module:
Administer > Site building > Modules (admin/build/modules)
Enable the print module: Administer > Site building > Modules
(admin/build/modules)
3. Configure access rules:
Administer > User management > Access control (admin/user/access)
4. Configure:
Administer > Site configuration > Printer-friendly (admin/settings/print)
********************************************************************
PRINT_PDF module:
PDF TOOL
--------
The print_pdf module requires the use of an external PDF generation tool.
The currently supported tools are dompdf and TCPDF.
dompdf support:
The dompdf tool produces results that are more faithful to the HTML printer-friendly page.
The dompdf tool produces results that are more faithful to the HTML
printer-friendly page.
1. Download dompdf from http://sourceforge.net/projects/dompdf/
2. Extract the contents of the downloaded package into the print module directory (usually sites/all/modules/print)
2. Extract the contents of the downloaded package into the print module
directory (usually sites/all/modules/print)
3. Edit dompdf_config.inc.php to fit your installation.
4. Grant write access to the lib/fonts directory to your webserver user.
5. If you're using dompdf-0.5.1, delete the dompdf.php file as it contains a security vulnerability
5. If you're using dompdf-0.5.1, delete the dompdf.php file as it contains
a security vulnerability
6. Check http://www.digitaljunkies.ca/dompdf/ for further information.
TCPDF support:
TCPDF seems to be more actively developed than dompdf, but it's support for CSS is considerably worse.
TCPDF seems to be more actively developed than dompdf, but it's support
for CSS is considerably worse.
1. Download TCPDF from http://sourceforge.net/projects/tcpdf/
2. Extract the contents of the downloaded package into the print module directory (usually sites/all/modules/print)
2. Extract the contents of the downloaded package into the print module
directory (usually sites/all/modules/print)
3. Edit the config/tcpdf_config.php file to fit your installation.
4. Check http://tcpdf.sourceforge.net/ for further information.
********************************************************************
UPDATE:
UPDATE
------
When updating from a previous version, just remove the print directory and follow the instructions above. Make sure that you backup any costumization to the print.tpl.php and print.css files.
When updating from a previous version, just remove the print directory and
follow the instructions above. Make sure that you backup any costumization
to the print.tpl.php and print.css files.
********************************************************************
ROBOTS:
CONFIGURATION
-------------
Even though it is possible to set per-page robots settings, the following can be placed in your robots.txt file after the User-agent line to prevent search engines from even asking for the page:
Configure access rules: Administer > User management > Access control
(admin/user/access)
access print: Enable access to the PF page and display of the PF link in
other pages. (default: disabled)
administer print: Enable access to the module settings page.
(default: disabled)
Disallow: /print/
Configure the module: Administer > Site configuration > Printer-friendly
(admin/settings/print)
Also, for updates from older versions (<=4.7.x-1.0 and <=5.x-1.2) which used node/nnn/print instead of print/nnn, the following lines can prevent requests from Google for the obsolete print URLs:
ROBOTS
------
Disallow: /*/print$
Even though it is possible to set per-page robots settings, the following
can be placed in your robots.txt file after the User-agent line to prevent
search engines from even asking for the page:
Note that pattern matching in robots.txt is a Google extension (see http://www.google.com/support/webmasters/bin/answer.py?answer=40367 for more information).
Disallow: /print/
Also, for updates from older versions (<=4.7.x-1.0 and <=5.x-1.2) which used
node/nnn/print instead of print/nnn, the following lines can prevent
requests from Google for the obsolete print URLs:
********************************************************************
CUSTOMIZATION:
Disallow: /*/print$
- To modify the template of printer friendly pages, simply edit the print.tpl.php or the print.css files found in this directory.
Note that pattern matching in robots.txt is a Google extension (see
http://www.google.com/support/webmasters/bin/answer.py?answer=40367 for more
information).
- It is possible to set per-content-type and/or theme-specific templates which are searched for in the following order:
i. print.node-$type.tpl.php in the theme directory
ii. print.node-$type.tpl.php in the module directory
iii. print.tpl.php in the theme directory
iv. print.tpl.php in the module directory (supplied by the module)
// $Id$
This diff is collapsed.
<?php
/* $Id$ */
// $Id$
//*******************************************************************
// Admin Settings: Print
//*******************************************************************
/**
* @file
* Contains the administrative functions of the PF module.
*
* This file is included by the core PF module, and includes the
* settings form.
*/
/**
* Print module settings form
* Menu callback for the Printer-friendly pages module settings form.
*
* @ingroup forms
*/
function print_main_settings() {
$print_settings = variable_get('print_settings', print_settings_default());
......
<?php
// $Id$
/**
* Implementation of hook_install().
*/
function print_install() {
drupal_set_message(t("Printer-friendly Page settings are available under !link",
array( '!link' => l('Administer > Site configuration > Printer-friendly Pages ', 'admin/settings/print' ) )
));
}
/**
* Implementation of hook_uninstall().
*/
......@@ -14,4 +23,5 @@ function print_uninstall() {
while ($variable = db_fetch_object($settings)) {
variable_del($variable->name);
}
}
<?php
/* $Id$ */
// $Id$
/**
* @file
* Display printer-friendly versions of Drupal pages
* Displays Printer-friendly versions of Drupal pages.
*
* This is the core module of the PF package, with the Drupal hooks
* and other administrative functions.
*/
define("PRINT_PATH", "print");
/**
* Default values of the print_settings variable
*
* @return
* array with the values
*/
function print_settings_default() {
return array('logo_url' => '',
......@@ -33,6 +39,9 @@ function print_html_settings_default() {
/**
* Default values of the print_sourceurl_settings variable
*
* @return
* array with the values
*/
function print_sourceurl_settings_default() {
return array('enabled' => 1, 'date' => 0, 'forcenode' => 0);
......@@ -40,15 +49,14 @@ function print_sourceurl_settings_default() {
/**
* Default values of the print_robot_settings variable
*
* @return
* array with the values
*/
function print_robot_settings_default() {
return array('noindex' => 1, 'nofollow' => 1, 'noarchive' => 0, 'nocache' => 0);
}
//*******************************************************************
// Drupal Hooks
//*******************************************************************
/**
* Implementation of hook_perm().
*/
......@@ -182,6 +190,12 @@ function print_link_alter(&$links, $node) {
* Implementation of hook_help().
*/
function print_help($path, $arg) {
switch ($path) {
case 'admin/help#print':
// Return a line-break version of the module README
return filter_filter('process', 2, NULL, file_get_contents(drupal_get_path('module', 'print') ."/README.txt") );
}
$print_html_settings = variable_get('print_html_settings', print_html_settings_default());
if (($print_html_settings['show_link']) && ($print_html_settings['show_sys_link']) &&
......@@ -220,7 +234,8 @@ function print_form_alter(&$form, $form_state, $form_id) {
/**
* Auxiliary function to fill the Printer-friendly link attributes
*
* @return array of formatted attributes
* @return
* array of formatted attributes
*/
function _print_format_link_aux($type = 0, $text = '', $img = '', $title = '', $class = '') {
$print_settings = variable_get('print_settings', print_settings_default());
......@@ -269,6 +284,13 @@ function _print_format_link_aux($type = 0, $text = '', $img = '', $title = '', $
);
}
/**
* Format the Printer-friendly link
*
* @return
* array of formatted attributes
* @ingroup themeable
*/
function theme_print_format_link() {
$print_html_settings = variable_get('print_html_settings', print_html_settings_default());
$text = t('Printer-friendly version');
......@@ -283,20 +305,34 @@ function theme_print_format_link() {
);
}
/**
* Define the strings displayed by the module in the printer-friendly template
*
* @return
* array with the used text strings
* @ingroup themeable
*/
function theme_print_text() {
return array('retrieved' => t('retrieved on'),
'sourceURL' => t('Source URL'),
'published' => t('Published on'),
'by' => t('By'),
'created' => t('Created'),
'links' => t('Links:'),
'links' => t('Links'),
);
}
/**
* Auxiliary function to display a formatted Printer-friendly link
*
* @return string
* Function made available so that developers may call this function from
* their defined pages/blocks.
*
* @param $path
* path of the original page (optional). If not specified, the current URL
* is used
* @return
* string with the HTML link to the printer-friendly page
*/
function print_insert_link($path = NULL) {
if (user_access('access print')) {
......
<?php
/* $Id$ */
// $Id$
//*******************************************************************
// Module Functions :: Controller
//*******************************************************************
/**
* @file
* Contains the functions to generate Printer-friendly pages.
*
* This file is included by the core PF module, and includes all the
* functions necessary to generate a PF version of the original page
* in HTML format.
*/
/**
* Generate an HTML version of the printer-friendly page
*
* @see print_controller()
* @see _print_get_template()
*/
function print_controller_html() {
$print = print_controller();
include_once(_print_get_template($print["type"]));
}
/**
* Print module path catcher
* Select the print generator function based on the current path
*
* Depending on the type of node, this functions chooses the appropriate
* generator function.
*
* @return
* array with the fields to be used in the template
* @see _print_generate_node()
* @see _print_generate_path()
* @see _print_generate_book()
*/
function print_controller() {
// Remove the print/ prefix
......@@ -47,14 +67,11 @@ function print_controller() {
return $print;
}
//*******************************************************************
// Module Functions : Auxiliary
//*******************************************************************
/**
* Generates a meta tag to tell robots what they may index based on module settings
* Generates a robots meta tag to tell them what they may index
*
* @return string
* @return
* string with the meta robots tag
*/
function _print_robots_meta_generator() {
$robots_settings = variable_get('print_robot_settings', print_robot_settings_default());
......@@ -85,9 +102,15 @@ function _print_robots_meta_generator() {
}
/**
* Generates the HTML to insert in the template file
* Post-processor that fills the array for the template with common details
*
* @return string
* @param $node
* generated node with a printer-friendly node body
* @param $cid
* id of current comment being generated (NULL when not generating
* an individual comment)
* @return
* array with the fields to be used in the template
*/
function _print_var_generator($node, $cid = NULL) {
global $base_url, $language;
......@@ -174,7 +197,7 @@ function _print_var_generator($node, $cid = NULL) {
for ($i = 0; $i < $max; $i++) {
$print["pfp_links"] .= '['. ($i + 1) .'] '. $urls[$i] ."<br />\n";
}
$print["pfp_links"] = "<p><strong>". $themed['links'] ."</strong><br />". $print["pfp_links"] ."</p>";
$print["pfp_links"] = "<p><strong>". $themed['links'] .":</strong><br />". $print["pfp_links"] ."</p>";
}
}
......@@ -189,10 +212,16 @@ function _print_var_generator($node, $cid = NULL) {
}
/**
* We need to manipulate URLs so that they are recorded as absolute in the
* Printer-friendly URLs list, and to add a [n] footnote marker.
* Callback function for the preg_replace_callback for URL-capable patterns
*
* @return string containing the changed <a> tag
* Manipulate URLs to make them absolute in the URLs list, and to add a
* [n] footnote marker.
*
* @param $matches
* array with the matched tag patterns, usually <a...>+text+</a>
* @return
* tag with re-written URL and when appropriate the [n] index to the
* URL list
*/
function _print_rewrite_urls($matches) {
global $base_url, $base_root;
......@@ -280,8 +309,11 @@ function _print_rewrite_urls($matches) {
/**
* Auxiliary function to store the Printer-friendly URLs list as static.
*
* @return string containing the list of URLs previously stored if $url is 0,
* or the current count otherwise.
* @param $url
* absolute URL to be inserted in the list
* @return
* list of URLs previously stored if $url is 0, or the current count
* otherwise.
*/
function _print_friendly_urls($url = 0) {
static $urls = array();
......@@ -299,11 +331,16 @@ function _print_friendly_urls($url = 0) {
}
/**
* Choose most appropriate template
*
* Auxiliary function to resolve the most appropriate template trying to find
* a content specific template in the theme or module dir before falling back
* on a generic template also in those dirs.
*
* @return string with the most suitable template filename
* @param $type
* name of the node type being rendered in a PF page
* @return
* filename of the most suitable template
*/
function _print_get_template($type = NULL) {
if ($type) {
......@@ -330,12 +367,15 @@ function _print_get_template($type = NULL) {
return drupal_get_path('module', 'print') ."/print.tpl.php";
}
//*******************************************************************
// Module Functions : Content renderers
//*******************************************************************
/**
* Outputs a printer-friendly page. Used for content types
* Prepare a Printer-friendly-ready node body for content nodes
*
* @param $nid
* node ID of the node to be rendered into a printer-friendly page
* @param $cid
* comment ID of the individual comment to be rendered
* @return
* filled array ready to be used in the template
*/
function _print_generate_node($nid, $cid = NULL) {
// We can take a node id
......@@ -406,7 +446,12 @@ function _print_generate_node($nid, $cid = NULL) {
}
/**
* Outputs a printer-friendly page. Used for drupal core pages.
* Prepare a Printer-friendly-ready node body for non-content pages
*
* @param $path
* path of the node to be rendered into a printer-friendly page
* @return
* filled array ready to be used in the template
*/
function _print_generate_path($path) {
$path = drupal_get_normal_path($path);
......@@ -448,7 +493,12 @@ function _print_generate_path($path) {
/**
* Outputs a printer-friendly page. Used for book pages
* Prepare a Printer-friendly-ready node body for book pages
*
* @param $nid
* node ID of the node to be rendered into a printer-friendly page
* @return
* filled array ready to be used in the template
*/
function _print_generate_book($nid) {
$node = node_load(array('nid' => $nid));
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment