BW-LM body
Manual for BW-LM page
Top bw_logo

Users Manual for BRAEWORKS ® Links Manager (BW-LM) V0.38

Contents
Introduction

This user manual is to aid administrators and managers of the BW-LM.
Supplementary to this manual is the Installation Notes. The Release Notes list the BW-LM change history. General information is available in the About BW-LM.

The LM has dynamic filtering that finds content matching keywords.

Also the most recent changes can be shown. The number of changes within a number of days can be configured.

The LM has an admin search function to aid finding configuration and setup values.

NOTE: The BW-LM is not designed to operate inside a frame or iframe.

Technical Information

BW-LM is based around standard technology. Some effort was made to make the code compatible for browsers with CSS2 and HTML4. CSS3 and HTML5 is used on compatible browsers. PHP 5.3 scripts are used to generate html web pages.

See Compatibility for browser support information.

Installation setup is stored in INI files. Theme customization is also stored in INI files, and is used to generate CSS style sheets. Accompanying installation and theme setting pages are included to make changes. The default settings provide an operational BW-LM.

BW-LM has a number of WYSIWYG web page editors available. The WYSIWYGs included in the BW-LM are standard free downloads from there from TinyMCE and CKEditor web sites. They are supported by code built into the BW-LM. There are six to eight (depending on the server) WYSIWYGs available and the WYSIWYG selection is in the Admin -> Config menu.

Data for users, administrators, managers, groups, page bodies, tools and configuration are stored in an SQLite2 or SQLite3 database. SQLite was chosen due to its easy installation (no database setup required) and it is very suitable for small projects. Automatic database installation code is provided. The SQLite database is initialized when the first web page is generated after installation. Providing an empty initialized database with the default configuration settings.

A basic description of the databases tables used;-

  • Configuration Table - stores company name, web titles, image control, etc., used in the web pages.
  • Users Table - stores username, login counts, encrypted password, group memberships, sort order/priority, enable/disable and administrator enabling. New users can be configured to provide their passwords on first login, or the admin can enter the password.
  • Groups Table - stores group, enable/disable, administrator and managers.
  • Sections Table - stores the section information for links. Number of columns, sort order/priority, group memberships and enable/disable. This table can be exported and imported as CSV files.
  • Links Table - stores the link information. Each link has a section where it should appear. Links have sort order/priority, group memberships, new page and enable/disable. This table can be exported and imported as CSV files.
  • Tools Table - stores the tools information. A special directory has been set aside inside the BW-LM file structure for handy tools, local "hacks" and try outs. Tools have sort order/priority, new page and enable/disable. Stores tool links , group memberships, sort order/priority and enable/disable. The tools appear in left column or in a drop down from the header, and are displayed according to the group settings.

Setup and operational features should be self evident. All install, setup and configuration settings have accompanying information builtin describing each particular setting. The idea was to keep it simple. Remove anything that wasn’t useful or looked too complicated (i.e. make it easy to customize), by providing just the basics. The result has been to make use of CSS to remove as much code as possible. As a result the code has minimal javascript.

BW-LM theme settings are numerous and should self evident. BW-LM is intended for general small web sites required for the generation of user/owner managed web sites. BW-LM can be set to be easily identifiable (due to page headers and footers) so that users know the web site entity.

NOTE: The BW-LM will also work in an aliased folder.

Server System Prerequisites

BW-LM requires the following server requirements to operate;-

  • Apache Web Server 2.2.x installed on LINUX or MS Windows (other PHP compatible web servers should be suitable),
  • PHP 5.3 with PHP SQLite installed, or PHP 5.4 with php-pecl-sqlite installed,
  • BW-LM can be setup as an adjunct to an existing web site, or as a new web site (If a new web site, the apache web server configuration needs to be setup for the new web site.),
  • An SSL certificate, self signed or registered for SSL/https web site encryption,
  • http (port 80) for default home/links page and https (port 443) for login and user designated pages,

To install on Windows, a server bundle like WAMP or XAMPP will need to be installed and setup. It is also recommended that Wget for Windows be installed also.
NOTE: "xampp-win32-5.5.19-0-VC11-installer.exe" (apache, php, MySQL, etc.) was installed and setup on Windows ® 7 Ultimate for development of BW-LM.

To use country checks, the PECL geoip (geoip >= 2.0) is required.

Installation and Update

Note 1: The server set up is beyond the scope of this manual. Some general server side setup information is given here. If help is required, contact your system administrator or tech support.
Note 2: The actual methods used on a particular server may vary from the steps shown here.
Note 3: The BW-LM zip file does not come with user set files that over writes user settings, if they don’t exist the BW-LM will generate default files.

For full user and administration experience use one of the following PC browsers on a desktop or laptop PC;-

  • Windows Internet Explore V11 or higher,
  • Firefox V31 or higher on Windows, LINUX or Apple MAC,
Other web browser have been tested.

A guide to installing and updating BW-LM follows;-

  • If updating the BW-LM, backup the web site.
  • Download the BW-LM zip file "BW-LM-latest.zip" to the web site’s directory.
  • Unzip the "BW-LM-latest.zip" with the overwrite and update options turned on into your web sites directory.
    e.g. unzip -u -o "BW-LM-latest.zip"
      where (-u = update, -o = overwrite)
    This will unzip the BW-LM file structure into the containing (the web site’s) directory.
    If you wish to restore BW-LM to it’s default file structure contents, leave the update option off. And then run Rebuild Setup, see below.
    e.g. unzip -o "BW-LM-latest.zip"
    NOTE: This does not change existing settings, but will remove any code changes made outside of the release.
  • Pointer your browser at "http://your.web.site/site_alias/index.php" (site_alias/ is part of your server setup, usually empty).
    When the BW-LM is first accessed, it will create an empty SQLite database and rebuild all the CSS stylesheets.
    After approximately 20 seconds and went well, the first run web site looks like this;-
    First run
    NOTE: The filename of the log includes the domain name of the web site.
    On an update the appearance will be different. Run the "Admin->Rebuild Setup" to rebuild the web site.
  • Click the User: Login link. On a fresh install you see this;-
    First login
    On an update the appearance maybe different.
  • When no users are setup, a default admin user is;-
    Username: admin
    Paswword: password
    Strongly recommend the admin username be disabled after you have setup another, more secure, user (with admin rights).
    Login to the web site. On a fresh install you see this;-
    Admin empty
    On an update the appearance maybe different.
  • Suggest going to the Setup and Configuration section.

If failures and non functional issues occur, see Trouble shooting

Browser Window Layout

There is an overall web site style settings (part of the Theme settings);

  • Block Style - uses absolute positioning in the browser’s window. The sections and links scrolls between fixed positions of the header and the footer. The tool links and admin links also have fixed positions in the browser’s window. The browser’s window is more easily navigable.
  • Inline Style - uses inline/relative positioning in the browser’s window. Scrolls the header, tool links, admin link, sections and links and footer as one entity. This can make the separate areas of the browser window difficult to navigate to. Where the browser cannot be identified or compatibility issues are known, the BW-LM will use inline style.

The general arrangement of the BW-LM in block mode is;-

  • Header - top section of the window. This can be the standard web page header from the BW-LM which contains standard features. The standard features can be configured by the administer. Or the entire header can be replaced with a customer header. Or the header can be turned off. If the left column is turned off, drop boxes are used to display tool and administration links.
  • Left Column - when enabled and displayed, occupies the left side of the window between the header and footer. The left column displays tool links and administration links. If no tools are setup and no user is logged in, the left column is not displayed. The left column can be turned off, then other means are used to display tool administration link, in the header.
  • Sections and Links Body - occupies the remaining window area. This the window area that displays the sections and links as configured by the administer / manager.
  • Footer - bottom section of the window. This can be the standard web page footer from the BW-LM which contains standard features. The standard features can be configured by the administer. Or the entire footer can be replaced with a customer header. Or the footer can be turned off.

Setup and Configuration

Use a recommended administration web browser.

After logging into the BW-LM, an "Admin" menu in the left column (default), in the header (as a drop down), depending on any previous settings, will appear. The contents of the "Admin" menu are self explanatory, having tooltips (i.e. small pop up boxes with explanatory text) for each link.

After installation or update, the following guide is useful;-

  • Suggest checking out the "Admin" links to get a feel for the available settings.
  • If looking for a possible setting, try the "Admin->Search" link.

To further the general control and operation of the web site, the following maybe useful;-

  • Web site administrators can redirect the web site to another URL. Administrator can still login (using the "http://your.web.site/site_alias/login.php" URI) and administrator the site.
  • Web site administrators can close the web site. Administrator can still login (using the "http://your.web.site/site_alias/login.php" URI) and administrator the site.

Exporting and Importing CSV Files

The Sections and Links tables in the database can be downloaded (exported) as CSV file. And saved to the local computer so that the contents can be edited by a spreadsheet program.

The CSV files use the tab character as the column separator. The first line of the CSV file is the databases table column (column headers) names. The the import table column names and order of the column names must match the export table csv.

The sections table CSV file uses lm_section_name,lm_section_enabled,lm_section_order,lm_section_columns,lm_section_title,lm_section_description,lm_section_group_ids,lm_section_image_url as the header, which is always the first line. The lm_section_name column is regarded as unique and is the index to the table. If imports are done from a CSV file that has multiple rows with the same lm_section_name value, the last one is used.

The sections export the /var/www/vhosts/braeworks.org/public_html/export/lm_sections.csv file in the server filesystem. And is available at lm_sections.csv

Similar to the sections table, the links table which has a CSV file that uses lm_section_name, lm_link_name, lm_link_enabled, lm_link_order, lm_link_title, lm_link_description, lm_link_url, lm_link_image_url, lm_link_new_page, lm_link_ssl, lm_link_add_name2url as the header, which is always the first line. The lm_section_name, lm_link_name columns are regarded as unique and are the index to the table. If imports are done from a CSV file that has multiple rows with the same lm_section_name, lm_link_name value, the last one is used.

The links export use the /var/www/vhosts/braeworks.org/public_html/export/lm_links.csv file in the server filesystem. And is available at lm_links.csv

Local Tools

The BW-LM has a local tools directory at "./localtools", for the installation of web based tools and extras. The local tools folder provides somewhere to put web applications / pages (tools). Each tool should be given a unique directory to occupy. Examples of tools are;- conversion tables, code checkers, procedures, manuals, just to name a few.

If you have tools installed on the host that are not under the "./localtools" directory, these tools can be accessed by using a symlink. This allows these non-local tools to be appear in the Local Tools setup.

Symlinked Local Tools EXAMPLES:
On LINUX, to setup HTdig, make a symlink by going to the "./localtools" directory, and execute "ln -s /usr/share/htdig htdig", where "/usr/share/htdig" is the path to the HTdig web pages. This allows HTdig to be used as the Local Tool.
A similar tool setup can used for the Apache Manual. Execute "ln -s /var/www/manual ApacheManual" in the "./localtools" directory, where "/var/www/manual" is the path to the Apache Manual web pages.
On Windows, a similar symlink can be set by using the mklink command. Execute "mklink /D ApacheManual C:\\xampp\apache\manual" in the "./localtools" directory, where "C:\\xampp\apache\manual" is the path to the Apache Manual web pages.
NOTE: Windows may not have the "mklink" command installed. If not contact your system administrator.

During tool setup, the "./localtools" directory is searched for filename extensions of .htm .php .html and .txt The tool could be a complete sub-web site.

Sitemap

The BW-LM has a search engine compatible XML sitemap generator builtin. As changes are made to configuration and contents of the web site, the sitemap is automatically updated. To manually update the sitemap goto "http://your.web.site/site_alias/index.php?action=update_sitemap".
NOTE: If the sitemap filename is not setup, no sitemap XML is generated.

The XML sitemap is available at "http://your.web.site/site_alias/sitemap.xml" (replace "your.web.site/site_alias/" with your domain name and alias, if any, for BW-LM installation).
NOTE: The name of the sitemap can be configured in the "Admin->Install->Xml Sitemap File" setting. The primary link URL in the sitemap is the same URL in "Admin->Config->Main Web Site URL" setting.

The sitemap can be generated from the command line.

  • On a LINUX server, in a console shell, goto the web site’s cli/ directory and run "./generate_sitemap.sh".
  • On a Windows host, in a command shell, goto the web site’s cli/ folder and run "generate_sitemap.cmd".
Successful sitemap generation looks like this;-
					Starting -> sitemap generator for BW-LM V0.38.
					INFO: Created sitemap "/web-site-root-directory/sitemap.xml" (Link=sitemap.xml)
					Finished -> sitemap generator for BW-LM V0.38.
				
Where sitemap name is set to "sitemap".
If any errors or warnings occurred, these will be printed out.

Trouble Shooting

The BW-LM has installation and updating trouble shooting functions built-in.
NOTE: This does not change existing settings, but will remove any code changes made outside of the release.

If the web site is basically functional, logging in as an administrator and going to the "http://your.web.site/site_alias/index.php?action=rebuild_setup" link will rebuild the web site settings. This can take a minute or so to complete.

If after an update or other problems, the web site is non functional, there is a recovery command available to help fix this.

  • On a LINUX server, in a console shell, goto the web site’s cli/ directory and run "./rebuild.sh".
  • On a Windows host, in a command shell, goto the web site’s cli/ folder and run "rebuild.cmd".
Successful rebuild output looks like this;-
					Starting -> rebuilding setup for BW-LM V0.38.
					INFO: Installation check.
					INFO: No install issues detected.
					INFO: Checking BW-LM V0.38 database for updates.
					INFO: Checking table lm_users
					INFO: Checking table lm_groups
					INFO: Checking table lm_configs
					INFO: Checking table lm_sections
					INFO: Checking table lm_links
					INFO: Checking table lm_tools
					SUCCESS: Checked links_manager.sqlite tables - success
					SUCCESS: Update main_styles.css
					SUCCESS: Update block_styles.css
					SUCCESS: Update inline_styles.css
					INFO: DB updated to V0.38.
					Finished -> rebuilding setup for BW-LM V0.38.
				
If any errors or warnings occurred, these will be printed out.

A basic installation guide is available in the Installation Notes.

File Version Control

When a manager or administrator are logged in, the BW-LM can use "Subversion" (SVN), if available, to aid in administration and checking of the site. Hovering the mouse over the BRAEWORKS logo in the about or manual pages shows the current SVN version status of the website. This reports the lowest and highest SVN revision number of the web site. The revision numbers can used to identify changes.

To use the SVN features, the system administrator will need to install the PECL SVN package.

License

GNU General Public License, version 2. See "http://www.gnu.org/licenses/gpl-2.0.html"

More Information and Feedback

Release Notes.

Hints, corrections and suggestions are always welcome. Email Feedback.