"SfR Fresh" - the SfR Freeware/Shareware Archive 
Member "MyNews-4.2.2/README" of archive MyNews-4.2.2.tar.gz:
As a special service "SfR Fresh" has tried to format the requested source page into HTML format using source code syntax highlighting with prefixed line numbers.
Alternatively you can here view or download the uninterpreted source code file.
That can be also achieved for any archive member file by clicking within an archive contents listing on the first character of the file(path) respectively on the according byte size field.
1 README:
2
3
4 /** Note:
5 * If you are upgrading from a previous version of MyNews-4, please
6 * see the UPGRADING file in the source distribution.
7 **/
8
9 1. GETTING STARTED
10 1.1 Intro
11 1.2 Features
12 1.3 The Administration Interface
13 2. REQUIREMENTS
14 3. INSTALL
15 3.1 MySql setup
16 3.2 MyNews setup
17 4. PERMISSIONS
18 5. SECTIONS
19 6. THEMES
20 7. CHANNEL FILE
21 8. MISC
22 9. CONTACT
23
24 #--------------------------------------------------------------------#
25 /**
26 * 1. GETTING STARTED
27 **/
28 /**
29 * 1.1 - Intro
30 **/
31 This is MyNews 4
32
33 This only works with MySQL at the moment. I plan on building in
34 database abstraction (most likely with PEAR) in the next major release,
35 which will be 5.0. If you want to make it work with other databases,
36 please feel free to do so.
37
38 First thing I would like to do, is to give credit where it is due. The
39 idea for MyNews wasn't mine. If it weren't for Stig-Ørjan Smelror of
40 winther.net (stig@winther.net) MyNews probably wouldn't have been born.
41 Stig wrote the inital release of MyNews and it suited his needs. I then
42 took over the project. Since the Release of version 2.0, none of Stig's
43 code remains, but the concept is still his. Therefore, I would like to
44 thank him again.
45
46 Other people of mention are: JedTheHead from http://www.organization.cx.
47 If it weren't for his insight on the comments system, I probably would
48 have lost interest a looong time ago.
49
50 Finally, I would like to thank everyone who uses/has used/ and
51 contributed to the project. I'm trying to get things going again, and
52 hope that the project takes off after a long vacation.
53
54 Thanks again everyone!
55
56 --Mike
57
58 /**
59 * 1.2 - Features
60 **/
61
62 Now, on to features, etc...... okay. This script features the follwing
63 administrative tools:
64
65 1. Posting/Deleting/Editing news through a web interface.
66 2. A nested comment system.
67 3. Author administration with Author/Editor/Admin permissions
68 (See the README section on PERMISSIONS)
69 4. Comment administration.
70 5. Submission adminstration.
71 6. Calendar administration.
72
73 /**
74 * 1.3 - The Administration Interface
75 **/
76
77 The admin interface is pretty self explanatory. I suggest you just play
78 around with it to get used to it.
79
80 *NOTE*
81 The default login to the admin section is as follows:
82 User: admin
83 Pass: abc123
84
85 #--------------------------------------------------------------------#
86 /**
87 * 2. REQUIREMENTS
88 */
89
90 Following are things that are required for MyNews to work:
91 Note: If you want me to test it on a different build, provide me a host ;]
92
93 --------------------------------------------------------
94 Package: Tested Versions: URL:
95 --------------------------------------------------------
96 PHP 4.0.6/4.1.2 (http://www.php.net)
97 MySQL 3.23.35/3.23.43 (http://www.mysql.com)
98 GD >= 1.8.3 / >= 2.0.1b (http://www.boutell.com/gd/)
99 FreeType 2.0.3-7 (http://www.freetype.org/)
100
101 #--------------------------------------------------------------------#
102 /**
103 * 3. INSTALL
104 */
105 /**
106 * 3.1 - Setting Up MySQL
107 */
108
109 a) Connect to your mysql server:
110 $ mysql -u <username> -p
111
112 create a database name "mynews".
113
114 mysql> create database mynews;
115 mysql> exit;
116
117 an alternative way to create the database is to use the
118 mysqladmin script. Ex.
119
120 $ mysqladmin -u root -p -create mynews
121
122 b) Cat the file mynews.sql into your news database. for ex.
123
124 $ mysql -u <username> -p mynews < mynews.sql
125
126 /**
127 * 3.2 - Setting up MyNews
128 */
129
130 MyNews *will not* work with the following php runtime vars turned on.
131 magic_quotes_gpc
132 magic_quotes_runtime
133
134 it is recommended to either set these values to Off in the your php.ini
135 file, or in a .htaccess in $DOCUMENT_ROOT/.htaccess (only works if you
136 have AllowOverrides set to All in your Apache Config.) The following is
137 what needs to be set in your .htaccess file (if you choose that method).
138
139 php_flag magic_quotes_gpc off
140 php_flag magic_quotes_runtime off
141
142 Next you will have to setup the config.inc.php file.
143
144 It is important to realize that the config.inc.php file needs to be
145 located in a specific path or MyNews *will not* work.
146
147 config.inc.php should always be located in the $DOCUMENT_ROOT/include/
148 directory of your webserver. If you are not sure where the
149 $DOCUMENT_ROOT directory is, put the extras/phpinfo.php script in
150 somewhere in your web path and look for the $DOCUMENT_ROOT variable.
151
152 sh$> $DOCUMENT_ROOT/include/config.inc.php
153
154 This file is pretty self explanatory, but here's the gist of it.
155
156 *Note* As of MyNews 4.1.2 you will need to copy:
157
158 sh$> $DOCUMENT_ROOT/include/config.inc.php.distro
159 to:
160 sh$> $DOCUMENT_ROOT/include/config.inc.php
161
162 Edit the following config keys in $DOCUMENT_ROOT/config.inc.php:
163
164 --------------------------------------------------------
165 Key: Possible Value(s): Synopsis:
166 --------------------------------------------------------
167 ['debug']['timer'] (on|off) If this key is turned on, you will
168 see the time (in seconds)
169 It took php to generate that page.
170
171 --------------------------------------------------------
172 Key: Possible Value(s): Synopsis:
173 --------------------------------------------------------
174 ['default']
175 ['limit'] INTEGER This sets how many items are shown
176 on each archive/search page.
177
178 ['count'] INTEGER The number of headlines to be shown
179 under the top story.
180
181 ['theme'] STRING This sets the overall theme of the
182 site. Please see the README section
183 on THEMES if you would like to build
184 additional themes.
185
186 ['button'] (gd|text) This is how you define whether you
187 want your button images created
188 as dynamic images, or text.
189
190 ['siteurl'] URL This is the url of your MyNews
191 installation.
192
193 ['sitename'] STRING This string preceeds everything
194 in the <TITLE></TITLE>
195
196 ['desc'] STRING This string only shows up on your
197 news index page, and should
198 accurately represent a brief
199 description of your website.
200
201 ['channel'] (on|off) This turns on/off the channel file
202 that is generate by
203 posting/editing/delete news items.
204 If turned on it creates a channel
205 file in your base news directory.
206 This can be shared with other sites
207 and is an RSS-.91(Rich Site Summary)
208 file. If you do not understand RSS,
209 I suggest you leave this key turned
210 off. NOTE: Please be sure to read
211 The README section on CHANNEL FILE
212 if you turn this key on.
213
214 ['channel_file'] FILENAME If the default:channel key is turned
215 on, this is the name of the file
216 that it will generate.
217
218 ['spam']
219 ['stop'] (on|off) This replaces the @ sign in email
220 address on posted items to a string
221 defined in the default:spam:string
222 key if turned on.
223
224 ['string'] STRING This is the string you want to
225 replace the "@" sign in email
226 addresses if you turn on the
227 default:spam:stop key.
228
229 ['pagebreak'] REGEX This is the regex used to determine
230 where to split your entry into
231 pages. If you don't have an
232 undertstanding of regex, it is not
233 recommended that you change this
234 from it's original value. If you
235 use the default value, your page
236 break tag will be: [pagebreak]
237
238
239 --------------------------------------------------------
240 Key: Possible Value(s): Synopsis:
241 --------------------------------------------------------
242 ['mail']
243 ['admin']
244 ['email'] EMAIL The email address of the site
245 adminstrator. This is the email
246 address that submission
247 notifications will go to.
248
249 ['cal']
250 ['email'] EMAIL The email address of the calendar
251 admin. This key should only be
252 set if the following key is set.
253 When both are set, the calendar
254 admin will be emailed notifications
255 of events matching a defined list
256 of categories.
257
258 ['list'] LIST This is a colon seperated list of
259 Event types that will be flagged to
260 notify the calendar admin when an
261 event matching a type in the list
262 is posted to the calendar.
263
264 --------------------------------------------------------
265 Key: Possible Value(s): Synopsis:
266 --------------------------------------------------------
267 ['blocks']
268 ['left'] LIST This is a colon seperated list of
269 modules/blocks you want displayed
270 on the left-hand side of your
271 MyNews site. The modules can be
272 found in include/blocks/
273 the modules *must* have the .php
274 extension, and are called by the
275 filename minus the extension.
276
277 ['right'] LIST Please see the previous description
278 This is for the right side of your
279 MyNews site.
280
281 /** For Example:
282 * a module named include/blocks/topten.php
283 * would be placed in the LIST as follows:
284 *
285 * $myNewsConf['blocks']['left'] = 'topten'
286 * or
287 * $myNewsConf['blocks']['right'] = 'topten'
288 **/
289
290 --------------------------------------------------------
291 Key: Possible Value(s): Synopsis:
292 --------------------------------------------------------
293 ['gd']
294 ['ver'] (1|2) 1 for GD >= 1.8.3
295 2 for GD >= 2.0.1 (Beta)
296
297 Note: If you have GD >= 1.8.3 your
298 thumnails will not look very nice.
299 >= 2.0.1 your thumbnails will look
300 spectacular.
301
302 --------------------------------------------------------
303 Key: Possible Value(s): Synopsis:
304 --------------------------------------------------------
305 ['button']['font']
306 ['type'] (plain|ttf) This is the type of font you want
307 to overlay on your button images
308 if the:
309 $myNewsConf['button']['default']
310 key is set to gd. This will only
311 work if you have TrueType font
312 support compiled into php.
313
314 /**
315 * Note:
316 * The following keys only apply if $myNewsConf['button']['font']['type]
317 * is set to 'ttf'.
318 **/
319
320 ['size'] INTEGER The Size you want your TrueType
321 font to display on your button
322 image.
323
324 ['path'] PATH This is the fully qualified path
325 to your TrueType font directory.
326
327 ['name'] FILENAME
328
329 --------------------------------------------------------
330 Key: Possible Value(s): Synopsis:
331 --------------------------------------------------------
332 ['path']
333 ['sys']['index'] PATH This is the fully qualified path
334 to your MyNews installation.
335
336 ['sys']['admin'] PATH This is the fully qualified path
337 to your administration scripts.
338
339 /** Note:
340 * The ['sys'] (system path) keys *do not* have to have a trailing slash("/")
341 * while the ['web'] (web path) keys *DO* need to have a trailing slash.
342 **/
343
344 ['web']['index'] PATH This is the relative path to your
345 MyNews installation.
346
347 ['web']['admin'] PATH This is the relative path to your
348 administration section.
349
350 --------------------------------------------------------
351 Key: Possible Value(s): Synopsis:
352 --------------------------------------------------------
353 ['db']
354 ['hostname'] STRING This is the host where your database
355 will be stored.
356 (most likely: localhost)
357
358 ['dbUser'] STRING This is the user MyNews will connect
359 to MySQL as.
360
361 ['dbPass'] STRING This is the password of your MySQL
362 user. Leave it blank if your
363 webserver user does not need a
364 password.
365
366 ['dbName'] STRING This is the name of the database
367 that will store all of the MyNews
368 tables.
369
370 /**
371 * The remaining are safe to leave alone and only documented for reference
372 * purposes.
373 **/
374
375 ['table']
376 ['news'] STRING The News table.
377 ['submissions'] STRING The Submissions table.
378 ['comments'] STRING The Comments table.
379 ['authors'] STRING The Authors table.
380 ['sections'] STRING The Sections table.
381 ['calendar'] STRING The Calendar table.
382
383 --------------------------------------------------------
384 Key: Possible Value(s): Synopsis:
385 --------------------------------------------------------
386 ['scripts']
387 ['index'] STRING The Index script.
388 ['story'] STRING The Story script.
389 ['archive'] STRING The Archive script.
390 ['comments'] STRING The Comments script.
391 ['about'] STRING The About script.
392 ['submit'] STRING The Submit script.
393 ['search'] STRING The Search script.
394 ['calendar'] STRING The Calendar script.
395 ['event'] STRING The Calendar Event script.
396 ['hof'] STRING The Hall of Fame script.
397
398 --------------------------------------------------------
399 Key: Possible Value(s): Synopsis:
400 --------------------------------------------------------
401 ['adminScripts']
402 ['authors'] STRING The Authors admin script.
403 ['news'] STRING The News admin script.
404 ['calendar'] STRING The Calendar admin script.
405 ['preferences'] STRING The User Preferences admin script.
406
407 --------------------------------------------------------
408 Key: Possible Value(s): Synopsis:
409 --------------------------------------------------------
410 ['format']
411 ['date']
412 ['default'] STRING The human readable date format
413 with the time of day.
414
415 ['nice'] STRING The human readable date format
416 without the time of day.
417
418 --------------------------------------------------------
419 Key: Possible Value(s): Synopsis:
420 --------------------------------------------------------
421 ['head'] STRING The HTML header file. (See THEMES)
422 ['foot'] STRING The HTML footer file. (See THEMES)
423
424 --------------------------------------------------------
425 Key: Possible Value(s): Synopsis:
426 --------------------------------------------------------
427 ['button']
428 ['gd']
429 ['search'] STRING The image you would like to use
430 for your Search button.
431
432 ['submit'] STRING The image you would like to use
433 for your Submit button.
434
435 /** Note:
436 * The previous two keys need to be valid html input types.
437 * Please refer to the included config for an example.
438 *
439 **/
440
441 ['next'] STRING The image you would like to use
442 for your next button.
443
444 ['back'] STRING The image you would like to use
445 for your back button.
446 ['text']
447 ['search'] STRING A plain search button.
448 ['submit'] STRING A plain submit button.
449 ['next'] STRING A text link that says: "::Next::"
450 ['back'] STRING A text link that says: "::Back::"
451
452 /**
453 * End MyNews Config section
454 **/
455
456 Pheewww... okay that should be about the most of it. It is extremely
457 customizable, and it might just take a little digging, but I'm sure you
458 will figure out that it is pretty easy to understand the code.
459
460 #--------------------------------------------------------------------#
461 /**
462 * 4. PERMISSIONS
463 */
464
465 There are three levels of permissions for the administration section. I
466 will go over these levels and what permissions they provide.
467
468
469 -----------------------------------------------------------------
470 | Level | Permissions |
471 -----------------------------------------------------------------
472 | Author | An author has the ability to do the |
473 | | following: |
474 | | |
475 | | * Post News items. |
476 | | * Edit / Delete News items they posted. |
477 | | |
478 |---------------|-----------------------------------------------|
479 | Editor | An Editor has the ability to do the |
480 | | following: |
481 | | |
482 | | * Post News items. |
483 | | * Edit / Delete any News item. |
484 | | * Post / Delete Submissions. |
485 | | * Post / Edit / Delete Calendar events. |
486 | | |
487 |---------------|-----------------------------------------------|
488 | Admin | An Admin has the ability to do the |
489 | | following: |
490 | | |
491 | | * Post News items. |
492 | | * Edit / Delete any News item. |
493 | | * Post / Delete Submissions. |
494 | | * Post / Edit / Delete any Comments. |
495 | | * Post / Edit / Delete Calendar events. |
496 | | * Modify what Sections show up on the front |
497 | | page. |
498 | | * Add / Edit / Delete Adminstrative Users. |
499 | | |
500 -----------------------------------------------------------------
501
502 #--------------------------------------------------------------------#
503 /**
504 * 5. SECTIONS
505 */
506
507 When a new Section is created It can only be deleted by someone
508 with access to the database your MyNews data is stored in.
509
510 There are a couple of reasons I haven't written web base
511 administration for this.
512
513 1) If there are multiple items posted under that Section, what
514 section would those items be changed to?
515
516 2) A section is not truly deleted until all posted News items
517 below it are.
518
519 I have left it up to the site administrator to delete sections as
520 they feel necessary. I will provide a couple of example query's on
521 how to accomplish this, however.
522
523 mysql> select * from sections;
524 +-------+-------------+-------+
525 | secid | section | front |
526 +-------+-------------+-------+
527 | 2 | News | 1 |
528 | 4 | Contributed | 0 |
529 | 1 | Features | 0 |
530 | 3 | Reviews | 0 |
531 +-------+-------------+-------+
532
533 pick the section you want deleted. Decide if you want to delete all
534 items under that section or change those item's section to another.
535
536 To Change to another section.
537 * Note: Make sure that <new section> is a section that alreay exists
538 in the sections table. <old section> is the section you want
539 to delete.
540
541 mysql> update news set section = '<new section>'
542 where section = '<old section>';
543
544 To Delete everything in the section:
545 * Note: This is unrecoverable (unless you make frequent backups).
546
547 mysql> delete from news where section = '<old section>';
548
549 #--------------------------------------------------------------------#
550 /**
551 * 6. THEMES
552 */
553
554 Ahhhh, welcome to the wonderful section on themeing. Themeing is
555 pretty easy as long as you follow a few simple steps.
556
557 1) The easiest way to learn theming is to hack up an existing one.
558 They can be found in:
559 /path/to/mynews/install/htdocs/include/themes/<theme>/
560 with the image directories in:
561 /path/to/mynews/install/htdocs/images/themes/<theme>/
562
563 2) You will always need a file call themefunc.php
564 In this file, there are two functions that are necessary.
565
566 section_header()
567 section_footer()
568
569 These functions should call your table header and footer files.
570
571 3) You will *always* need a header.tmpl and footer.tmpl file.
572 In this file, you will need to call the themefunc.php with an
573 include();
574 or
575 require();
576
577 4) You will *always* need a css.tmpl file. Whether is has anything
578 in it or not, is up to you.
579
580 5) Each of these files need to be in a directory called:
581 /path/to/mynews/install/htdocs/include/themes/<theme>/
582 where <theme> is the name of your theme.
583
584 Again, themeing is not *that* hard, but it does take a little practice
585 and an understanding of php.
586
587 If your build a theme send an email to me (See CONTACT) with the theme
588 tar.gz'd and I'll put a link to it from the MyNews homepage.
589
590 #--------------------------------------------------------------------#
591 /**
592 * 7. CHANNEL FILE
593 */
594
595 If the ['default']['channel'] config key is turned on, MyNews will
596 write an RSS* file with the headlines from your 10 newest News Items.
597
598 This ['default']['channel_file'] config key is necessary if you set
599 ['default']['channel'] to 'on'.
600
601 This will create a file in your MyNews installation directory by the
602 name of whatever you set the ['default']['channel_file'] key to.
603
604 There are a few different ways to accomplish getting the Channel File
605 setup.
606
607
608 1) You create an empty file with the correct owner/permissions before
609 turning the key on.
610
611 $ touch /path/to/mynews/install/htdocs/channel.rdf
612 $ chgrp nobody /path/to/mynews/install/htdocs/channel.rdf
613 $ chmod 664 /path/to/mynews/install/htdocs/channel.rdf
614
615 This *is* recommended.
616
617 2) You create the file, and set it to writable by anyone.
618
619 $ touch /path/to/mynews/install/htdocs/channel.rdf
620 $ chmod 666 /path/to/mynews/install/htdocs/channel.rdf
621
622 This is *not* recommended.
623
624 3) Your MyNews install directory will either need to be mode 0777 (as the
625 file is written to/read from as the user your webserver runs as.
626
627 $ chmod 777 /path/to/mynews/install/htdocs
628
629 This is *not* recommended.
630
631 * RSS stands for Rich Site Summary and can be read about at:
632 http://www.webreview.com/1999/10_29/webauthors/10_29_99_2a.shtml
633
634 #--------------------------------------------------------------------#
635 /**
636 * 8. MISC
637 */
638
639 a.) To change the verbage in the "about" section, edit the file:
640 $DOCUMENT_ROOT/include/about.inc
641
642 #--------------------------------------------------------------------#
643 /**
644 * 9. CONTACT
645 */
646
647 Please contact me at:
648 alien@alienated.org
649
650 You can find updated versions at:
651 http://www.alienated.org/scripts/
652
653 To see a demo, please go to:
654 http://www.alienated.org
655
656 I have setup a mailing list for users of MyNews.
657 To join the mailing list, send an e-mail with:
658 "subscribe mynews-help <your.email@address.com>
659 in the subject field, to:
660 majordomo@wtlug.org
661
662 To send a message to the list, use:
663 mynews-help@wtlug.org
664
665 To get off the list (who'd want that...) send a mail with:
666 "unsubscribe mynews-help <your.email@address.com>"
667 in the subject field to:
668 majordomo@wtlug.org
669
670 Regards,
671 Mike McMurray
672 (alien@alienated.org)