From e8a80108c8a4f4a3297864bae5d7e6de26cb0fee Mon Sep 17 00:00:00 2001 From: Bruce Bannon Date: Sat, 16 Nov 2024 01:20:54 -0700 Subject: [PATCH] Rework phpDoc header --- includes/css/styles.php | 156 +++++++++++++++++++++++----------------- 1 file changed, 90 insertions(+), 66 deletions(-) diff --git a/includes/css/styles.php b/includes/css/styles.php index 82096d82e..11e4c6ad1 100644 --- a/includes/css/styles.php +++ b/includes/css/styles.php @@ -2,11 +2,6 @@ /** * Dynamic CSS styles used in WebCalendar. * - * @author Craig Knudsen - * @copyright Craig Knudsen, , http://k5n.us/webcalendar - * @license https://gnu.org/licenses/old-licenses/gpl-2.0.html GNU GPL - * @package WebCalendar - * * HOW TO READ THIS DOCUMENT * * There are two main parts to every CSS style: 'selector' & 'declaration'. @@ -14,11 +9,12 @@ * body { * color: red; * } + * * The selector in the example above is 'body', * while its declaration is 'color: red;'. * Each declaration has two parts: 'property' & 'value'. * - * In the example above, there is only one declaraion ("color: red;"). + * In the example above, there is only one declaration ("color: red;"). * For that declaration, the PROPERTY is "color" and the VALUE is "red". * * NOTE: Each property must be followed by a colon (:), @@ -31,81 +27,99 @@ * color: red; * font-size: 12px; * } + * * In the example above, there are three declarations: * background: black; * color: red; * font-size: 12px; * - * NOTE: The declarations for a given style must be contained - * within curly brackets ({ }). + * However, beware of the "gotcha" of using a shorthand, i.e. 'background', + * because it resets ALL the parts not specified to 'initial'. + * + * The above would be better/safer using: + * 'background-color: black;' + * + * NOTE: The declarations for a given style + * must be contained within curly brackets ({ } * * PHP VARIABLES USED TO STYLE WEBCALENDAR * - * BGCOLOR - background-color for the page - * CELLBG - background-color for normal cells - * (not weekends, today, or any other types of cells) - * FONTS - default font-family - * H2COLOR - text color for text within h2 tags - * MYEVENTS - text color for users' events - * OTHERMONTHBG - background-color for cells that belong to other month - * POPUP_BG - background-color for event popups - * POPUP_FG - text color for event popups - * TABLEBG - background-color for tables - * (typically used when the table also has cellspacing, - * thereby creating a border effect) - * TEXTCOLOR - default text color - * THBG - background-color for table headers - * THFG - text color for table headers - * TODAYCELLBG - background-color for cells that make up today's date - * WEEKENDBG - background-color for cells that make up the weekend + * BGCOLOR - background-color for the page + * CELLBG - background-color for normal cells + * (not weekends, today, or any other types of cells) + * FONTS - default font-family + * H2COLOR - text color for text within h2 tags + * MYEVENTS - text color for users' events + * OTHERMONTHBG - background-color for cells that belong to other month + * POPUP_BG - background-color for event popups + * POPUP_FG - text color for event popups + * TABLEBG - background-color for tables + * (typically used when the table also has cellspacing, + * thereby creating a border effect) + * TEXTCOLOR - default text color + * THBG - background-color for table headers + * THFG - text color for table headers + * TODAYCELLBG - background-color for cells that make up today's date + * WEEKENDBG - background-color for cells that make up the weekend * * SOME OF THE CSS IDS AND CLASSES USED IN WEBCALENDAR - * #programname - link to webcalendar site - * NOTE: modifying this can make this link disappear - * #viewd .main th - participants cell - * #year.minical - contains ALL months - * NOTE: display: block; here - * keeps the caption vertically close to the day names - * .dayofmonth - numerical date links in main calendars - * .dayofmonth:hover - numerical date links in main calendars on hover - * .entry - links to entries/events - * .entry img - * .layerentry img - * .unapprovedentry img - event (or bullet) icon; - * NOTE: must be defined AFTER the .entry, .layerentry, - * and .unapprovedentry classes. - * .layerentry - links to entries/events on layers - * .main - most display pages use this for calendar content - * .main td.hasevents - only use HASEVENTSBG if it differs from CELLBG - * .minical - styles for minicalendars - * .minical caption - really big number above the minicalendar in day.php - * .minical th - formats the day name (i.e. Sun, Mon, etc) in minicals - * .minitask - table appearing in small task window - * .new - new event icon (i.e. '+' symbol) - * .next img - right arrow images - * .prev img - left arrow images - * .printer - printer-friendly links - * .standard - standard table mainly in prefs.php & admin.php - * .unapprovedentry - links to unapproved entries/events - * .weeknumber - week number in monthview & such - * a - links that don't have a specific class must be - * defined BEFORE all other link-related classes for - * those classes to work. - * img.color - transparent images used for visual color-selection - * img.help - question mark img linking to help sections * - * display: none; is unhidden by includes/css/print_styles.css + * a - links that don't have a specific class must be + * defined BEFORE all other link-related classes for + * those classes to work. + * img.color - transparent images used for visual color-selection + * img.help - question mark img linking to help sections + * + * .dayofmonth - numerical date links in main calendars + * .dayofmonth:hover - numerical date links in main calendars on hover + * .entry - links to entries/events + * .layerentry - links to entries/events on layers + * .unapprovedentry - links to unapproved entries/events + * + * NOTE: ':where()' makes specificity of (selectors) zero. + * And may save typing [in future] by grouping. + * Part of CSS, not SCSS. + * + * :where(.entry, .layerentry, .unapprovedentry) img - event (or bullet) icon + * Specificity would be 0 0 1 for the 'img' tag. + * + * Alternately, 'is()' makes specificity of (selectors) + * whichever is highest + * + * .main - most display pages use this for calendar content + * .main td.hasevents - only use HASEVENTSBG if it differs from CELLBG + * .minical - styles for minicalendars + * .minical caption - really big number above the minicalendar in day.php + * .minical th - formats the day name (i.e. Sun, Mon, etc) in minicals + * .minitask - table appearing in small task window + * .new - new event icon (i.e. '+' symbol) + * .next img - right arrow images + * .prev img - left arrow images + * .printer - printer-friendly links + * .standard - standard table mainly in prefs.php & admin.php + * .weeknumber - week number in monthview & such + * + * #programname - link to webcalendar site + * NOTE: modifying this can make this link disappear + * #viewd .main th - participants cell + * #year.minical - contains ALL months + * NOTE: display: block; here + * keeps the caption vertically close to the day names + * + * "display: none;" is unhidden by 'includes/css/print_styles.css' * for printer-friendly pages and where else needed. * * PHP FUNCTION CALLS + * * A special function, background_css(), will allow the dynamic creation of * gradient images to be used for the background of that selector. The image * file will be created and cached (if enabled) for faster processing and the * url will be returned for inclusion into the final CSS file. - * Example: background_css( $GLOBALS['CELLBG'], 50 ); - * Yields : background: #FFFFFF url( images/cache/FFFFFF-50.png ) repeat-x; + * Example: background_css ( $GLOBALS['CELLBG'], 50 ); + * Yields : background: #FFFFFF url(images/cache/FFFFFF-50.png) repeat-x; * * CSS CACHING AND VIEWING + * * A caching scheme has been implemented to improve performance and reduce * download payloads. This file is now called from a helper file called * 'css_cacher.php'. Its function is to control cache expiration and compress @@ -113,15 +127,25 @@ * * To view the current CSS definitions from your browser, simply run * http://yourserver/css_cacher.php - * The resulting file will contain the color and layout preferences for the - * logged in user or the default values if not logged in. + * The resulting file will contain the color and layout preferences + * for the logged in user or the default values if not logged in. * - * Each page in WebCalendar is assigned a unique ID. This unique ID is - * determined by taking the name of the page & removing any underscores (_). + * Each page in WebCalendar is assigned a unique ID determined by + * taking the name of the page, removing underscores (_) & '.php' + * and Capitalizing the parts. * Example: edit_entry.php - * Results: + * Results: + * + * @author Craig Knudsen + * @copyright Craig Knudsen, , http://k5n.us/webcalendar + * @license https://gnu.org/licenses/old-licenses/gpl-2.0.html GNU GPL + * + * @package WebCalendar */ +/** + * Are you allowed to be here? + */ defined( '_ISVALID' ) or die( 'You cannot access this file directly!' ); /* CSS Variables (Custom Properties) are currently available in all modern browsers. Even IE > 9!