Catalyst-Manual-5.9012/000750 000000 000000 00000000000 14557515636 014724 5ustar00rootwheel000000 000000 Catalyst-Manual-5.9012/README000644 000000 000000 00000000601 12474515633 015577 0ustar00rootwheel000000 000000 Catalyst-Manual This is just the Catalyst manual. If you want to develop Catalyst apps, please install Catalyst::Devel. If you'd like a tutorial and a full example Catalyst application, please install Task::Catalyst::Tutorial. If you just want to run Catalyst applications, you probably don't need this manual, but you do need Catalyst::Runtime. http://dev.catalystframework.org/ Catalyst-Manual-5.9012/Changes000644 000000 000000 00000030326 14557515607 016226 0ustar00rootwheel000000 000000 Revision history for Catalyst-Manual 5.9012 - 2024-02-03 - fixed some broken links (Graham Knop, Daniel Böhmer) 5.9011 - 2020-07-22 - added NGINX Unit deployment documentation 5.9010 - 2019-04-25 - updated stale urls - numerous typo fixes - many pod syntax fixes - other pod syntax cleanup - added references to the RT issues queue, mailing list, and irc channel 5.9009 - 2014-12-13 - fixed a new error in the manual regarding "component" -> "components" (RT#99131, RT#100597, RT#100767) - typo fix in 09_FormFu.pod (Jason McVeigh, RT#104585) 5.9008 - 2014-07-26 - misc small documentation tweaks (thanks Karen Etheridge, Matthew Horsfall, Andreas Marienborg, Dagfinn Ilmari Mannsåker, David Steinbrunner, Gerda Shank, Jesse) 5.9007 2013-05-06 - Fix pod warnings (RT#83398 - thanks, Paul Waring!) - Fix repository metadata (thanks, Lars Dɪᴇᴄᴋᴏᴡ) 5.9006 2012-11-08 - fix bad =head1 (Kennedy Clark) 5.9005 2012-11-01 - Fix minor typos RT 78545, thanks Joe Axford - Update auth class name RT 77322 Thanks Joe Axford - Fix typo RT #77247 Thanks John Deighan 5.9004 4th May 2012 - PSGI Compat changes - Small code changes (thanks sockmonk) - Small changes to Manual::Components 5.9003 17 Feb 2012 - Mention PSGI in Manual::Ingro RT 74872 (thanks William Blunn). - Better docs of :Global inspired by RT 74869 (thanks William Blunn) - Highlight the importance of uncommenting the template line in the list action - Clarify docs for nginx in non-root - a trailing slash on the location block is very much needed. - Clarified Data::Dumper usage. RT#71410 Thanks to Bill Corr - Mention Chef deployment in Manual::Deployment (thanks to Alexey Melezhik) 5.9002 3 Sept 2011 - Tutorial - Switch to 'catalyst' vs. 'root' user in VM - Add notes about X Windows installation - Misc small adjustments 5.9001 2 Sept 2011 - Tutorial: - Migrate Tutorial to use of a downloadable Virtual Machine - Switch tutorial to Catalyst::Plugin::StatusMessage (vs. flash and query parameters) - Switch to use of local::lib - Add "next chapter links" (RT #31164) - Test all the tutorial code and make sure it's all working - Lots of other Tutorial cleanup - Update to Catalyst 5.9 and latest versions of all modules - Clean up RT ticket queue (#68379, 68377, 68376, etc.) - Other misc fixes/changes 5.9000 16 Aug 2011 - Copy editing to make more sense in deployment documentation. 5.8901 7 Aug 2011 - TRIAL RELEASE - Added Catalyst::Manual::Deployment containing the documentation which used to be in Catalyst::Engine::*, updated for the new PSGI engine. 5.8008 2 Aug 2011 - Tutorial chaper 3 - Remove note about hacking tests to require MyApp so that MyApp->path_to works. Application components should compile independently, and therefore explain this and show configuring components from the app class. - Tutorial appendix - Fix confusing mix of singular and plural table names in the MySQL section to be plural, as per the rest of the tutorial. - Cookbook - Remove suggestion to generate RSS feeds using Template Toolkit. This is a horrible idea, and it's very very easy to generate an invalid feed. 5.8007 29 Feb 2011 - Tutorial - Switch to use of DBIx::Class::PassphraseColumn for hashed & salted passwords. It's much more flexible than the previously used DBIx::Class::EncodedColumn. 5.8006 29 Feb 2011 - Fix metadata to refer to the new git repository - Cookbook - Small fixes and typos - Tutorial - Various typo fixes. - RT #57989: typo - RT #61486: correct instructions for MySQL - RT #62095: prevent XSS - RT #62095: persistent message on /login - RT #63057: typo - RT #64087: typos - RT #64126: Use precise name of licence - RT #64126: typos - RT #67820: fix relationship decleration - Do not recommend FastMmap - DevelopmentProcess - RT #62610: typo 5.8005 27 Oct 2010 - Tutorial: - Add DATABASE CONFIG SWITCHING USING MULTIPLE CONFIG FILES section - Critical bugfix on index page. 5.8004 17 Feb 2010 - Tutorial: - Add foreign key support for SQLite (huge thanks to Caelum for that and other good edits!) - Add "Quick Start" to Intro (Chapter 1) - Switch to use of "-r" to auto-restart the dev svr - Update for latest available Debian package versions - Switch to individual files for example code vs. tarballs - Switch to 'done_testing' and shorter 'prove' args for testing chapter - Misc typo fixes - Other: - Minor Cookbook edits 5.8003 28 Dec 2009 - Variety of typo fixes - Fix incorrectness re :Global and :Local - Update DevelopmentProcess.pod 5.8002 15 Nov 2009 - Update tutorial to match latest prepacked versions in Debian 5 - Add FormHandler branch (with thanks to gshank!) - Misc cleanup/freshing up of tutorial. - Fix indenting issue (with thanks to Kiffin Gish) - Integrate tome fix branch (with thanks to tome!) - Add a "negative" test to confirm that test02 does not have an admin create link - Integrate sqlite3 clarification and link by wolfman2000 from tutorial_role_updates branch - Fix Pod typos in ::Internals (RT#51488) - Fix Pod typos in the Cookbook (RT#51466) - Fix a Test::Pod failure and make Debian happier. - Typo fixes from garu - Misc minor and/or typo fixes 5.8001 06 Oct 2009 - Tutorial - Fix RT #46760 - Fix RT #46618 - Fix cat-install script URL - Fix typos - Replace reference to deprecated CatalystX::ListFramework::Builder with Catalyst::Plugin::AutoCRUD - Other - Lots of updates thanks to t0m - Update development process / core team docs - Cookbook fixes WRT authorization - Better description of application setup process - Fix some links - Normalise spacing 5.8000 27 May 2009 - Tutorial: - Update for Catalyst 5.80 - Update to "depluralize" the database names (big thanks to Kiffin Gish!) - Switch back to including numbers in chapter names (for proper sorting) - Add section to Ch 4: "Moving Complicated View Code to the Model" - Add section to Ch 3: "RenderView's 'dump_info' Feature" - Misc fixes and updates (thanks to Anne Wainwright) - Other: - Add some 5.8 and Moose-specific material to the new CatalystAndMoose.pod (thanks to t0m and Sebastian Willert) 5.7021 8 May 2009 - Tutorial: - Switch to SimpleDB for auth - Switch to use of DBIx::Class::EncodedColumn for hashed & salted passwords - Re-write PostgreSQL section in appendix - Remove "create=dynamic" and only cover "create=static" for DBIC helper - Other: - Rewrite / clean up a big chunk of Catalyst::Manual::Intro (Ian Wells) - There is no Catalyst::Config, fix reference to it. (t0m) - Misc minor adjustments 5.7020 12 Mar 2009 - Tutorial: - Fix errors in FormFu chapter 5.7019 11 Mar 2009 - Tutorial: - Change from the use of "part" to refer to each .pod file for the tutorial in favor of the more intuitive word "chapter." "Part" was just to ambiguous (e.g., does "prior part" refer to the prior .pod file or the prior section in the current .pod file). - Move use of "load_namespaces" for DBIC from BasicCRUD to MoreCatalystBasics - Update the "Table of Contents" in Tutorial.pod to match the current sections - Fix a few typos 5.7018 8 Mar 2009 - Tutorial: - Add a new section to BasicCRUD covering more advanced features of DBIC ("EXPLORING THE POWER OF DBIC") - Convert from Ubuntu to Debian 5 live CD as the recommended way to do the tutorial (all code and examples updated and tested to match) - Removed Catalyst::Plugin::Authorization::ACL from Authorization.pod in favor of a "chained and model-based" approach - More conversion to Chained dispatch - Suggestions and fixes with thanks to mintywalker@gmail.com - DBIC-related updates in MoreCatalystBasics - Fix misplaced "=over 4" in previous release - Reword warning about not using GET for delete based on input from kd - Lots of other small adjustments 5.7017 28 Feb 2009 - Tutorial: - Main change = adding Chained dispatch starting in BasicCRUD (Part 4) - Change FormFu tutorial to not use deprecated methods (Del Merritt) - MoreCatalystBasics - Additional clarification about TTSite (Del Merritt) - Tutorial::Authorization - Corrects the ACL for "/books/delete" - Additional comments (Del Merritt) - Tutorial::AdvancedCRUD::FormFu - suggest how the intrepid user might now proceed, having completed the Tutorial. (Del Merritt) - Fix typo in Authorization section (RT #42091) - Fix typo in BasicCRUD (RT #42034) - Resolve outstanding typo and suggestions in MoreCatalystBasics (RT #41491) - Fix DBIC create for MySQL in Appendix (Jarom) - Other: - Misc minor updates - Add some "getting started" links to the Catalyst::Manual page 5.7016 28 Dec 2008 - Tutorial: - Updates to make Parts 8 & 9 run correctly - Adjust URLs for final config tarballs - Add note about changes across different C::Devel on how plugins enabled - Misc minor updates 5.7015 15 Dec 2008 - Tutorial: - Remove TTSite from Tutorial (thanks to dhoss for the help) - Update Tutorial for Ubuntu 8.10 (therefore update to Cat v5.7014, C::Devel v1.07, DBIC v0.08010, etc.) - Reorganize MoreCatalystBasics.pod so user is able to run the app the first time much earlier and build on it from there (running the app each time along the way) - Update URL for latest copy in SVN to match new location of repo - Other: - Misc typo fix - Change use of Class::C3 to MRO::Compat, as rafl tells me this is best practice, and gives you native next::method in 5.10. (t0m) 5.7014 04 Nov 2008 - Remove a reference to a FOREACH loop that did not exist (RT #39046) - Changed some Template Toolkit links to perldoc links (RT #38354) - Fix Template Toolkit website link (RT #37574) - Fix part numbering (RT #37963) - Improvements to the ACCEPT_CONTEXT docs in Manual::Intro - Happy Election Day, America! 5.7013 09 Jul 2008 - revert to use Catalyst qw/@plugins/ style 5.7012 29 May 2008 - Expurgation of all use of default :Private and index :Private in favour of default :Path and index :Path :Args(0) - Expurgation of all yaml as configuration format - Major updates to tutorial, thanks hkclark and gerda 5.7011 16 May 2008 - added warnings and poiinters to newer examples in HTML::Widget, and Authentication parts of the tutorial. - pod fix (RT #32636) 5.701004 09 Apr 2008 - rename placeholder back to Manual.pm, this will probably trigger a ppm bug but that's ppm's problem 5.701003 08 Oct 2007 - Patch to Cookbook from bits. 5.701002 25 Aug 2007 5.701001 17 Aug 2007 - Changes to mocation of lib/Catalyst/Manual.pod to lib/Catalyst/ManualPlaceholder.pm to keep cpan indexer happy. 5.700704 08 Aug 2007 - Updated mailing list addresses to scsys.co.uk domains 5.700703 - Cookbook: Updated development server deployment instructions, and included a better description of the POE engine. 5.700702 26 April 2007 - Switch to Module::Install 5.700701 19 April 2007 - Removal of WritingPlugins. ExtendingCatalyst is now the main resource for extensions to the framework and the application. 5.700501 10 November 2006 - Matches Catalyst-Runtime 5.7005 5.700401 07 November 2006 - First release to CPAN; matches Catalyst-Runtime 5.7004. 5.700301 20 October 2006 - Splitting manual into its own distro Catalyst-Manual-5.9012/MANIFEST000644 000000 000000 00000003621 14557515636 016064 0ustar00rootwheel000000 000000 Changes lib/Catalyst/Manual.pm lib/Catalyst/Manual/About.pod lib/Catalyst/Manual/Actions.pod lib/Catalyst/Manual/CatalystAndMoose.pod lib/Catalyst/Manual/Components.pod lib/Catalyst/Manual/Cookbook.pod lib/Catalyst/Manual/Deployment.pod lib/Catalyst/Manual/Deployment/Apache/FastCGI.pod lib/Catalyst/Manual/Deployment/Apache/mod_perl.pod lib/Catalyst/Manual/Deployment/DevelopmentServer.pod lib/Catalyst/Manual/Deployment/FastCGI.pod lib/Catalyst/Manual/Deployment/IIS/FastCGI.pod lib/Catalyst/Manual/Deployment/lighttpd/FastCGI.pod lib/Catalyst/Manual/Deployment/nginx/FastCGI.pod lib/Catalyst/Manual/Deployment/NGINXUnit/PSGI.pod lib/Catalyst/Manual/Deployment/SharedHosting.pod lib/Catalyst/Manual/DevelopmentProcess.pod lib/Catalyst/Manual/ExtendingCatalyst.pod lib/Catalyst/Manual/Internals.pod lib/Catalyst/Manual/Intro.pod lib/Catalyst/Manual/Tutorial.pod lib/Catalyst/Manual/Tutorial/01_Intro.pod lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod lib/Catalyst/Manual/Tutorial/04_BasicCRUD.pod lib/Catalyst/Manual/Tutorial/05_Authentication.pod lib/Catalyst/Manual/Tutorial/06_Authorization.pod lib/Catalyst/Manual/Tutorial/07_Debugging.pod lib/Catalyst/Manual/Tutorial/08_Testing.pod lib/Catalyst/Manual/Tutorial/09_AdvancedCRUD.pod lib/Catalyst/Manual/Tutorial/09_AdvancedCRUD/09_FormBuilder.pod lib/Catalyst/Manual/Tutorial/09_AdvancedCRUD/09_FormFu.pod lib/Catalyst/Manual/Tutorial/09_AdvancedCRUD/09_FormHandler.pod lib/Catalyst/Manual/Tutorial/10_Appendices.pod lib/Catalyst/Manual/WritingPlugins.pod maint/Makefile.PL.include Makefile.PL MANIFEST This list of files README t/01-use.t xt/author/pod-coverage.t xt/author/pod.t LICENSE LICENSE file (added by Distar) META.yml Module YAML meta-data (added by MakeMaker) META.json Module JSON meta-data (added by MakeMaker) Catalyst-Manual-5.9012/LICENSE000644 000000 000000 00000043547 14557515550 015746 0ustar00rootwheel000000 000000 Terms of the Perl programming language system itself a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" --- The GNU General Public License, Version 1, February 1989 --- This software is Copyright (c) 2020 by Catalyst Contributors, see Catalyst.pm, Kieren Diment . This is free software, licensed under: The GNU General Public License, Version 1, February 1989 GNU GENERAL PUBLIC LICENSE Version 1, February 1989 Copyright (C) 1989 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The license agreements of most software companies try to keep users at the mercy of those companies. By contrast, our General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. The General Public License applies to the Free Software Foundation's software and to any other program whose authors commit to using it. You can use it for your programs, too. When we speak of free software, we are referring to freedom, not price. Specifically, the General Public License is designed to make sure that you have the freedom to give away or sell copies of free software, that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of a such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. The precise terms and conditions for copying, distribution and modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any work containing the Program or a portion of it, either verbatim or with modifications. Each licensee is addressed as "you". 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this General Public License and to the absence of any warranty; and give any other recipients of the Program a copy of this General Public License along with the Program. You may charge a fee for the physical act of transferring a copy. 2. You may modify your copy or copies of the Program or any portion of it, and copy and distribute such modifications under the terms of Paragraph 1 above, provided that you also do the following: a) cause the modified files to carry prominent notices stating that you changed the files and the date of any change; and b) cause the whole of any work that you distribute or publish, that in whole or in part contains the Program or any part thereof, either with or without modifications, to be licensed at no charge to all third parties under the terms of this General Public License (except that you may choose to grant warranty protection to some or all third parties, at your option). c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the simplest and most usual way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this General Public License. d) You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. Mere aggregation of another independent work with the Program (or its derivative) on a volume of a storage or distribution medium does not bring the other work under the scope of these terms. 3. You may copy and distribute the Program (or a portion or derivative of it, under Paragraph 2) in object code or executable form under the terms of Paragraphs 1 and 2 above provided that you also do one of the following: a) accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Paragraphs 1 and 2 above; or, b) accompany it with a written offer, valid for at least three years, to give any third party free (except for a nominal charge for the cost of distribution) a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Paragraphs 1 and 2 above; or, c) accompany it with the information you received as to where the corresponding source code may be obtained. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form alone.) Source code for a work means the preferred form of the work for making modifications to it. For an executable file, complete source code means all the source code for all modules it contains; but, as a special exception, it need not include source code for modules which are standard libraries that accompany the operating system on which the executable file runs, or for standard header files or definitions files that accompany that operating system. 4. You may not copy, modify, sublicense, distribute or transfer the Program except as expressly provided under this General Public License. Any attempt otherwise to copy, modify, sublicense, distribute or transfer the Program is void, and will automatically terminate your rights to use the Program under this License. However, parties who have received copies, or rights to use copies, from you under this General Public License will not have their licenses terminated so long as such parties remain in full compliance. 5. By copying, distributing or modifying the Program (or any work based on the Program) you indicate your acceptance of this license to do so, and all its terms and conditions. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. 7. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of the license which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the license, you may choose any version ever published by the Free Software Foundation. 8. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS Appendix: How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to humanity, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) 19yy This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) 19xx name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (a program to direct compilers to make passes at assemblers) written by James Hacker. , 1 April 1989 Ty Coon, President of Vice That's all there is to it! --- The Artistic License 1.0 --- This software is Copyright (c) 2020 by Catalyst Contributors, see Catalyst.pm, Kieren Diment . This is free software, licensed under: The Artistic License 1.0 The Artistic License Preamble The intent of this document is to state the conditions under which a Package may be copied, such that the Copyright Holder maintains some semblance of artistic control over the development of the package, while giving the users of the package the right to use and distribute the Package in a more-or-less customary fashion, plus the right to make reasonable modifications. Definitions: - "Package" refers to the collection of files distributed by the Copyright Holder, and derivatives of that collection of files created through textual modification. - "Standard Version" refers to such a Package if it has not been modified, or has been modified in accordance with the wishes of the Copyright Holder. - "Copyright Holder" is whoever is named in the copyright or copyrights for the package. - "You" is you, if you're thinking about copying or distributing this Package. - "Reasonable copying fee" is whatever you can justify on the basis of media cost, duplication charges, time of people involved, and so on. (You will not be required to justify it to the Copyright Holder, but only to the computing community at large as a market that must bear the fee.) - "Freely Available" means that no fee is charged for the item itself, though there may be fees involved in handling the item. It also means that recipients of the item may redistribute it under the same conditions they received it. 1. You may make and give away verbatim copies of the source form of the Standard Version of this Package without restriction, provided that you duplicate all of the original copyright notices and associated disclaimers. 2. You may apply bug fixes, portability fixes and other modifications derived from the Public Domain or from the Copyright Holder. A Package modified in such a way shall still be considered the Standard Version. 3. You may otherwise modify your copy of this Package in any way, provided that you insert a prominent notice in each changed file stating how and when you changed that file, and provided that you do at least ONE of the following: a) place your modifications in the Public Domain or otherwise make them Freely Available, such as by posting said modifications to Usenet or an equivalent medium, or placing the modifications on a major archive site such as ftp.uu.net, or by allowing the Copyright Holder to include your modifications in the Standard Version of the Package. b) use the modified Package only within your corporation or organization. c) rename any non-standard executables so the names do not conflict with standard executables, which must also be provided, and provide a separate manual page for each non-standard executable that clearly documents how it differs from the Standard Version. d) make other distribution arrangements with the Copyright Holder. 4. You may distribute the programs of this Package in object code or executable form, provided that you do at least ONE of the following: a) distribute a Standard Version of the executables and library files, together with instructions (in the manual page or equivalent) on where to get the Standard Version. b) accompany the distribution with the machine-readable source of the Package with your modifications. c) accompany any non-standard executables with their corresponding Standard Version executables, giving the non-standard executables non-standard names, and clearly documenting the differences in manual pages (or equivalent), together with instructions on where to get the Standard Version. d) make other distribution arrangements with the Copyright Holder. 5. You may charge a reasonable copying fee for any distribution of this Package. You may charge any fee you choose for support of this Package. You may not charge a fee for this Package itself. However, you may distribute this Package in aggregate with other (possibly commercial) programs as part of a larger (possibly commercial) software distribution provided that you do not advertise this Package as a product of your own. 6. The scripts and library files supplied as input to or produced as output from the programs of this Package do not automatically fall under the copyright of this Package, but belong to whomever generated them, and may be sold commercially, and may be aggregated with this Package. 7. C or perl subroutines supplied by you and linked into this Package shall not be considered part of this Package. 8. The name of the Copyright Holder may not be used to endorse or promote products derived from this software without specific prior written permission. 9. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. The End Catalyst-Manual-5.9012/t/000750 000000 000000 00000000000 14557515635 015166 5ustar00rootwheel000000 000000 Catalyst-Manual-5.9012/xt/000750 000000 000000 00000000000 14557515635 015356 5ustar00rootwheel000000 000000 Catalyst-Manual-5.9012/META.yml000660 000000 000000 00000006723 14557515635 016207 0ustar00rootwheel000000 000000 --- abstract: "The Catalyst developer's manual" author: - 'Catalyst Contributors, see Catalyst.pm' - 'Kieren Diment ' build_requires: Test::More: '0.88' configure_requires: ExtUtils::MakeMaker: '0' dynamic_config: 0 generated_by: 'ExtUtils::MakeMaker version 7.70, CPAN::Meta::Converter version 2.150010' license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: '1.4' name: Catalyst-Manual no_index: directory: - t - inc requires: perl: '5.006' resources: IRC: irc://irc.perl.org/#catalyst MailingList: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst bugtracker: https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual repository: https://github.com/perl-catalyst/Catalyst-Manual.git version: '5.9012' x_contributors: - 'Kennedy Clark ' - 'Tomas Doran ' - 'Kieren Diment ' - 'Karen Etheridge ' - 'Graham Knop ' - 'Jonathan Rockway ' - 'Jesse Sheidlower ' - 'Brian Cassidy ' - 'Caleb Cushing ' - 'Dan Dascalescu ' - 'Rafael Kitover ' - 'Jason Felds ' - 'Frederik Schwarzer ' - 'Jonathan Yu ' - 'Breno G. de Oliveira ' - "Lars Dɪá´á´á´á´á´¡ 迪ææ¯ " - 'Matt S Trout ' - 'Florian Ragwitz ' - 'Jess Robinson ' - 'Matthew Horsfall ' - 'Andrew Rodland ' - 'Artem Konev ' - 'Eden Cardim ' - 'Justin Hunter ' - 'Ricardo Signes ' - "Robert 'phaylon' Sedlacek " - 'Shlomi Fish ' - 'antgel ' - 'Alexander Hartmaier ' - 'Andreas Marienborg ' - 'Dagfinn Ilmari MannsÃ¥ker ' - 'Gerda Shank ' - 'Ian Wells ' - 'Jay Hannah ' - 'Jay Kuri ' - 'Mark A. Stratman ' - 'Mateu X. Hunter ' - 'Nick Tonkin <1nickt@users.noreply.github.com>' - 'Peter Karman ' - 'Wes Sheldahl ' - 'Alastair McGowan-Douglas ' - 'Andy Grundman ' - 'Ash Berlin ' - 'David Schmidt ' - 'David Steinbrunner ' - 'Dominic Humphries ' - 'Edwin de Graaf ' - 'Eisenberger Tamás ' - 'Eric A. Zarko ' - 'Iñigo Tejedor Arrondo ' - 'Jonathan "Duke" Leto ' - 'Jonathan Otsuka ' - 'Kartik Thakore ' - 'Kostya Ten ' - 'Lilly An ' - 'Marcus Ramberg ' - 'Matthias Dietrich ' - 'Paul Waring ' - 'Ronald J Kimball ' - 'Tom Feist ' - 'Ton Voon ' - 'Zsolt Zemancsik ' - 'kmx ' x_serialization_backend: 'CPAN::Meta::YAML version 0.018' Catalyst-Manual-5.9012/META.json000660 000000 000000 00000010760 14557515636 016354 0ustar00rootwheel000000 000000 { "abstract" : "The Catalyst developer's manual", "author" : [ "Catalyst Contributors, see Catalyst.pm", "Kieren Diment " ], "dynamic_config" : 0, "generated_by" : "ExtUtils::MakeMaker version 7.70, CPAN::Meta::Converter version 2.150010", "license" : [ "perl_5" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : 2 }, "name" : "Catalyst-Manual", "no_index" : { "directory" : [ "t", "inc" ] }, "prereqs" : { "build" : {}, "configure" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "develop" : { "requires" : { "Pod::Simple" : "3.11", "Test::Pod" : "1.14", "Test::Pod::Coverage" : "1.04" } }, "runtime" : { "requires" : { "perl" : "5.006" } }, "test" : { "requires" : { "Test::More" : "0.88" } } }, "release_status" : "stable", "resources" : { "bugtracker" : { "mailto" : "bug-Catalyst-Manual@rt.cpan.org", "web" : "https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual" }, "repository" : { "type" : "git", "url" : "https://github.com/perl-catalyst/Catalyst-Manual.git", "web" : "https://github.com/perl-catalyst/Catalyst-Manual" }, "x_IRC" : "irc://irc.perl.org/#catalyst", "x_MailingList" : "http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst" }, "version" : "5.9012", "x_contributors" : [ "Kennedy Clark ", "Tomas Doran ", "Kieren Diment ", "Karen Etheridge ", "Graham Knop ", "Jonathan Rockway ", "Jesse Sheidlower ", "Brian Cassidy ", "Caleb Cushing ", "Dan Dascalescu ", "Rafael Kitover ", "Jason Felds ", "Frederik Schwarzer ", "Jonathan Yu ", "Breno G. de Oliveira ", "Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 ", "Matt S Trout ", "Florian Ragwitz ", "Jess Robinson ", "Matthew Horsfall ", "Andrew Rodland ", "Artem Konev ", "Eden Cardim ", "Justin Hunter ", "Ricardo Signes ", "Robert 'phaylon' Sedlacek ", "Shlomi Fish ", "antgel ", "Alexander Hartmaier ", "Andreas Marienborg ", "Dagfinn Ilmari MannsÃ¥ker ", "Gerda Shank ", "Ian Wells ", "Jay Hannah ", "Jay Kuri ", "Mark A. Stratman ", "Mateu X. Hunter ", "Nick Tonkin <1nickt@users.noreply.github.com>", "Peter Karman ", "Wes Sheldahl ", "Alastair McGowan-Douglas ", "Andy Grundman ", "Ash Berlin ", "David Schmidt ", "David Steinbrunner ", "Dominic Humphries ", "Edwin de Graaf ", "Eisenberger Tamás ", "Eric A. Zarko ", "Iñigo Tejedor Arrondo ", "Jonathan \"Duke\" Leto ", "Jonathan Otsuka ", "Kartik Thakore ", "Kostya Ten ", "Lilly An ", "Marcus Ramberg ", "Matthias Dietrich ", "Paul Waring ", "Ronald J Kimball ", "Tom Feist ", "Ton Voon ", "Zsolt Zemancsik ", "kmx " ], "x_serialization_backend" : "JSON::MaybeXS version 1.004005" } Catalyst-Manual-5.9012/lib/000750 000000 000000 00000000000 14557515635 015471 5ustar00rootwheel000000 000000 Catalyst-Manual-5.9012/maint/000750 000000 000000 00000000000 14557515635 016033 5ustar00rootwheel000000 000000 Catalyst-Manual-5.9012/Makefile.PL000644 000000 000000 00000013314 14557513715 016701 0ustar00rootwheel000000 000000 use strict; use warnings; use 5.006; my %META = ( name => 'Catalyst-Manual', license => 'perl_5', author => [ 'Catalyst Contributors, see Catalyst.pm', 'Kieren Diment ', ], dynamic_config => 0, resources => { repository => { url => 'https://github.com/perl-catalyst/Catalyst-Manual.git', web => 'https://github.com/perl-catalyst/Catalyst-Manual', type => 'git', }, bugtracker => { mailto => 'bug-Catalyst-Manual@rt.cpan.org', web => 'https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual', }, x_IRC => 'irc://irc.perl.org/#catalyst', x_MailingList => 'http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst', }, # perl -MData::Dumper -e'$Data::Dumper::Indent = $Data::Dumper::Terse = $Data::Dumper::Trailingcomma = 1; print Dumper([map /^\s*\d+\s+(.*)/, `git shortlog -e -s -n`]);' x_contributors => [ 'Kennedy Clark ', 'Tomas Doran ', 'Kieren Diment ', 'Karen Etheridge ', 'Graham Knop ', 'Jonathan Rockway ', 'Jesse Sheidlower ', 'Brian Cassidy ', 'Caleb Cushing ', 'Dan Dascalescu ', 'Rafael Kitover ', 'Jason Felds ', 'Frederik Schwarzer ', 'Jonathan Yu ', 'Breno G. de Oliveira ', 'Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 ', 'Matt S Trout ', 'Florian Ragwitz ', 'Jess Robinson ', 'Matthew Horsfall ', 'Andrew Rodland ', 'Artem Konev ', 'Eden Cardim ', 'Justin Hunter ', 'Ricardo Signes ', 'Robert \'phaylon\' Sedlacek ', 'Shlomi Fish ', 'antgel ', 'Alexander Hartmaier ', 'Andreas Marienborg ', 'Dagfinn Ilmari Mannsåker ', 'Gerda Shank ', 'Ian Wells ', 'Jay Hannah ', 'Jay Kuri ', 'Mark A. Stratman ', 'Mateu X. Hunter ', 'Nick Tonkin <1nickt@users.noreply.github.com>', 'Peter Karman ', 'Wes Sheldahl ', 'Alastair McGowan-Douglas ', 'Andy Grundman ', 'Ash Berlin ', 'David Schmidt ', 'David Steinbrunner ', 'Dominic Humphries ', 'Edwin de Graaf ', 'Eisenberger Tamás ', 'Eric A. Zarko ', 'Iñigo Tejedor Arrondo ', 'Jonathan "Duke" Leto ', 'Jonathan Otsuka ', 'Kartik Thakore ', 'Kostya Ten ', 'Lilly An ', 'Marcus Ramberg ', 'Matthias Dietrich ', 'Paul Waring ', 'Ronald J Kimball ', 'Tom Feist ', 'Ton Voon ', 'Zsolt Zemancsik ', 'kmx ', ], prereqs => { configure => { requires => { 'ExtUtils::MakeMaker' => '0', }, }, runtime => { requires => { perl => '5.006', }, }, test => { requires => { 'Test::More' => '0.88', }, }, develop => { requires => { 'Pod::Simple' => '3.11', # L support 'Test::Pod' => '1.14', 'Test::Pod::Coverage' => '1.04', }, }, }, ); my %MM_ARGS = (); ## BOILERPLATE ############################################################### require ExtUtils::MakeMaker; (do './maint/Makefile.PL.include' or die $@) unless -f 'META.yml'; # have to do this since old EUMM dev releases miss the eval $VERSION line my $eumm_version = eval $ExtUtils::MakeMaker::VERSION; my $mymeta = $eumm_version >= 6.57_02; my $mymeta_broken = $mymeta && $eumm_version < 6.57_07; ($MM_ARGS{NAME} = $META{name}) =~ s/-/::/g; ($MM_ARGS{VERSION_FROM} = "lib/$MM_ARGS{NAME}.pm") =~ s{::}{/}g; $META{license} = [ $META{license} ] if $META{license} && !ref $META{license}; $MM_ARGS{LICENSE} = $META{license}[0] if $META{license} && $eumm_version >= 6.30; $MM_ARGS{NO_MYMETA} = 1 if $mymeta_broken; $MM_ARGS{META_ADD} = { 'meta-spec' => { version => 2 }, %META } unless -f 'META.yml'; $MM_ARGS{PL_FILES} ||= {}; $MM_ARGS{NORECURS} = 1 if not exists $MM_ARGS{NORECURS}; for (qw(configure build test runtime)) { my $key = $_ eq 'runtime' ? 'PREREQ_PM' : uc $_.'_REQUIRES'; my $r = $MM_ARGS{$key} = { %{$META{prereqs}{$_}{requires} || {}}, %{delete $MM_ARGS{$key} || {}}, }; defined $r->{$_} or delete $r->{$_} for keys %$r; } $MM_ARGS{MIN_PERL_VERSION} = delete $MM_ARGS{PREREQ_PM}{perl} || 0; delete $MM_ARGS{MIN_PERL_VERSION} if $eumm_version < 6.47_01; $MM_ARGS{BUILD_REQUIRES} = {%{$MM_ARGS{BUILD_REQUIRES}}, %{delete $MM_ARGS{TEST_REQUIRES}}} if $eumm_version < 6.63_03; $MM_ARGS{PREREQ_PM} = {%{$MM_ARGS{PREREQ_PM}}, %{delete $MM_ARGS{BUILD_REQUIRES}}} if $eumm_version < 6.55_01; delete $MM_ARGS{CONFIGURE_REQUIRES} if $eumm_version < 6.51_03; ExtUtils::MakeMaker::WriteMakefile(%MM_ARGS); ## END BOILERPLATE ########################################################### Catalyst-Manual-5.9012/maint/Makefile.PL.include000644 000000 000000 00000000203 14557513715 021424 0ustar00rootwheel000000 000000 BEGIN { -e 'Distar' or system qw(git clone https://github.com/p5sagit/Distar.git) } use lib 'Distar/lib'; use Distar 0.002000; 1; Catalyst-Manual-5.9012/lib/Catalyst/000750 000000 000000 00000000000 14557515635 017255 5ustar00rootwheel000000 000000 Catalyst-Manual-5.9012/lib/Catalyst/Manual/000750 000000 000000 00000000000 14557515635 020472 5ustar00rootwheel000000 000000 Catalyst-Manual-5.9012/lib/Catalyst/Manual.pm000644 000000 000000 00000004401 14557514172 021027 0ustar00rootwheel000000 000000 # Manual.pm # Copyright (c) 2006 Jonathan Rockway package Catalyst::Manual; use strict; use warnings; our $VERSION = '5.9012'; 1; __END__ =head1 NAME Catalyst::Manual - The Catalyst developer's manual =head1 SYNOPSIS perldoc Catalyst::Manual::Intro perldoc Catalyst::Manual::Tutorial =head1 SEE ALSO Install L to install all the dependencies you need to follow along with the Tutorial. You can also refer to L for more information on installation options. Some "Getting Started" Links: =over 4 =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =back =head2 Books For additional information on Catalyst, there are currently two books available: =over 4 =item * The Definitive Guide to Catalyst: Writing Extendable, Scalable and Maintainable Perl-Based Web Applications By: Kieren Diment, Matt Trout Available July 12, 2009 ISBN 10: 1-4302-2365-0 ISBN 13: 978-1-4302-2365-8 https://link.springer.com/book/10.1007/978-1-4302-2366-5 =item * Accelerating Perl Web Application Development By: Jonathan Rockway Published December, 2007 ISBN 10: 1847190952 ISBN 13: 978-1-847190-95-6 =back =head1 SUPPORT Corrections or amendments may be submitted through L (or L). There is also a mailing list available for users of this distribution, at L. There is also an irc channel available for users of this distribution, at L. =head1 AUTHORS Catalyst Contributors, see L =head1 COPYRIGHT AND LICENCE This software is copyright (c) 2006 by the Catalyst contributors. This is free software and content; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut Catalyst-Manual-5.9012/lib/Catalyst/Manual/ExtendingCatalyst.pod000644 000000 000000 00000062705 14557513230 024634 0ustar00rootwheel000000 000000 =head1 NAME Catalyst::Manual::ExtendingCatalyst - Extending The Framework =head1 DESCRIPTION This document will provide you with access points, techniques and best practices to extend the L framework, or to find more elegant ways to abstract and use your own code. The design of Catalyst is such that the framework itself should not get in your way. There are many entry points to alter or extend Catalyst's behaviour, and this can be confusing. This document is written to help you understand the possibilities, current practices and their consequences. Please read the L section before deciding on a design, especially if you plan to release your code to CPAN. The Catalyst developer and user communities, which B, will benefit most if we all work together and coordinate. If you are unsure on an implementation or have an idea you would like to have RFC'ed, it surely is a good idea to send your questions and suggestions to the Catalyst mailing list (See L) and/or come to the C<#catalyst> channel on the C network. You might also want to refer to those places for research to see if a module doing what you're trying to implement already exists. This might give you a solution to your problem or a basis for starting. =head1 BEST PRACTICES During Catalyst's early days, it was common to write plugins to provide functionality application wide. Since then, Catalyst has become a lot more flexible and powerful. It soon became a best practice to use some other form of abstraction or interface, to keep the scope of its influence as close as possible to where it belongs. For those in a hurry, here's a quick checklist of some fundamental points. If you are going to read the whole thing anyway, you can jump forward to L. =head2 Quick Checklist =over =item Use the C namespace if you can! If your extension isn't a Model, View, Controller, Plugin, Engine, or Log, it's best to leave it out of the C namespace. Use instead. =item Don't make it a plugin unless you have to! A plugin should be careful since it's overriding Catalyst internals. If your plugin doesn't really need to muck with the internals, make it a base Controller or Model. Also, if you think you really need a plugin, please instead consider using a L. =item There's a community. Use it! There are many experienced developers in the Catalyst community, there's always the IRC channel and the mailing list to discuss things. =item Add tests and documentation! This gives a stable basis for contribution, and even more importantly, builds trust. The easiest way is a test application. See L for more information. =back =head2 Namespaces While some core extensions (engines, plugins, etc.) have to be placed in the C namespace, the Catalyst core would like to ask developers to use the C namespace if possible. Please B invent components which are outside the well known C, C, C or C namespaces! When you try to put a base class for a C, C or C directly under your C directory as, for example, C, you will have the problem that Catalyst will try to load that base class as a component of your application. The solution is simple: Use another namespace. Common ones are C or C as examples. =head2 Can it be a simple module? Sometimes you want to use functionality in your application that doesn't require the framework at all. Remember that Catalyst is just Perl and you always can just C a module. If you have application specific code that doesn't need the framework, there is no problem in putting it in your C namespace. Just don't put it in C, C or C, because that would make Catalyst try to load them as components. Writing a generic component that only works with Catalyst is wasteful of your time. Try writing a plain perl module, and then a small bit of glue that integrates it with Catalyst. See L for a module that takes the approach. The advantage here is that your "Catalyst" DBIC schema works perfectly outside of Catalyst, making testing (and command-line scripts) a breeze. The actual Catalyst Model is just a few lines of glue that makes working with the schema convenient. If you want the thinnest interface possible, take a look at L. =head2 Using Moose roles to apply method modifiers Rather than having a complex set of base classes which you have to mixin via multiple inheritance, if your functionality is well structured, then it's possible to use the composability of L roles, and method modifiers to hook onto to provide functionality. These can be applied to your models/views/controllers, and your application class, and shipped to CPAN. Please see L for specific information about using Roles in combination with Catalyst, and L for more information about roles in general. =head2 Inheritance and overriding methods When overriding a method, keep in mind that some day additional arguments may be provided to the method, if the last parameter is not a flat list. It is thus better to override a method by shifting the invocant off of C<@_> and assign the rest of the used arguments, so you can pass your complete arguments to the original method via C<@_>: use MRO::Compat; ... sub foo { my $self = shift; my ($bar, $baz) = @_; # ... return $self->next::method(@_); } If you would do the common my ($self, $foo, $bar) = @_; you'd have to use a much uglier construct to ensure that all arguments will be passed along and the method is future proof: $self->next::method(@_[ 1 .. $#_ ]); =head2 Tests and documentation When you release your module to the CPAN, proper documentation and at least a basic test suite (which means more than pod or even just C, sorry) gives people a good base to contribute to the module. It also shows that you care for your users. If you would like your module to become a recommended addition, these things will prove invaluable. If you're just getting started, try using L to generate some example tests for your module. =head2 Maintenance In planning to release a module to the community (Catalyst or CPAN and Perl), you should consider if you have the resources to keep it up to date, including fixing bugs and accepting contributions. If you're not sure about this, you can always ask in the proper Catalyst or Perl channels if someone else might be interested in the project, and would jump in as co-maintainer. A public repository can further ease interaction with the community. Even read only access enables people to provide you with patches to your current development version. subversion, SVN and SVK, are broadly preferred in the Catalyst community. If you're developing a Catalyst extension, please consider asking the core team for space in Catalyst's own subversion repository. You can get in touch about this via IRC or the Catalyst developers mailing list. =head2 The context object Sometimes you want to get a hold of the context object in a component that was created on startup time, where no context existed yet. Often this is about the model reading something out of the stash or other context information (current language, for example). If you use the context object in your component you have tied it to an existing request. This means that you might get into problems when you try to use the component (e.g. the model - the most common case) outside of Catalyst, for example in cronjobs. A stable solution to this problem is to design the Catalyst model separately from the underlying model logic. Let's take L as an example. You can create a schema outside of Catalyst that knows nothing about the web. This kind of design ensures encapsulation and makes development and maintenance a whole lot easier. The you use the aforementioned model to tie your schema to your application. This gives you a C (the name is of course just an example) model as well as C models to access your result sources directly. By creating such a thin layer between the actual model and the Catalyst application, the schema itself is not at all tied to any application and the layer in-between can access the model's API using information from the context object. A Catalyst component accesses the context object at request time with L. =head1 CONFIGURATION The application has to interact with the extension with some configuration. There is of course again more than one way to do it. =head2 Attributes You can specify any valid Perl attribute on Catalyst actions you like. (See L for a description of what is valid.) These will be available on the L instance via its C accessor. To give an example, this action: sub foo : Local Bar('Baz') { my ($self, $c) = @_; my $attributes = $self->action_for('foo')->attributes; $c->res->body($attributes->{Bar}[0] ); } will set the response body to C. The values always come in an array reference. As you can see, you can use attributes to configure your actions. You can specify or alter these attributes via L, or even react on them as soon as Catalyst encounters them by providing your own L. =head2 Component Configuration At creation time, the class configuration of your component (the one available via C<< $self->config >>) will be merged with possible configuration settings from the applications configuration (either directly or via config file). This is done by Catalyst, and the correctly merged configuration is passed to your component's constructor (i.e. the new method). Ergo, if you define an accessor for each configuration value that your component takes, then the value will be automatically stored in the controller object's hash reference, and available from the accessor. The C accessor always only contains the original class configuration and you B call C<< $self->config >> to get your component configuration, as the data there is likely to be a subset of the correct config. For example: package MyApp use Moose; extends 'Catalyst'; ... __PACKAGE__->config( 'Controller::Foo' => { some_value => 'bar' }, ); ... package MyApp::Controller::Foo; use Moose; use namespace::autoclean; BEGIN { extends 'Catalyst::Controller' }; has some_value ( is => 'ro', required => 1 ); sub some_method { my $self = shift; return "the value of 'some_value' is " . $self->some_value; } ... my $controller = $c->controller('Foo'); warn $controller->some_value; warn $controller->some_method; =head1 IMPLEMENTATION This part contains the technical details of various implementation methods. Please read the L before you start your implementation, if you haven't already. =head2 Action classes Usually, your action objects are of the class L. You can override this with the C attribute to influence execution and/or dispatching of the action. A widely used example of this is L, which is used in every newly created Catalyst application in your root controller: sub end : ActionClass('RenderView') { } Usually, you want to override the C and/or the C method. The execute method of the action will naturally call the methods code. You can surround this by overriding the method in a subclass: package Catalyst::Action::MyFoo; use Moose; use namespace::autoclean; use MRO::Compat; extends 'Catalyst::Action'; sub execute { my $self = shift; my ($controller, $c, @args) = @_; # put your 'before' code here my $r = $self->next::method(@_); # put your 'after' code here return $r; } 1; We are using L to ensure that you have the next::method call, from L (in older perls), or natively (if you are using perl 5.10) to re-dispatch to the original C method in the L class. The Catalyst dispatcher handles an incoming request and, depending upon the dispatch type, will call the appropriate target or chain. From time to time it asks the actions themselves, or through the controller, if they would match the current request. That's what the C method does. So by overriding this, you can change on what the action will match and add new matching criteria. For example, the action class below will make the action only match on Mondays: package Catalyst::Action::OnlyMondays; use Moose; use namespace::autoclean; use MRO::Compat; extends 'Catalyst::Action'; sub match { my $self = shift; return 0 if ( localtime(time) )[6] == 1; return $self->next::method(@_); } 1; And this is how we'd use it: sub foo: Local ActionClass('OnlyMondays') { my ($self, $c) = @_; $c->res->body('I feel motivated!'); } If you are using action classes often or have some specific base classes that you want to specify more conveniently, you can implement a component base class providing an attribute handler. It is not possible to use multiple action classes at once, however L allows you to apply L to actions. For further information on action classes and roles, please refer to L and L. =head2 Component base classes Many L that were written in Catalyst's early days should really have been just controller base classes. With such a class, you could provide functionality scoped to a single controller, not polluting the global namespace in the context object. You can provide regular Perl methods in a base class as well as actions which will be inherited to the subclass. Please refer to L for an example of this. You can introduce your own attributes by specifying a handler method in the controller base. For example, to use a C attribute to specify a fully qualified action class name, you could use the following implementation. Note, however, that this functionality is already provided via the C<+> prefix for action classes. A simple sub foo : Local ActionClass('+MyApp::Action::Bar') { ... } will use C as action class. package MyApp::Base::Controller::FullClass; use Moose; use namespace::autoclean; BEGIN { extends 'Catalyst::Controller'; } sub _parse_FullClass_attr { my ($self, $app_class, $action_name, $value, $attrs) = @_; return( ActionClass => $value ); } 1; Note that the full line of arguments is only provided for completeness sake. We could use this attribute in a subclass like any other Catalyst attribute: package MyApp::Controller::Foo; use Moose; use namespace::autoclean; BEGIN { extends 'MyApp::Base::Controller::FullClass'; } sub foo : Local FullClass('MyApp::Action::Bar') { ... } 1; =head2 Controllers Many things can happen in controllers, and it often improves maintainability to abstract some of the code out into reusable base classes. You can provide usual Perl methods that will be available via your controller object, or you can even define Catalyst actions which will be inherited by the subclasses. Consider this controller base class: package MyApp::Base::Controller::ModelBase; use Moose; use namespace::autoclean; BEGIN { extends 'Catalyst::Controller'; } sub list : Chained('base') PathPart('') Args(0) { my ($self, $c) = @_; my $model = $c->model( $self->{model_name} ); my $condition = $self->{model_search_condition} || {}; my $attrs = $self->{model_search_attrs} || {}; $c->stash(rs => $model->search($condition, $attrs); } sub load : Chained('base') PathPart('') CaptureArgs(1) { my ($self, $c, $id) = @_; my $model = $c->model( $self->{model_name} ); $c->stash(row => $model->find($id)); } 1; This example implements two simple actions. The C action chains to a (currently non-existent) C action and puts a result-set into the stash taking a configured C as well as a search condition and attributes. This action is a L endpoint. The other action, called C< load > is a chain midpoint that takes one argument. It takes the value as an ID and loads the row from the configured model. Please not that the above code is simplified for clarity. It misses error handling, input validation, and probably other things. The class above is not very useful on its own, but we can combine it with some custom actions by sub-classing it: package MyApp::Controller::Foo; use Moose; use namespace::autoclean; BEGIN { extends 'MyApp::Base::Controller::ModelBase'; } __PACKAGE__->config( model_name => 'DB::Foo', model_search_condition=> { is_active => 1 }, model_search_attrs => { order_by => 'name' }, ); sub base : Chained PathPart('foo') CaptureArgs(0) { } sub view : Chained('load') Args(0) { my ($self, $c) = @_; my $row = $c->stash->{row}; $c->res->body(join ': ', $row->name, $row->description); } 1; This class uses the formerly created controller as a base class. First, we see the configurations that were used in the parent class. Next comes the C action, where everything chains off of. Note that inherited actions act like they were declared in your controller itself. You can therefor call them just by their name in Cs, C and C specifications. This is an important part of what makes this technique so useful. The new C action ties itself to the C action specified in the base class and outputs the loaded row's C and C columns. The controller C now has these publicly available paths: =over =item /foo Will call the controller's C, then the base classes C action. =item /foo/$id/view First, the controller's C will be called, then it will C the row with the corresponding C<$id>. After that, C will display some fields out of the object. =back =head2 Models and Views If the functionality you'd like to add is really a data-set that you want to manipulate, for example internal document types, images, files, it might be better suited as a model. The same applies for views. If your code handles representation or deals with the applications interface and should be universally available, it could be a perfect candidate for a view. Please implement a C method in your views. This method will be called by Catalyst if it is asked to forward to a component without a specified action. Note that C is B but a simple Perl method. You are also encouraged to implement a C method corresponding with the one in L. This has proven invaluable, because people can use your view for much more fine-grained content generation. Here is some example code for a fictional view: package Catalyst::View::MyView; use Moose; use namespace::autoclean; extends 'Catalyst::View'; sub process { my ($self, $c) = @_; my $template = $c->stash->{template}; my $content = $self->render($c, $template, $c->stash); $c->res->body( $content ); } sub render { my ($self, $c, $template, $args) = @_; # prepare content here return $content; } 1; =head2 Plugins The first thing to say about plugins is that if you're not sure if your module should be a plugin, it probably shouldn't. It once was common to add features to Catalyst by writing plugins that provide accessors to said functionality. As Catalyst grew more popular, it became obvious that this qualifies as bad practice. By designing your module as a Catalyst plugin, every method you implement, import or inherit will be available via your applications context object. A plugin pollutes the global namespace, and you should be only doing that when you really need to. Often, developers design extensions as plugins because they need to get hold of the context object. Either to get at the stash or request/response objects are the widely spread reasons. It is, however, perfectly possible to implement a regular Catalyst component (read: model, view or controller) that receives the current context object via L. When is a plugin suited to your task? Your code needs to be a plugin to act upon or alter specific parts of Catalyst's request lifecycle. If your functionality needs to change some C or C stages, you won't get around a plugin. Note, if you just want to hook into such a stage, and run code before, or after it, then it is recommended that you use L's method modifiers to do this. Another valid target for a plugin architecture are things that B have to be globally available, like sessions or authentication. B release Catalyst extensions as plugins only to provide some functionality application wide. Design it as a controller base class or another better suited technique with a smaller scope, so that your code only influences those parts of the application where it is needed, and namespace clashes and conflicts are ruled out. The implementation is pretty easy. Your plugin will be inserted in the application's inheritance list, above Catalyst itself. You can by this alter Catalyst's request lifecycle behaviour. Every method you declare, every import in your package will be available as method on the application and the context object. As an example, let's say you want Catalyst to warn you every time uri_for was called without an action object as the first parameter, for example to test that all your chained uris are generated from actions (a recommended best practice). You could do this with this simple implementation (excuse the lame class name, it's just an example): package Catalyst::Plugin::UriforUndefWarning; use strict; use Scalar::Util qw/blessed/; use MRO::Compat; sub uri_for { my $c = shift; my $uri = $c->next::method(@_); $c->log->warn( 'uri_for with non action: ', join(', ', @_), ) if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action')); return $uri; } 1; This would override Catalyst's C method and emit a C log entry containing the arguments to uri_for. Please note this is not a practical example, as string URLs are fine for static content etc. A simple example like this is actually better as a L role, for example: package CatalystX::UriforUndefWarning; use Moose::Role; use namespace::autoclean; after 'uri_for' => sub { my ($c, $arg) = @_; $c->log->warn( 'uri_for with non action: ', join(', ', @_), ) if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action')); return $uri; }; Note that Catalyst will load any Moose Roles in the plugin list, and apply them to your application class. =head2 Factory components with COMPONENT() Every component inheriting from L contains a C method. It is used on application startup by C to instantiate the component object for the Catalyst application. By default, this will merge the components own Curation with the application wide overrides and call the class' C method to return the component object. You can override this method and do and return whatever you want. However, you should use L (via L) to forward to the original C method to merge the configuration of your component. Here is a stub C method: package CatalystX::Component::Foo; use Moose; use namespace::autoclean; extends 'Catalyst::Component'; sub COMPONENT { my $class = shift; # Note: $app is like $c, but since the application isn't fully # initialized, we don't want to call it $c yet. $config # is a hashref of config options possibly set on this component. my ($app, $config) = @_; # Do things here before instantiation $new = $class->next::method(@_); # Do things to object after instantiation return $new; } The arguments are the class name of the component, the class name of the application instantiating the component, and a hash reference with the controller's configuration. You are free to re-bless the object, instantiate a whole other component or really do anything compatible with Catalyst's expectations on a component. For more information, please see L. =head2 Applying roles to parts of the framework L will allow you to apply Roles to the following classes: =over =item Request =item Response =item Engine =item Dispatcher =item Stats =back These roles can add new methods to these classes, or wrap preexisting methods. The namespace for roles like this is C. For an example of a CPAN component implemented in this manor, see L. =head1 SEE ALSO L, L, L =head1 AUTHORS Catalyst Contributors, see Catalyst.pm =head1 COPYRIGHT This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself. =cut Catalyst-Manual-5.9012/lib/Catalyst/Manual/Internals.pod000644 000000 000000 00000006516 14557513230 023137 0ustar00rootwheel000000 000000 =head1 NAME Catalyst::Manual::Internals - Catalyst Internals =head1 DESCRIPTION This document provides a brief overview of the internals of Catalyst. As Catalyst is still developing rapidly, details may become out of date: please treat this as a guide, and look at the source for the last word. The coverage is split into initialization and request lifecycle. =head2 Initialization Catalyst initializes itself in two stages: =over 4 =item 1 When the Catalyst module is imported in the main application module, it stores any options. =item 2 When C<< __PACKAGE__->setup >> is called, it evaluates any options stored (C<-Debug>), and makes the application inherit from L (if that hasn't already been done with an explicit C<< use base 'Catalyst'; >> or C<< extends 'Catalyst'; >>. Any specified plugins are then loaded, the application module is made to inherit from the plugin classes. It also sets up a default log object and ensures that the application module inherits from C and from the selected specialized Engine module. =item 3 Catalyst automatically loads all components it finds in the C<$class::Controller>, C<$class::C>, C<$class::Model>, C<$class::M>, C<$class::View> and C<$class::V> namespaces (using L). As each is loaded, if it has a L method then this method will be called, and passed that component's configuration. It then returns an instance of the component, which becomes the C<$self> when methods in that component are called later. =item 4 Each controller has it's C method called. At this point, the subroutine attributes are retrieved from the L, parsed, and used to build instances of L, which are then registered with the dispatcher. =back =head2 Request Lifecycle For each request Catalyst builds a I object, which includes information about the request, and then searches the action table for matching actions. The handling of a request can be divided into three stages: preparation of the context, processing of the request, and finalization of the response. These are the steps of a Catalyst request in detail; every step can be overloaded to extend Catalyst. handle_request prepare prepare_request prepare_connection prepare_query_parameters prepare_headers prepare_cookies prepare_path prepare_body (unless parse_on_demand) prepare_body_parameters prepare_parameters prepare_uploads prepare_action dispatch finalize finalize_uploads finalize_error (if one happened) finalize_headers finalize_cookies finalize_body These steps are normally overloaded from engine classes, and may also be extended by plugins. For more on extending Catalyst, see L. The engine class populates the Catalyst request object with information from the underlying layer (L) during the prepare phase, then push the generated response information down to the underlying layer during the finalize phase. =head1 AUTHORS Catalyst Contributors, see Catalyst.pm =head1 COPYRIGHT This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself. =cut Catalyst-Manual-5.9012/lib/Catalyst/Manual/Deployment.pod000644 000000 000000 00000006763 14557513230 023324 0ustar00rootwheel000000 000000 =encoding utf8 =head1 NAME Catalyst::Manual::Deployment - Deploying Catalyst =head1 DEPLOYMENT OPTIONS Catalyst applications are most often deployed as a FastCGI or mod_perl application (with FastCGI being the recommended option). However, as Catalyst is based on the L specification, any web handler implementing that specification can be used to run Catalyst applications. This documentation most thoroughly covers the normal and traditional deployment options, but will mention alternate methods of deployment, and we welcome additional documentation from people deploying Catalyst in non-standard environments. =head2 Deployment in a shared hosting environment Almost all shared hosting environments involve deploying Catalyst as a FastCGI application on Apache. You will usually want to have a set of libraries specific to your application installed on your shared host. Full details of deploying Catalyst in a shared hosting environment are at L. =head2 FastCGI FastCGI is the most common Catalyst deployment option. It is documented generally in L, and there are specific instructions for using FastCGI with common web servers below: =head3 Apache L =head3 nginx L =head3 lighttpd L =head3 Microsoft IIS L =head2 mod_perl Traditionally a common deployment option for dedicated applications, mod_perl has some advantages and disadvantages over FastCGI. Use of mod_perl is documented in L. =head2 Development Server It is possible to deploy the Catalyst development server behind a reverse proxy. This may work well for small-scale applications which are in an early development phase, but which you want to be able to show to people. See L. =head2 PSGI Catalyst can be deployed with any PSGI-compliant handler. See L for more information; a list of possible deployment servers are shown below: =head3 NGINX Unit L is a lightweight, dynamically configurable web app server that supports running PSGI-capable apps. =head3 Starman L is a high-performance Perl server implementation, which is designed to be used directly (rather than behind a reverse proxy). It includes HTTP/1.1 support, chunked requests and responses, keep-alive, and pipeline requests. =head3 Starlet Starlet is a standalone HTTP/1.0 server with keep‐alive support which is suitable for running HTTP application servers behind a reverse proxy. =head3 Twiggy L is a high-performance asynchronous web server. It can be used in conjunction with Catalyst, but there are a number of caveats which mean that it is not suitable for most deployments. =head2 Chef L is an open-source systems integration framework built specifically for automating cloud computing deployments. A Cookbooks demonstrating how to deploy a Catalyst application using Chef is available at L and L. =head1 AUTHORS Catalyst Contributors, see Catalyst.pm =head1 COPYRIGHT This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself. =cut Catalyst-Manual-5.9012/lib/Catalyst/Manual/DevelopmentProcess.pod000644 000000 000000 00000012715 14557513230 025017 0ustar00rootwheel000000 000000 =head1 NAME Catalyst::Manual::DevelopmentProcess - Administrative structure of the Catalyst Development Process =head1 Contributing to Catalyst The main philosophy behind Catalyst development can be summarized as: Patches welcome! Everyone is welcome (and will be encouraged) to contribute to Catalyst in whatever capacity they're able to. People in #catalyst-dev will be more than happy to talk newcomers through contributing their first patch, or how best to go about their first CPAN extension module.... =head1 Catalyst development =head2 Discussing proposed bugfixes or improvements L has information about how to get in touch with the Catalyst "community". In particular, you would want to discuss a proposed change on the mailing list: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev or on IRC: irc://irc.perl.org/catalyst-dev http://wiki.catalystframework.org/wiki/livegroups Usually, the core team will be more than happy for you to contribute, and will talk you through how to submit a patch, or get a "commit bit". =head2 Repositories The Catalyst git repository can be found at: read: git://git.shadowcat.co.uk/catagits/PROJECTNAME write: catagits@git.shadowcat.co.uk:PROJECTNAME browser: https://git.shadowcat.co.uk/gitweb/gitweb.cgi =head2 Schedule There is no dated release cycle for Catalyst. New releases will be made when sufficient small fixes have accumulated; or an important bugfix, or significant feature addition, is completed. =head1 The Catalyst Core Team The intention of the Catalyst Core Team is to maintain and support the Catalyst framework, in order for it to be a viable and stable framework for developing web-based MVC applications. This includes both technical decisions about the Catalyst core distribution, and public relations relating to the Catalyst framework as a whole. The current goals of the Catalyst core development team are stability, performance, and a properly paced addition of features, with a focus on extensibility. The core team is concerned with the 'core' Catalyst distributions (i.e. L, L and L), and also tries to encourage best practices for extension authors, and cooperation and shared vision within the Catalyst community. =head2 Membership The Catalyst Core Team consists of the developers who have full commit privileges to the entire Catalyst source tree, and who have made a significant contribution to the core Catalyst distributions, and various extensions and plugins. In addition, the core team includes members that have non-technical roles, such as marketing, legal, or economic responsibilities. Currently, the Core Team consists of the following people: =over 4 =item Brian Cassidy =item Andy Grundman =item Christian Hansen =item Yuval Kogman =item Marcus Ramberg =item Jonathan Rockway =item Jesse Sheidlower =item Matt S. Trout =item Florian Ragwitz =item Tomas Doran =back New members of the Core Team must be accepted by a 2/3 majority by the current members. =head2 Technical Decisions. Any change to the Catalyst core which can not be conceived as a correction of an error in the current feature set will need to be accepted by at least 3 members of the Core Team before it can be committed to master (which is the basis for CPAN releases). Anyone with access is at any time free to make a branch to develop a proof of concept for a feature to be committed to master. =head2 Organizational and Philosophical Decisions. Any organizational or philosophical decision should be decided by majority vote. Thus it should be a goal of the organization that its membership number should at any time be an odd number, to render it effective with regards to decision making. The exceptions to this rule are changes to this charter and additions to the membership of the Core Team, which require a 2/3 majority. =head2 CPAN Releases Planned releases to CPAN should be performed by the release manager, at the time of writing Marcus Ramberg, or the deputy release manager, at the time of writing Florian Ragwitz. In the case of critical error correction, any member of the Core Team can perform a rescue release. =head2 Public statements from the Core Team The Core Team should strive to appear publicly as a group when answering questions or other correspondence. In cases where this is not possible, the same order as for CPAN releases applies. =head2 New Catalyst Extensions As Catalyst is deliberately designed for extension, there is an ecosystem of several hundred Catalyst extensions that can be found on CPAN. See L for more information on how to extend Catalyst in various ways and how to write CPANable components for Catalyst which can be reused in many applications. It is recommended to post a request for comments to the Catalyst mailing list, or ask around in the #catalyst IRC channel before starting to implement something, as another member of the community is likely to have example or prototype code that you can reuse, and members of the community and core team are happy to advise on the best way to implement a generic solution to a particular problem. This could save you duplicate work, and will help you produce a better thought out and designed extension. =head1 AUTHORS Catalyst Contributors, see Catalyst.pm =head1 COPYRIGHT This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself. =cut Catalyst-Manual-5.9012/lib/Catalyst/Manual/Components.pod000644 000000 000000 00000043443 14557513230 023325 0ustar00rootwheel000000 000000 =head1 NAME Catalyst::Manual::Components - Reuseable components for Catalyst applications =head1 DESCRIPTION This section lists the some of the components (and plugins) that are available to extend the runtime functionality of Catalyst. Most components are not distributed with Catalyst but should be available from CPAN. They typically require additional modules from CPAN. This list may well be outdated by the time you read this, and some plugins may be deprecated, or, conversely, may now part of core L. Be sure to check the Catalyst:: and CatalystX:: namespaces for additional components, and consult the mailing list ( L ) for advice on the current status or preferred use of your chosen plugin/framework. =head1 PLUGINS Take care with plugins! In general with a plugin ask "should this be acting globally on my application?". If not it should be a Controller Role (e.g. see L. =head2 L Provides Account Auto-Discovery for Catalyst. =head2 L Implements a demonstration showing how easily fluent speakers can read scrambled text if the first and last letters remain constant but the middle . Operates on text/plain and text/html served by your Catalyst application. This should really be a controller role, or even a View these days. =head2 L =head2 L Allows you to dispatch AtomPP methods. =head2 L A plugin that implements the necessary bits to make it easy to build an Atom API server for any Catalyst-based application. =head2 L An infrastructure plugin for the Catalyst authentication framework. Now the recommended way to do any form of Authentication. Note that newer versions of the authentication plugin allow multiple C, so that you can authenticate users in different ways in different parts of your application. This, however, has involved deprecating all classes in the C and C namespaces. These plugins are still usable, but they have mostly been replaced with new modules in the new namespace which will work together. =head3 Available Credential modules: =head4 L Allows you to use the L module with Catalyst. =head4 L Allows you to authenticate Facebook users using the FBConnect API. =head4 L Provides authentication via Flickr, using its API. =head4 L Allows you to authenticate users using HTTP Basic or Digest authentication. =head4 L Allows you to authenticate users against a remote web server offering HTTP authentication. =head4 L Allows you to authenticate your users against a Kerberos server. =head4 L Allows you to authenticate users using their login on other websites supporting the OAuth protocol. =head4 L Allows you to authenticate users using their login on other websites supporting the OpenID protocol. =head4 L Takes a username (or userid) and a password, and tries various methods of comparing a password based on what the chosen store's user objects support. Part of the Authentication Framework L. =head4 L Allows you to authenticate users using the RPX protocol. =head4 L Allows you to authenticate users in Catalyst that have already been authenticated by your web server. This is useful for authenticating users with SSL Client certificates, and using NTLM or any other authentication protocol natively supported by your web server. =head4 L Allows you to set the same password for all users, which is useful when you want to test logging in as multiple users or multiple types of user, without having to mock things, or set all users' passwords in your test suite. =head4 L Allows any of the L family of modules to be used to authenticate users in Catalyst. =head3 Available Store modules: =head4 L Does authentication and authorization against a L model. =head4 L Uses L to let your application use C<.htpasswd> files for its authentication storage. =head4 L This module implements the Catalyst::Authentication API for L. =head4 L Allows you to use a plain L database connection to identify users. =head4 L Allows you to use an Apache htpasswd type file to authenticate users. =head4 L Authenticate users stored as objects in the L object graph storage engine system. =head4 L Authenticates users using an LDAP server. =head4 L Lets you create a very quick and dirty user database in your application's config hash. Great for testing or getting up and running quickly. =head4 L The Null store is a transparent store where any supplied user data is accepted. This is mainly useful for remotely authenticating credentials (e.g. OpenID) which may not be tied to any local storage. =head4 L Allows access to authentication information stored in a database via a L class. =head4 L Allows access to authentication information stored in a database via a L class. =head4 L Allows access to authentication information stored in a database via a L class. =head4 L Allows access to authentication information stored in a database via a L class. =head4 L An easy authentication user object based on hashes. See L for more info. =head2 L This module provides Access Control List style path protection, with arbitrary rules for L applications. It operates only on the Catalyst private namespace, at least at the moment. =head2 L L provides role-based authorization for Catalyst based on L. =head2 L L enables specified request parameters to generate session variables. =head2 L Extends L by adding the capability of browser detection. It returns an instance of L, which lets you get information from the client's user agent. =head2 L Provides a cache method enabling easy access to a shared cache implementing the C<< Cache:: >> APO, such as: =over =item FastMmap =item FileCache =item BerkeleyDB =item Memcached =item CHI =back =head2 L =head2 L Provides specific charset handlers for the Japanese charsets. =head2 L =head2 L =head2 L =head2 L =head2 L Provides a standard method for loading config files. Support exists for various formats. See L L, L, L, L, and L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L A plugin based on L, which describes itself as a module to automatically insert data from a previous HTML form into the HTML input, textarea, radio buttons, checkboxes, and select tags. L is a subclass of L and uses it to parse the HTML and insert the values into the form tags. =head2 L =head2 L Allows you to retrieve various kinds of geographical information. You can retrieve the country or code from the current user, from a given IP address, or from a given hostname. =head2 L =head2 L =head2 L =head2 L An internationalization plugin for Catalyst. Supports C/C files and Maketext classes under your application's I18N namespace. =head2 L =head2 L =head2 L =head2 L Provides the ability to register AOP-like callbacks to specific Engine events. Subclasses L. =head2 L Adjusts the way that parameters operate, causing them to appear in the same order they were submitted by the browser. This can be useful for creating things such as email forms. =head2 L Helps improve the performance of slow or frequently accessed pages by caching the entire output of your page. Subsequent requests to the page will receive the page very quickly from cache. =head2 L =head2 L =head2 L A plugin for pluggable Catalyst applications. =head2 L A plugin for the Prototype JavaScript library. This plugin allows you to easily implement AJAX functionality without actually knowing Javascript. =head2 L Allows for easy redirecting with the Catalyst app. =head2 L =head2 L Use this if you would like to force visitors to access certain pages using only SSL mode. An attempt to access the page in non-SSL mode will receive a redirect into SSL mode. Useful for login pages, shopping carts, user registration forms, and other sensitive data. =head2 L =head2 L The L series of modules provide an easy way to include session handling in an application. You can choose from several different backend storage methods and combine that with your choice of client-side storage methods. =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L Allows your controller class to dispatch SRU actions (C, C, and C) from its own class. =head2 L =head2 L L is a plugin to serve static files from C<< $c->config(root => 'foo') >>. Intended chiefly for development purposes. =head2 L Serves static files in your application without requiring a single line of code. =head2 L A plugin to allow subrequests to actions to be made within Catalyst. Nice for portal software and such. =head2 L An interface to the L module, enabling easy HTML form creation. =head2 L Provides a Unicode-aware Catalyst. On request, it decodes all params from UTF-8 octets into a sequence of logical characters. On response, it encodes the body into UTF-8 octets. =head2 L Disrecommended plugin which tries to autodetect the uft8ness of the output and do the correct thing. This may work in some cases, but if it helps, you've already painted yourself into a corner - try to avoid! =head2 L =head2 L Computes the MD5 message digest of uploaded files. =head2 L =head2 L =head2 L Allows your Controller class to dispatch XMLRPC methods from its own class. =head1 CONTROLLERS =head2 L Catalyst integration for L. =head1 MODELS =head2 L The L (CDBI) model class. It is built on top of L, which automates the definition of L sub-classes by scanning the underlying table schemas, setting up columns and primary keys. =head2 L A neutral interface to the L module which does not attempt to automate table setup. It allows the user to manually set up L classes, either by doing so within the Catalyst model classes themselves, or by inheriting from existing L classes. =head2 L A L model class that can use either an explicit L or one automatically loaded from your database via L. =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L A model class for the Plucene search engine. =head2 L =head2 L =head2 L A model class for the Xapian search engine. =head1 VIEWS =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L =head2 L A view component for rendering pages with L. =head2 L =head2 L =head2 L A view component for rendering pages with L. =head2 L =head2 L =head2 L A view component for rendering pages using PSP, a Perl extension implementing a JSP-like templating system. See L. =head2 L A view component for rendering pages using Petal, the Perl Template Attribute Language, an XML-based templating system. See L. =head2 L A view component for rendering pages with Template Toolkit. See L. =head2 L =head2 L =head1 Actions =head2 L Creates a sane, standard end method for your application. =head1 OBSOLETE MODULES =head2 L Lets you mark lexical variables with a C attribute, automatically passing them to the stash. Discouraged by the author. =head2 L Replaced by L. =head2 L Replaced by L. =head2 L Replaced by L. =head2 L Replaced by L. =head2 L Replaced by L. =head2 L Replaced by L. =head2 L =head2 L =head2 Catalyst::Plugin::Config::* The L and L modules have been replaced by their corresponding L modules. =head2 L Replaced by L =head2 L =head2 L =head2 Catalyst::Plugin::Session::* The L, L, L, and L modules have been replaced by the framework. =head1 AUTHORS Catalyst Contributors, see Catalyst.pm =head1 COPYRIGHT This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself. =cut Catalyst-Manual-5.9012/lib/Catalyst/Manual/Tutorial.pod000644 000000 000000 00000025671 14557513230 023006 0ustar00rootwheel000000 000000 =head1 NAME Catalyst::Manual::Tutorial - Catalyst Tutorial: Overview =head1 DESCRIPTION The Catalyst framework is a flexible and comprehensive environment for quickly building high-functionality web applications. This tutorial is designed to provide a rapid introduction to its basics and its most commonly used features while focusing on real-world best practices. We suggest that you read this introduction on the web. Make sure you are reading the latest version of the tutorial by visiting L. Alternatively you can use CPAN modules like L, L, L (Catalyst based), or L to read a local copy of the tutorial. The tutorial is divided into the following sections: B (the index links above only navigate inside this page). =over 4 =item 1 L =item 2 L =item 3 L =item 4 L =item 5 L =item 6 L =item 7 L =item 8 L =item 9 L =item 10 L =back Final code tarballs for each chapter of the tutorial are available at L. =head1 Detailed Table of Contents =head2 L Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter. =over 4 =item * VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL =item * CATALYST INSTALLATION =item * DATABASES =item * WHERE TO GET WORKING CODE =back =head2 L Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter. =over 4 =item * CREATE A CATALYST PROJECT =item * HELLO WORLD =over 4 =item * The Simplest Way =item * Hello, World! Using a View and a Template =back =item * CREATE A SIMPLE CONTROLLER AND AN ACTION =back =head2 L Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter. =over 4 =item * CREATE A NEW APPLICATION =item * EDIT THE LIST OF CATALYST PLUGINS =item * CREATE A CATALYST CONTROLLER =item * CATALYST VIEWS =over 4 =item * Create a Catalyst View =item * Create a TT Template Page =item * Test Run The Application =back =item * CREATE A SQLITE DATABASE =item * DATABASE ACCESS WITH DBIx::Class =over 4 =item * Create a Dynamic DBIC Model =back =item * ENABLE THE MODEL IN THE CONTROLLER =over 4 =item * Test Run The Application =back =item * CREATE A WRAPPER FOR THE VIEW =over 4 =item * Configure TT.pm For The Wrapper =item * Create the Wrapper Template File and Stylesheet =item * Test Run The Application =back =item * A STATIC DATABASE MODEL WITH DBIx::Class =over 4 =item * Create Static DBIC Schema Files =item * Updating the Generated DBIC Schema Files =item * Run The Application =back =item * UPDATING THE VIEW =item * RUNNING THE APPLICATION FROM THE COMMAND LINE =item * OPTIONAL INFORMATION =over 4 =item * Using RenderView for the Default View =item * Using The Default Template Name =item * Return To A Manually-Specified Template =back =back =head2 L Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter. =over 4 =item * FORMLESS SUBMISSION =over 4 =item * Include a Create Action in the Books Controller =item * Include a Template for the url_create Action: =item * Try the url_create Feature =back =item * CONVERT TO A CHAINED ACTION =over 4 =item * Try the Chained Action =item * Refactor to Use a "Base" Method to Start the Chains =back =item * MANUALLY BUILDING A CREATE FORM =over 4 =item * Add a Method to Display the Form =item * Add a Template for the Form =item * Add Method to Process Form Values and Update Database =item * Test Out the Form =back =item * A SIMPLE DELETE FEATURE =over 4 =item * Include a Delete Link in the List =item * Add a Common Method to Retrieve a Book for the Chain =item * Add a Delete Action to the Controller =item * Try the Delete Feature =item * Fixing a Dangerous URL =item * Try the Delete and Redirect Logic =item * Using uri_for to Pass Query Parameters =item * Try the Delete and Redirect With Query Param Logic =back =item * EXPLORING THE POWER OF DBIC =over 4 =item * Add Datetime Columns to Our Existing Books Table =item * Update DBIC to Automatically Handle the Datetime Columns =item * Create a ResultSet Class =item * Chaining ResultSets =item * Adding Methods to Result Classes =back =back =head2 L Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter. =over 4 =item * BASIC AUTHENTICATION =over 4 =item * Add Users and Roles to the Database =item * Add User and Role Information to DBIC Schema =item * Sanity-Check Reload of Development Server =item * Include Authentication and Session Plugins =item * Configure Authentication =item * Add Login and Logout Controllers =item * Add a Login Form TT Template Page =item * Add Valid User Check =item * Displaying Content Only to Authenticated Users =item * Try Out Authentication =back =item * USING PASSWORD HASHES =over 4 =item * Get a SHA-1 Hash for the Password =item * Switch to SHA-1 Password Hashes in the Database =item * Enable SHA-1 Hash Passwords in Catalyst::Plugin::Authentication::Store::DBIC =item * Try Out the Hashed Passwords =back =item * USING THE SESSION FOR FLASH =over 4 =item * Try Out Flash =item * Switch To Flash-To-Stash =back =back =head2 L Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter. =over 4 =item * BASIC AUTHORIZATION =over 4 =item * Update Plugins to Include Support for Authorization =item * Add Config Information for Authorization =item * Add Role-Specific Logic to the ``Book List'' Template =item * Limit Books::add to admin Users =item * Try Out Authentication And Authorization =back =item * ENABLE MODEL-BASED AUTHORIZATION =back =head2 L Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter. =over 4 =item * LOG STATEMENTS =item * RUNNING CATALYST UNDER THE PERL DEBUGGER =item * DEBUGGING MODULES FROM CPAN =item * TT DEBUGGING =back =head2 L Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter. =over 4 =item * RUNNING THE "CANNED" CATALYST TESTS =item * RUNNING A SINGLE TEST =item * ADDING YOUR OWN TEST SCRIPT =item * SUPPORTING BOTH PRODUCTION AND TEST DATABASES =back =head2 L Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter. =over 4 =item * ADVANCED CRUD OPTIONS =back =head2 L Note: Click on the heading in the previous line to jump to the actual chapter. Below is a "table of contents" for this chapter. =over 4 =item * APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES =over 4 =item * "Un-indenting" with Vi/Vim =item * "Un-indenting" with Emacs =back =item * APPENDIX 2: USING MYSQL AND POSTGRESQL =over 4 =item * MySQL =item * PostgreSQL =back =item * APPENDIX 3: IMPROVED HASHING SCRIPT =back =head1 THANKS This tutorial would not have been possible without the input of many different people in the Catalyst community. In particular, the primary author would like to thank: =over 4 =item * Sebastian Riedel for founding the Catalyst project. =item * The members of the Catalyst Core Team for their tireless efforts to advance the Catalyst project. Although all of the Core Team members have played a key role in this tutorial, it would have never been possible without the critical contributions of: Matt Trout, for his unfathomable knowledge of all things Perl and Catalyst (and his willingness to answer lots of my questions); Jesse Sheidlower, for his incredible skill with the written word and dedication to improving the Catalyst documentation; and Yuval Kogman, for his work on the Catalyst "Auth & Authz" plugins (the original focus of the tutorial) and other key Catalyst modules. =item * Other Catalyst documentation folks like Kieren Diment, Gavin Henry, and Jess Robinson (including their work on the original Catalyst tutorial). =item * Kieren Diment for his oversight of Catalyst-related documentation. =item * Everyone on #catalyst and #catalyst-dev. =item * Louis Moore (who thanks Marcello Romani and Tom Lanyon) for the PostgreSQL content in the Appendix. =item * People who have emailed me with corrections and suggestions on the tutorial. As of the most recent release, this include: Florian Ragwitz, Mauro Andreolini, Jim Howard, Giovanni Gigante, William Moreno, Bryan Roach, Ashley Berlin, David Kamholz, Kevin Old, Henning Sprang, Jeremy Jones, David Kurtz, Ingo Wichmann, Shlomi Fish, Murray Walker, Adam Witney and xenoterracide (Caleb Cushing). Thanks to Devin Austin for coming up with an initial version of a non-TTSite wrapper page. Also, a huge thank you to Kiffin Gish for all the hard work on the "database depluralization" effort and Rafael Kitover for the work on updating the tutorial to include foreign key support for SQLite. I'm sure I am missing some names here... apologies for that (please let me know if you name should be here). =back =head1 AUTHOR Kennedy Clark, C Feel free to contact the author for any errors or suggestions, but the best way to report issues is via the CPAN RT Bug system at L. Copyright 2006-2010, Kennedy Clark, under the Creative Commons Attribution Share-Alike License Version 3.0 (L). Catalyst-Manual-5.9012/lib/Catalyst/Manual/About.pod000644 000000 000000 00000034250 14557513230 022246 0ustar00rootwheel000000 000000 =head1 NAME Catalyst::Manual::About - The philosophy of Catalyst =head1 DESCRIPTION This document is a basic introduction to the I of Catalyst. It does not teach you how to write Catalyst applications; for an introduction to that please see L. Rather, it explains the basics of what Catalyst is typically used for, and why you might want to use Catalyst to build your applications. =head2 What is Catalyst? The short summary Catalyst is a web application framework. This means that you use it to help build applications that run on the web, or that run using protocols used for the web. Catalyst is designed to make it easy to manage the various tasks you need to do to run an application on the web, either by doing them itself, or by letting you "plug in" existing Perl modules that do what you need. There are a number of things you typically do with a web application. For example: =over 4 =item * Interact with a web server If you're on the web, you're relying on a web server, a program that sends files over the web. There are a number of these, and your application has to do the right thing to make sure that your program works with the web server you're using. If you change your web server, you don't want to have to rewrite your entire application to work with the new one. =item * Do something based on a URI It's typical for web applications to use URIs as a main way for users to interact with the rest of the application; various elements of the URI will indicate what the application needs to do. Thus, C will add a person named "John" whose title is "President" to your database, and C will go to a "display" of item 23 in your catalog, and C will display the status of order 7582, and C will display a form to add a comment to page 8. Your application needs to have a regular way of processing these URIs so it knows what to do when such a request comes in. =item * Interact with a data store You probably use a database to keep track of your information. Your application needs to interact with your database, so you can create, edit, and retrieve your data. =item * Handle forms When a user submits a form, you receive it, process it to make sure it's been filled in properly, and then do something based on the result--submit an order, update a record, send e-mail, or return to the form if there's an error. =item * Display results If you have an application running on the web, people need to see things. You usually want your application displayed on a web browser, in which case you will probably be using a template system to help generate HTML code. But you might need other kinds of display, such as PDF files, or other forms of output, such as RSS feeds or e-mail. =item * Manage users You might need the concept of a "user", someone who's allowed to use your system, and is allowed to do certain things only. Perhaps normal users can only view or modify their own information; administrative users can view or modify anything; normal users can only order items for their own account; normal users can view things but not modify them; order-processing users can send records to a different part of the system; and so forth. You need a way of ensuring that people are who they say they are, and that people only do the things they're allowed to do. =item * Develop the application itself When you're writing or modifying the application, you want to have access to detailed logs of what it is doing. You want to be able to write tests to ensure that it does what it's supposed to, and that new changes don't break the existing code. =back Catalyst makes it easy to do all of these tasks, and many more. It is extremely flexible in terms of what it allows you to do, and very fast. It has a large number of "components" and "plugins" that interact with existing Perl modules so that you can easily use them from within your application. =over 4 =item * Interact with a web server? Catalyst lets you use a number of different ones, and even comes with a built-in server for testing or local deployment. =item * Do something based on a URI? Catalyst has extremely flexible systems for figuring out what to do based on a URI. =item * Interact with a data store? Catalyst has many plugins for different databases and database frameworks, and for other non-database storage systems. =item * Handle forms? Catalyst has plugins available for several form creation and validation systems that make it easy for the programmer to manage. =item * Display results? Catalyst has plugins available for a number of template modules and other output packages. =item * Manage users? Catalyst has plugins that handle sessions, authentication, and authorization, in any way you need. =item * Developing the application? Catalyst has detailed logging built-in, which you can configure as necessary, and supports the easy creation of new tests--some of which are automatically created when you begin writing a new application. =back =head3 What B Catalyst? Catalyst is not an out-of-the-box solution that allows you to set up a complete working e-commerce application in ten minutes. (There are, however, several systems built on top of Catalyst that can get you very close to a working app.) Catalyst is designed for flexibility and power; to an extent, this comes at the expense of simplicity. Programmers have many options for almost everything they need to do, which means that any given need can be done in many ways, and finding the one that's right for you, and learning the right way to do it, can take time. TIMTOWDI works both ways. Catalyst is not designed for end users, but for working programmers. =head2 Web programming: The Olden Days Perl has long been favored for web applications. There are a wide variety of ways to use Perl on the web, and things have changed over time. It's possible to handle everything with very raw Perl code: print "Content-type: text/html\n\n

Hello World!

"; for example, or my @query_elements = split(/&/, $ENV{'QUERY_STRING'}); foreach my $element (@query_elements) { my ($name, $value) = split(/=/, $element); # do something with your parameters, or kill yourself # in frustration for having to program like this } Much better than this is to use Lincoln Stein's great L module, which smoothly handles a wide variety of common tasks--parameter parsing, generating form elements from Perl data structures, printing http headers, escaping text, and very many more, all with your choice of functional or object-oriented style. While L was revolutionary and is still widely used, it has various drawbacks that make it unsuitable for larger applications: it is slow; your code with it generally combines application logic and display code; and it makes it very difficult to handle larger applications with complicated control flow. A variety of frameworks followed, of which the most widely used is probably L, which encourages the development of modular code, with easy-to-understand control-flow handling, the use of plugins and templating systems, and the like. Other systems include L, which is designed for use with XML running under mod_perl; L--upon which Catalyst was originally based--designed for the easy development of powerful web databases; L, which does a great deal of automation in helping to set up web sites with many complex features; and Ruby on Rails (see L), written of course in Ruby and among the most popular web development systems. It is not the purpose of this document to criticize or even briefly evaluate these other frameworks; they may be useful for you and if so we encourage you to give them a try. =head2 The MVC pattern MVC, or Model-View-Controller, is a model currently favored for web applications. This design pattern is originally from the Smalltalk programming language. The basic idea is that the three main areas of an application--handling application flow (Controller), processing information (Model), and outputting the results (View)--are kept separate, so that it is possible to change or replace any one without affecting the others, and so that if you're interested in one particular aspect, you know where to find it. Discussions of MVC often degenerate into nitpicky arguments about the history of the pattern, and exactly what "usually" or "should" go into the Controller or the Model. We have no interest in joining such a debate. In any case, Catalyst does not enforce any particular setup; you are free to put any sort of code in any part of your application, and this discussion, along with others elsewhere in the Catalyst documentation, are only suggestions based on what we think works well. In most Catalyst applications, each branch of MVC will be made of up of several Perl modules that can handle different needs in your application. The purpose of the B is to access and modify data. Typically the Model will interact with a relational database, but it's also common to use other data sources, such as the L search engine or an LDAP server. The purpose of the B is to present data to the user. Typical Views use a templating module to generate HTML code, using L