README: /** Note: * If you are upgrading from a previous version of MyNews-4, please * see the UPGRADING file in the source distribution. **/ 1. GETTING STARTED 1.1 Intro 1.2 Features 1.3 The Administration Interface 2. REQUIREMENTS 3. INSTALL 3.1 MySql setup 3.2 MyNews setup 4. PERMISSIONS 5. SECTIONS 6. THEMES 7. CHANNEL FILE 8. MISC 9. CONTACT #--------------------------------------------------------------------# /** * 1. GETTING STARTED **/ /** * 1.1 - Intro **/ This is MyNews 4 This only works with MySQL at the moment. I plan on building in database abstraction (most likely with PEAR) in the next major release, which will be 5.0. If you want to make it work with other databases, please feel free to do so. First thing I would like to do, is to give credit where it is due. The idea for MyNews wasn't mine. If it weren't for Stig-Ørjan Smelror of winther.net (stig@winther.net) MyNews probably wouldn't have been born. Stig wrote the inital release of MyNews and it suited his needs. I then took over the project. Since the Release of version 2.0, none of Stig's code remains, but the concept is still his. Therefore, I would like to thank him again. Other people of mention are: JedTheHead from http://www.organization.cx. If it weren't for his insight on the comments system, I probably would have lost interest a looong time ago. Finally, I would like to thank everyone who uses/has used/ and contributed to the project. I'm trying to get things going again, and hope that the project takes off after a long vacation. Thanks again everyone! --Mike /** * 1.2 - Features **/ Now, on to features, etc...... okay. This script features the follwing administrative tools: 1. Posting/Deleting/Editing news through a web interface. 2. A nested comment system. 3. Author administration with Author/Editor/Admin permissions (See the README section on PERMISSIONS) 4. Comment administration. 5. Submission adminstration. 6. Calendar administration. /** * 1.3 - The Administration Interface **/ The admin interface is pretty self explanatory. I suggest you just play around with it to get used to it. *NOTE* The default login to the admin section is as follows: User: admin Pass: abc123 #--------------------------------------------------------------------# /** * 2. REQUIREMENTS */ Following are things that are required for MyNews to work: Note: If you want me to test it on a different build, provide me a host ;] -------------------------------------------------------- Package: Tested Versions: URL: -------------------------------------------------------- PHP 4.0.6/4.1.2 (http://www.php.net) MySQL 3.23.35/3.23.43 (http://www.mysql.com) GD >= 1.8.3 / >= 2.0.1b (http://www.boutell.com/gd/) FreeType 2.0.3-7 (http://www.freetype.org/) #--------------------------------------------------------------------# /** * 3. INSTALL */ /** * 3.1 - Setting Up MySQL */ a) Connect to your mysql server: $ mysql -u -p create a database name "mynews". mysql> create database mynews; mysql> exit; an alternative way to create the database is to use the mysqladmin script. Ex. $ mysqladmin -u root -p -create mynews b) Cat the file mynews.sql into your news database. for ex. $ mysql -u -p mynews < mynews.sql /** * 3.2 - Setting up MyNews */ MyNews *will not* work with the following php runtime vars turned on. magic_quotes_gpc magic_quotes_runtime it is recommended to either set these values to Off in the your php.ini file, or in a .htaccess in $DOCUMENT_ROOT/.htaccess (only works if you have AllowOverrides set to All in your Apache Config.) The following is what needs to be set in your .htaccess file (if you choose that method). php_flag magic_quotes_gpc off php_flag magic_quotes_runtime off Next you will have to setup the config.inc.php file. It is important to realize that the config.inc.php file needs to be located in a specific path or MyNews *will not* work. config.inc.php should always be located in the $DOCUMENT_ROOT/include/ directory of your webserver. If you are not sure where the $DOCUMENT_ROOT directory is, put the extras/phpinfo.php script in somewhere in your web path and look for the $DOCUMENT_ROOT variable. sh$> $DOCUMENT_ROOT/include/config.inc.php This file is pretty self explanatory, but here's the gist of it. *Note* As of MyNews 4.1.2 you will need to copy: sh$> $DOCUMENT_ROOT/include/config.inc.php.distro to: sh$> $DOCUMENT_ROOT/include/config.inc.php Edit the following config keys in $DOCUMENT_ROOT/config.inc.php: -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['debug']['timer'] (on|off) If this key is turned on, you will see the time (in seconds) It took php to generate that page. -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['default'] ['limit'] INTEGER This sets how many items are shown on each archive/search page. ['count'] INTEGER The number of headlines to be shown under the top story. ['theme'] STRING This sets the overall theme of the site. Please see the README section on THEMES if you would like to build additional themes. ['button'] (gd|text) This is how you define whether you want your button images created as dynamic images, or text. ['siteurl'] URL This is the url of your MyNews installation. ['sitename'] STRING This string preceeds everything in the ['desc'] STRING This string only shows up on your news index page, and should accurately represent a brief description of your website. ['channel'] (on|off) This turns on/off the channel file that is generate by posting/editing/delete news items. If turned on it creates a channel file in your base news directory. This can be shared with other sites and is an RSS-.91(Rich Site Summary) file. If you do not understand RSS, I suggest you leave this key turned off. NOTE: Please be sure to read The README section on CHANNEL FILE if you turn this key on. ['channel_file'] FILENAME If the default:channel key is turned on, this is the name of the file that it will generate. ['spam'] ['stop'] (on|off) This replaces the @ sign in email address on posted items to a string defined in the default:spam:string key if turned on. ['string'] STRING This is the string you want to replace the "@" sign in email addresses if you turn on the default:spam:stop key. ['pagebreak'] REGEX This is the regex used to determine where to split your entry into pages. If you don't have an undertstanding of regex, it is not recommended that you change this from it's original value. If you use the default value, your page break tag will be: [pagebreak] -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['mail'] ['admin'] ['email'] EMAIL The email address of the site adminstrator. This is the email address that submission notifications will go to. ['cal'] ['email'] EMAIL The email address of the calendar admin. This key should only be set if the following key is set. When both are set, the calendar admin will be emailed notifications of events matching a defined list of categories. ['list'] LIST This is a colon seperated list of Event types that will be flagged to notify the calendar admin when an event matching a type in the list is posted to the calendar. -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['blocks'] ['left'] LIST This is a colon seperated list of modules/blocks you want displayed on the left-hand side of your MyNews site. The modules can be found in include/blocks/ the modules *must* have the .php extension, and are called by the filename minus the extension. ['right'] LIST Please see the previous description This is for the right side of your MyNews site. /** For Example: * a module named include/blocks/topten.php * would be placed in the LIST as follows: * * $myNewsConf['blocks']['left'] = 'topten' * or * $myNewsConf['blocks']['right'] = 'topten' **/ -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['gd'] ['ver'] (1|2) 1 for GD >= 1.8.3 2 for GD >= 2.0.1 (Beta) Note: If you have GD >= 1.8.3 your thumnails will not look very nice. >= 2.0.1 your thumbnails will look spectacular. -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['button']['font'] ['type'] (plain|ttf) This is the type of font you want to overlay on your button images if the: $myNewsConf['button']['default'] key is set to gd. This will only work if you have TrueType font support compiled into php. /** * Note: * The following keys only apply if $myNewsConf['button']['font']['type] * is set to 'ttf'. **/ ['size'] INTEGER The Size you want your TrueType font to display on your button image. ['path'] PATH This is the fully qualified path to your TrueType font directory. ['name'] FILENAME -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['path'] ['sys']['index'] PATH This is the fully qualified path to your MyNews installation. ['sys']['admin'] PATH This is the fully qualified path to your administration scripts. /** Note: * The ['sys'] (system path) keys *do not* have to have a trailing slash("/") * while the ['web'] (web path) keys *DO* need to have a trailing slash. **/ ['web']['index'] PATH This is the relative path to your MyNews installation. ['web']['admin'] PATH This is the relative path to your administration section. -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['db'] ['hostname'] STRING This is the host where your database will be stored. (most likely: localhost) ['dbUser'] STRING This is the user MyNews will connect to MySQL as. ['dbPass'] STRING This is the password of your MySQL user. Leave it blank if your webserver user does not need a password. ['dbName'] STRING This is the name of the database that will store all of the MyNews tables. /** * The remaining are safe to leave alone and only documented for reference * purposes. **/ ['table'] ['news'] STRING The News table. ['submissions'] STRING The Submissions table. ['comments'] STRING The Comments table. ['authors'] STRING The Authors table. ['sections'] STRING The Sections table. ['calendar'] STRING The Calendar table. -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['scripts'] ['index'] STRING The Index script. ['story'] STRING The Story script. ['archive'] STRING The Archive script. ['comments'] STRING The Comments script. ['about'] STRING The About script. ['submit'] STRING The Submit script. ['search'] STRING The Search script. ['calendar'] STRING The Calendar script. ['event'] STRING The Calendar Event script. ['hof'] STRING The Hall of Fame script. -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['adminScripts'] ['authors'] STRING The Authors admin script. ['news'] STRING The News admin script. ['calendar'] STRING The Calendar admin script. ['preferences'] STRING The User Preferences admin script. -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['format'] ['date'] ['default'] STRING The human readable date format with the time of day. ['nice'] STRING The human readable date format without the time of day. -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['head'] STRING The HTML header file. (See THEMES) ['foot'] STRING The HTML footer file. (See THEMES) -------------------------------------------------------- Key: Possible Value(s): Synopsis: -------------------------------------------------------- ['button'] ['gd'] ['search'] STRING The image you would like to use for your Search button. ['submit'] STRING The image you would like to use for your Submit button. /** Note: * The previous two keys need to be valid html input types. * Please refer to the included config for an example. * **/ ['next'] STRING The image you would like to use for your next button. ['back'] STRING The image you would like to use for your back button. ['text'] ['search'] STRING A plain search button. ['submit'] STRING A plain submit button. ['next'] STRING A text link that says: "::Next::" ['back'] STRING A text link that says: "::Back::" /** * End MyNews Config section **/ Pheewww... okay that should be about the most of it. It is extremely customizable, and it might just take a little digging, but I'm sure you will figure out that it is pretty easy to understand the code. #--------------------------------------------------------------------# /** * 4. PERMISSIONS */ There are three levels of permissions for the administration section. I will go over these levels and what permissions they provide. ----------------------------------------------------------------- | Level | Permissions | ----------------------------------------------------------------- | Author | An author has the ability to do the | | | following: | | | | | | * Post News items. | | | * Edit / Delete News items they posted. | | | | |---------------|-----------------------------------------------| | Editor | An Editor has the ability to do the | | | following: | | | | | | * Post News items. | | | * Edit / Delete any News item. | | | * Post / Delete Submissions. | | | * Post / Edit / Delete Calendar events. | | | | |---------------|-----------------------------------------------| | Admin | An Admin has the ability to do the | | | following: | | | | | | * Post News items. | | | * Edit / Delete any News item. | | | * Post / Delete Submissions. | | | * Post / Edit / Delete any Comments. | | | * Post / Edit / Delete Calendar events. | | | * Modify what Sections show up on the front | | | page. | | | * Add / Edit / Delete Adminstrative Users. | | | | ----------------------------------------------------------------- #--------------------------------------------------------------------# /** * 5. SECTIONS */ When a new Section is created It can only be deleted by someone with access to the database your MyNews data is stored in. There are a couple of reasons I haven't written web base administration for this. 1) If there are multiple items posted under that Section, what section would those items be changed to? 2) A section is not truly deleted until all posted News items below it are. I have left it up to the site administrator to delete sections as they feel necessary. I will provide a couple of example query's on how to accomplish this, however. mysql> select * from sections; +-------+-------------+-------+ | secid | section | front | +-------+-------------+-------+ | 2 | News | 1 | | 4 | Contributed | 0 | | 1 | Features | 0 | | 3 | Reviews | 0 | +-------+-------------+-------+ pick the section you want deleted. Decide if you want to delete all items under that section or change those item's section to another. To Change to another section. * Note: Make sure that is a section that alreay exists in the sections table. is the section you want to delete. mysql> update news set section = '' where section = ''; To Delete everything in the section: * Note: This is unrecoverable (unless you make frequent backups). mysql> delete from news where section = ''; #--------------------------------------------------------------------# /** * 6. THEMES */ Ahhhh, welcome to the wonderful section on themeing. Themeing is pretty easy as long as you follow a few simple steps. 1) The easiest way to learn theming is to hack up an existing one. They can be found in: /path/to/mynews/install/htdocs/include/themes// with the image directories in: /path/to/mynews/install/htdocs/images/themes// 2) You will always need a file call themefunc.php In this file, there are two functions that are necessary. section_header() section_footer() These functions should call your table header and footer files. 3) You will *always* need a header.tmpl and footer.tmpl file. In this file, you will need to call the themefunc.php with an include(); or require(); 4) You will *always* need a css.tmpl file. Whether is has anything in it or not, is up to you. 5) Each of these files need to be in a directory called: /path/to/mynews/install/htdocs/include/themes// where is the name of your theme. Again, themeing is not *that* hard, but it does take a little practice and an understanding of php. If your build a theme send an email to me (See CONTACT) with the theme tar.gz'd and I'll put a link to it from the MyNews homepage. #--------------------------------------------------------------------# /** * 7. CHANNEL FILE */ If the ['default']['channel'] config key is turned on, MyNews will write an RSS* file with the headlines from your 10 newest News Items. This ['default']['channel_file'] config key is necessary if you set ['default']['channel'] to 'on'. This will create a file in your MyNews installation directory by the name of whatever you set the ['default']['channel_file'] key to. There are a few different ways to accomplish getting the Channel File setup. 1) You create an empty file with the correct owner/permissions before turning the key on. $ touch /path/to/mynews/install/htdocs/channel.rdf $ chgrp nobody /path/to/mynews/install/htdocs/channel.rdf $ chmod 664 /path/to/mynews/install/htdocs/channel.rdf This *is* recommended. 2) You create the file, and set it to writable by anyone. $ touch /path/to/mynews/install/htdocs/channel.rdf $ chmod 666 /path/to/mynews/install/htdocs/channel.rdf This is *not* recommended. 3) Your MyNews install directory will either need to be mode 0777 (as the file is written to/read from as the user your webserver runs as. $ chmod 777 /path/to/mynews/install/htdocs This is *not* recommended. * RSS stands for Rich Site Summary and can be read about at: http://www.webreview.com/1999/10_29/webauthors/10_29_99_2a.shtml #--------------------------------------------------------------------# /** * 8. MISC */ a.) To change the verbage in the "about" section, edit the file: $DOCUMENT_ROOT/include/about.inc #--------------------------------------------------------------------# /** * 9. CONTACT */ Please contact me at: alien@alienated.org You can find updated versions at: http://www.alienated.org/scripts/ To see a demo, please go to: http://www.alienated.org I have setup a mailing list for users of MyNews. To join the mailing list, send an e-mail with: "subscribe mynews-help in the subject field, to: majordomo@wtlug.org To send a message to the list, use: mynews-help@wtlug.org To get off the list (who'd want that...) send a mail with: "unsubscribe mynews-help " in the subject field to: majordomo@wtlug.org Regards, Mike McMurray (alien@alienated.org)