{ "content": [ { "type": "text", "text": "# CGI::Application::Plugin::ErrorPage (perldoc)\n\n## NAME\n\nCGI::Application::Plugin::ErrorPage - A simple error page plugin for CGI::Application\n\n## SYNOPSIS\n\nuse CGI::Application::Plugin::ErrorPage 'error';\nsub myrunmode {\nmy $self = shift;\neval { .... };\nif ($@) {\n# Send the gory details to the log for the developers\nwarn \"$@\";\n# Send a comprehensible message to the users\nreturn $self->error(\ntitle => \"Technical Failure',\nmsg => \"There was a techical failure during the operation.\",\n);\n}\n}\n\n## DESCRIPTION\n\nThis plugin provides a shortcut for the common need of returning a simple error message to the\nuser.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (2 subsections)\n- **METHODS** (1 subsections)\n- **SUPPORT**\n- **AUTHOR**\n- **COPYRIGHT**\n- **SEE ALSO** (1 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "CGI::Application::Plugin::ErrorPage", "section": "", "mode": "perldoc", "summary": "CGI::Application::Plugin::ErrorPage - A simple error page plugin for CGI::Application", "synopsis": "use CGI::Application::Plugin::ErrorPage 'error';\nsub myrunmode {\nmy $self = shift;\neval { .... };\nif ($@) {\n# Send the gory details to the log for the developers\nwarn \"$@\";\n# Send a comprehensible message to the users\nreturn $self->error(\ntitle => \"Technical Failure',\nmsg => \"There was a techical failure during the operation.\",\n);\n}\n}", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 20, "subsections": [] }, { "name": "DESCRIPTION", "lines": 26, "subsections": [ { "name": "Suggested Uses", "lines": 6 }, { "name": "Silliness", "lines": 3 } ] }, { "name": "METHODS", "lines": 43, "subsections": [ { "name": "Example error.html", "lines": 21 } ] }, { "name": "SUPPORT", "lines": 3, "subsections": [] }, { "name": "AUTHOR", "lines": 4, "subsections": [] }, { "name": "COPYRIGHT", "lines": 5, "subsections": [] }, { "name": "SEE ALSO", "lines": 1, "subsections": [ { "name": "perl", "lines": 1 } ] } ], "sections": { "NAME": { "content": "CGI::Application::Plugin::ErrorPage - A simple error page plugin for CGI::Application\n", "subsections": [] }, "SYNOPSIS": { "content": "use CGI::Application::Plugin::ErrorPage 'error';\n\nsub myrunmode {\nmy $self = shift;\n\neval { .... };\n\nif ($@) {\n# Send the gory details to the log for the developers\nwarn \"$@\";\n\n# Send a comprehensible message to the users\nreturn $self->error(\ntitle => \"Technical Failure',\nmsg => \"There was a techical failure during the operation.\",\n);\n}\n\n}\n", "subsections": [] }, "DESCRIPTION": { "content": "This plugin provides a shortcut for the common need of returning a simple error message to the\nuser.\n\nYou are encouraged to provide a template file so that the error messages can be presented with a\ndesign consistent with the rest of your application.\n\nA simple design is provided below to get to you started.\n\nA better default error page.\nIf you don't install an AUTOLOAD run mode in the normal way in \"setup\", this plugin will\nautomatically install a reasonable default at the \"prerun\" stage, which returns an error page\nlike this:\n\nreturn $c->error(\ntitle => 'The requested page was not found.',\nmsg => \"(The page tried was: \".$c->getcurrentrunmode.\")\"\n);\n\nRelation to errormode()\nCGI::Application includes \"errormode()\" to provide custom handling when the application dies.\nThis error() routine provides a shortcut for displaying error messages to the user. So, they\nboth have a place on their own, and it could make sense to use them together. In your\n'errormode' routine, you might call error() to return a message to the user:\n\n$self->error( title => 'Technical Failure', msg => 'There was a technical failure' );\n", "subsections": [ { "name": "Suggested Uses", "content": "Some common cases for returning error messages to the user include:\n\n* \"Technical Failure\" - The software failed unexpectedly\n* \"Insufficient Information\" - some required query parameter was missing\n* \"Request Not Understood\" - Some value we received in the query just didn't make sense.\n" }, { "name": "Silliness", "content": "[22:36] Techno Failure. We were cruising along and rocking out while fulfilling your request, but then the music stopped and we sort of got distracted.\n[22:36] Tek Failure. Too busy reading Shatner novels to respond to your request.\n" } ] }, "METHODS": { "content": "error()\nreturn $self->error(\ntitle => \"Technical Failure',\nmsg => \"There was a techical failure during the operation\",\n);\n\nNothing fancy, just a shortcut to load a template meant to display errors. I've used it for the\npast several years, and it's been very handy to always have around on projects to quickly write\nerror handling code.\n\nIt tries to load a template file named 'error.html' to display the error page.\n\nIf you want to use a different location, I recommend putting something like this in your base\nclass, so you only have to provide your error template location once.\n\n# In this case, intentionally *don't* import 'error' to avoid a \"redefined\" warning.\nuse CGI::Application::Plugin::ErrorPage;\nsub error {\nmy $c = shift;\nreturn $c->CGI::Application::Plugin::ErrorPage::error(\ntmpl => $self->cfg('ROOTURI').'/path/to/my/alternate/error/file.html',\n@,\n);\n}\n\nThis module intentionally ignores any \"tmplpath()\" set by application, since this is usually an\nindication of where the intended file is located, not the error template. This exceptional\nhandling of the \"tmplpath()\" is one of the only value added bits of logic that this plugin\nadds. The rest of it is primarily a simple recommendation for error page handling wrapped up as\na module.\n\nIf you don't want this behavior, it's simple enough just to roll your own error() page method\nand skip using this plugin. Here's the simple essential code:\n\nuse Params::Validate ':all';\nsub error {\nmy $self = shift;\nmy %p = validate(@, { title => SCALAR, msg => SCALAR });\nmy $t = $self->loadtmpl;\n$t->param( title => $p{title}, msg => $p{msg} );\nreturn $t->output;\n}\n", "subsections": [ { "name": "Example error.html", "content": "Here's a very basic example of an \"error.html\" file to get you started.\n\n\n\n\n<!-- tmplvar title escape=HTML -->\n\n\n\n

\n

\n\n\n\nWe manage site-wide designs with Dreamweaver and keep a basic 'error.html' that uses a generic\nDreamweaver 'page.dwt' template with standard EditableRegion names. That way, we can copy this\nerror.html into a new Dreamweaver-managed project and have the new design applied to it easily\nthrough Dreamweaver.\n" } ] }, "SUPPORT": { "content": "Ask for help on the CGI::Application mailing list. Report bugs and wishes through the\nrt.cpan.org bug tracker.\n", "subsections": [] }, "AUTHOR": { "content": "Mark Stosberg\nCPAN ID: MARKSTOS\nmark@summersault.com\n", "subsections": [] }, "COPYRIGHT": { "content": "This program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nThe full text of the license can be found in the LICENSE file included with this module.\n", "subsections": [] }, "SEE ALSO": { "content": "", "subsections": [ { "name": "perl", "content": "" } ] } } } }