### Adding a New Page.txt ### version 2.1.1

Weather Website PHP Scripts from Silver Acorn
These programs are distributed in the hope that they may 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.
!!! There is NO guaranteed support !!!

################################################################################

TOPICS
A. A NUMBER OF FACTORS SHOULD BE CONSIDERED
B. NOTES ABOUT "LOOK AND FEEL", AND ALL THOSE FILES BEING LOADED AT THE BEGINNING OF THE PAGE.
C. ACCESSING FILES IN ANOTHER FOLDER
D. LINKING TO OTHER WEBSITES

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A. A NUMBER OF FACTORS SHOULD BE CONSIDERED
1. Do you know what you are doing?
		A wrong step can stop a website!
	View the other pages to see how the pages are constructed - there is a variety to suit the individual page content.

2. To have your new page display in the menu, and be activated from the menu:-
	a. Make a copy of the file new_page.php saving it with the name you wish to appear on the menu.
		or, make a copy of an existing page, saving it as newname.php, and edit it.
	b. Note that newname.php requires settings.php, nav_menu.php and footer.php.
		settings.php does not require editing but must be loaded at the top of the new page.
		nav_menu.php requires editing to add newname.php to the site.
		However, newname.php can be tested before adding it to the menu by changing the url in the browser.
		https://sitename/newname.php
		Once newname.php is working:-
		i.		Decide on the position in the menu.
		ii.	Edit nav_menu.php by copying the existing entry above the newname.php menu location
					to immediately below the existing entry.
				e.g. copy
					<li <?php if($page_id == 'now') {echo 'class="active"';} ?>><a href="now.php">
						<span lang="en">Now</span></a></li>
				and paste
					<li <?php if($page_id == 'now') {echo 'class="active"';} ?>><a href="now.php">
						<span lang="en">Now</span></a></li>
				to the new location, and edit it
					<li <?php if($page_id == 'newname') {echo 'class="active"';} ?>><a href="newname.php">
						<span lang="en">Newname</span></a></li>
		iii.	If there is no newname.css file, rem out the css entry above </head>
					BUT you will probably require a simple newname.css file in the css folder
						to correctly position the page just below the nav_menu - see ./css/index.css for an example.
					e.g.	<!-- <link href="css/newname.css" rel="stylesheet"> -->
					If importing an existing page from elsewhere which has a <style> ........ </style> block in it,
						this can be left in place for testing.
						Once the page is working, in the css folder, create a new file newname.css
						and move the <style> ........ </style> block into the new newname.css file
							remove <style> and </style> from the new .css file.
						remove the <!-- and --> from <link href="css/newname.css" rel="stylesheet"> and test. 
						Size and colors are the most likely css items requiring change to fit the style of this website.
		iv.	The <!-- BOOTSTRAP -->, <!-- jquery --> and <!-- DATA TABLE CSS --> blocks should remain
						as they provide the look and feel of the site.
						If overrides to the style are required, make the changes by adding to or editing newname.css
		v.		<?php include_once('newname_inc.php'); ?> is used to include any data files or additional code blocks
						that are not created directly in newname.php

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

B. NOTES ABOUT "LOOK AND FEEL", AND ALL THOSE FILES BEING LOADED AT THE BEGINNING OF THE PAGE.

"look and feel"
If you are introducing an existing file from another source,
the first thing to address is to make it look like the rest of the site

Tables
Add
<div class="container">
	<div class="half-unit">
immediately before <table>

with matching
	</div>
</div>
immediately after </table>

<div class="container"> controls the width of the table and matches it to the nav_menu width, and makes it responsive
<div class="half-unit"> provides the matching background colour to the nav_menu and the rest of the site.

If there are multiple separate tables then depending on the layout, a new
<div class="container">
	<div class="half-unit">

	</div>
</div>
 set may be required around each table.

As noted in new_page.php,
Not every one of the		<!-- BOOTSTRAP -->
								<!-- jquery -->
								<!-- DATA TABLE CSS -->
	may be required.
		check other pages that are similar to the one you are creating and use that set first.
		You can rem them out one at a time and see what affect they have on the new page
		If you are adding a language, check a page that most looks like the new page and follow
		how it is configured in settings and nav_menu

NOTE that with style/css , a style always over rides one that came before, so sometimes there are repeating declarations in different blocks of a page as an earlier block may have required a specific style.


C. ACCESSING FILES IN ANOTHER FOLDER

If filename.ext is in a subfolder, e.g.
	/mxtest/subfolder/filename.ext
then to access a file in subfolder from mxtest, the include should be 

<?php include( './subfolder/filename.ext' ) ?> - single quotes may be required in some situations but usually it does not matter which is used (provided the pair is the same!).
The ./ means only look in this level

If filename.ext is in a folder at the same level as mxtest, e.g.
	.
	.
	/mxtest/subfolder/filename.ext
	/samelevel/filename.ext
	.
	.
then to access a file in samelevel from mxtest, the include should be 

<?php include( '../samelevel/filename.ext' ) ?> - single quotes may be required in some situations but usually it does not matter which is used (provided the pair is the same!).
the ../ means go up one level

Note that include_once( )	and require_once( ) ensure that the file is loaded once and is accessible to other pages, and if called again in another page it will not be loaded again but the existing loaded file will be used.
If you are not sure which to use, google it, or see below for a shortened version of what is in the link(s) below

https://www.php.net/manual/en/function.include.php
include
(PHP 4, PHP 5, PHP 7)
The include statement includes and evaluates the specified file.

The documentation below also applies to require.
Files are included based on the file path given or, if none is given, the include_path specified. If the file isn't found in the include_path, include will finally check in the calling script's own directory and the current working directory before failing. The include construct will emit an E_WARNING if it cannot find a file; this is different behavior from require, which will emit an E_ERROR.

If a path is defined — whether absolute (starting with a drive letter or \ on Windows, or / on Unix/Linux systems) or relative to the current directory (starting with . or ..) — the include_path will be ignored altogether. For example, if a filename begins with ../, the parser will look in the parent directory to find the requested file.

https://www.php.net/manual/en/function.include-once.php
include_once
(PHP 4, PHP 5, PHP 7)
The include_once statement includes and evaluates the specified file during the execution of the script. This is a behavior similar to the include statement, with the only difference being that if the code from a file has already been included, it will not be included again, and include_once returns TRUE. As the name suggests, the file will be included just once.

include_once may be used in cases where the same file might be included and evaluated more than once during a particular execution of a script, so in this case it may help avoid problems such as function redefinitions, variable value reassignments, etc.

https://www.php.net/manual/en/function.require.php
require ¶
(PHP 4, PHP 5, PHP 7)
require is identical to include except upon failure it will also produce a fatal E_COMPILE_ERROR level error. In other words, it will halt the script whereas include only emits a warning (E_WARNING) which allows the script to continue. 

https://www.php.net/manual/en/function.require-once.php
require_once ¶
(PHP 4, PHP 5, PHP 7)
The require_once statement is identical to require except PHP will check if the file has already been included, and if so, not include (require) it again.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

DROP DOWN MENU ITEM:-
Adding a drop down menu item to provide a list of additional pages / links.

nav_menu.php contains an example of a drop down menu - Davis Live Consoles

First create a working new page in the site as detailed above.
Test it by opening it directly on the url of your site.
Once you have a working stand alone page, then it can be added to a dropdown menu.

The structure is:-

						<?php if(($page_id == 'newpage1') || ($page_id == 'newpage2') || ($page_id == 'newpage3'))
							{echo '<li class="dropdown active">';} else {echo '<li class="dropdown">';} ?>

							<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">
							<span lang="en">New Pages</span><span class="caret"></span></a>

						<ul class="dropdown-menu">

							<li <?php if($page_id == 'newpage1') {echo 'class="active"';} ?>>
								<a href="newpage1.php"><span lang="en">New Page1</span></a></li>

							<li <?php if($page_id == 'newpage2') {echo 'class="active"';} ?>>
								<a href="newpage2.php"><span lang="en">New Page2.php</span></a></li>

							<li <?php if($page_id == 'newpage3') {echo 'class="active"';} ?>>
								<a href="newpage3.php"><span lang="en">New Page3.php</span></a></li>

						</ul></li>


The basic structure is an unsorted list
<li class="dropdown	 >

	<ul class="dropdown-menu">

		<li>			 </li>

		<li>			 </li>

		<li>			 </li>

	</ul>

</li>

The two lines
	<?php if(($page_id == 'newpage1') || ($page_id == 'newpage2') || ($page_id == 'newpage3'))
	{echo '<li class="dropdown active">';} else {echo '<li class="dropdown">';} ?>
	
simply change the status of the menu item seen in the main menu to indicate if it is active or not
AND
initiate the outer list structure.
	'<li class="dropdown active"> or <li class="dropdown">

The next two lines create the drop down mode
and
Name the drop down list for nav_menu.
The <span lang="en"> and </span> allow this item to be translated. ALL the text inside the lang spans must be added to the relevant langlib xx.json file(s) for each language being supported. Refer to the readme file in the langlib folder to assist with adding translations.
		<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">
		<span lang="en">New Pages</span><span class="caret"></span></a>

Next
	<ul class="dropdown-menu">
and
	</ul>
establish the form of the unsorted list as "drop down"

Each 
	<li <?php if($page_id == 'newpage3') {echo 'class="active"';} ?>>
		<a href="newpage3.php"><span lang="en">New Page3.php</span></a></li>
creates the menu item in the drop down list.

the final
</li>
closes out the outer list structure.

So there is 
<li dropdown....>
	<ul>
		<li> .. page1 .. </li>
		<li> .. page2 .. </li>
		<li> .. page3 .. </li>
		<li> .. etc	 .. </li>
	</ul>
</li>

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

D. LINKING TO OTHER WEBSITES
links_singledropdn.html
There is an example of a menu structure in the file links_singledropdn.html which is (included) into the nav_menu.
Here is an example of two ways to add links to another website.

a. The first links directly to another site in the same domain.
b. The third links to a remote site using the full URL
The changes are made in nav_menu.php
Near the end of the file - immediately BEFORE this code at the end of the file,

				</ul>
			</div> <!-- nav-collapse -->
		</div>
	</div>
<!-- END NAVIGATION MENU -->

Insert this block of code (including a blank line before and after - makes it easier avoid errors!)

						<li <?php if(!("link1"))
							{echo '<li class="dropdown active">';} else {echo '<li class="dropdown">';} ?>
							<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">
							<span lang="en">Alternate Sites</span>&#9660;</a>
						<ul class="dropdown-menu">
						<li>
							<a href="https://silveracorn.nz/weather/" title="Saratoga template website" rel="noopener noreferrer" target="_blank"><span lang="en">Saratoga</span></a>
						</li>
						<li <?php echo ''; ?>>
							<a href="../cumulus1/" title="Cumulus1 template website" rel="noopener noreferrer" target="_blank"><span lang="en">MXUI Style Cumulus1</span></a>
						</li>
						<li <?php echo ''; ?>>
						</li>
						</ul></li>

Then, replace the "....." in
 <a href="....." title="....." rel="noopener noreferrer" target="_blank"><span lang="en">.....</span></a></li>
to suit your requirements.

Any number of
						<li <?php echo ''; ?>>
							<a href="....." title="....." rel="noopener noreferrer" target="_blank"><span lang="en">.....</span></a>
						</li>
links may be added.

The first example links out through the internet so may be slower in operation
The second example links to a website in the same domain.
NOTE:- this structure is different from the others as there is no $page_id so there is some dummy code to
	enable the <a href= external links to work.
	This also means this menu item behaves differently from the others.
		The menu item does not stay 'active'
		The dropdown item last selected does NOT have a coloured background.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

E: DROPDOWN MENU MENU INSIDE A DROPDOWN MENU.
There is a more complex example of a menu structure in the file links_multidropdn.html which is (included).
It was created as a separate file to simplify the nav_menu file, and to make it easier to work with.
The settings.php options provides for including a single drop down, or multi dropdown menu.
The multi drop shows dropdowns with local and external links as well as a single list not in a dropdown.

Enjoy!
EOF