Introduction

GenHelm uses a web browser interface to maintain all components. GenHelm is designed for use on up-to-date versions of Google's Chrome browser, Mozilla's Firefox or Microsoft Edge. Other modern browsers may also work. Developers interact with GenHelm's integrated generation environment using a simple command line interface. Most of the time you will need only two commands:

  1. Edit to read in a new specification.
  2. Stow to save the specification while at the same time generating the underlying components.

This help describes the steps that are necessary when creating a new website from scratch.

Entering Commands

All commands are entered into the command line depicted here:

All commands are entered using the command line field

After typing a command you can either submit the command by pressing the <Enter> key or you can click on the arrow button next to the command field. An additional option is available for the stow command. To submit this command you may use the keyboard shortcut "<ctrl>s". In fact, it is a good idea to get into the habit of using <ctrl>s to stow your components since this is the most productive method of doing so.

Website Folders and Files

In a typical setup, websites are stored in the file system under two main directories:

  1. public_html/sitedirectory/ is used to store folders that require public access through http (or https). This is mainly for files such as images, css, JavaScript and PDF documents.
  2. private_data/sitedirectory/ is used to store folders that are only accessible via code. Things like php classes and includes as well as data files.

Any number of websites can be maintained and/or hosted within a single GenHelm environment provided each site contains a matching subfolder within the main public_html and private_data folders.

Defining Authorization

Only developers who are defined to the genhelm Group with the Role site-creator are allowed to create new website. If your user id is not configured with this group/role combination change this configuration before proceeding.

In order to create sites users must belong to the genhelm group with role site-creator

You will need to log out of genhelm and sign back in for the changes to take effect.

Creating a New Website

Before you can maintain a website using GenHelm it is necessary to create a subdomain for the site using your administration software such as Cpanel. If you are just developing on your local machine, for example under Windows, this step is not necessary since new sites can be created on-the-fly.

Once the subdomain has been defined you can use GenHelm to set up all of the files needed for the site. This is done by executing the command "create site subdomain name" where subdomain name is the name of the subdomain you just created. In GenHelm we refer to this subdomain name as the "site directory" or site name. In most cases, the site name will correspond with the live site domain (although this is not a requirement). For example, if you are building a new site for the domain www.spicymeatballs.com, you would typically create the necessary folders by executing the command "create site spicymeatballs". This will create a series of directories and show a number of messages such as the following:

🛈7001 Processing command "create site spicymeatballs".
🛈0003 Directory websites/public_html/spicymeatballs/ created successfully
🛈0003 Directory websites/public_html/spicymeatballs/cache/ created successfully
🛈0003 Directory websites/public_html/spicymeatballs/docs/ created successfully
🛈0003 Directory websites/public_html/spicymeatballs/images/ created successfully
🛈0003 Directory websites/public_html/spicymeatballs/styles/ created successfully
🛈0003 Directory websites/public_html/spicymeatballs/support/ created successfully
🛈0003 Directory websites/private_data/spicymeatballs/ created successfully
🛈0003 Directory websites/private_data/spicymeatballs/classes/ created successfully
🛈0003 Directory websites/private_data/spicymeatballs/data/ created successfully
🛈0003 Directory websites/private_data/spicymeatballs/downloads/ created successfully
🛈0003 Directory websites/private_data/spicymeatballs/includes/ created successfully
🛈0003 Directory websites/private_data/spicymeatballs/locate/ created successfully
🛈0003 Directory websites/private_data/spicymeatballs/messages/ created successfully
🛈0003 Directory websites/private_data/spicymeatballs/pageinfo/ created successfully
🛈0003 Directory websites/private_data/spicymeatballs/specs/ created successfully
🛈0003 Directory websites/private_data/spicymeatballs/uploads/ created successfully
🛈0003 Directory websites/private_data/spicymeatballs/users/ created successfully
🛈0001 All folders were created for site directory spicymeatballs
🛈0004 Saved program websites/public_html/spicymeatballs/index.php successfully

Switching Between Websites

The logon command is often the first command you will use after signing into GenHelm. This is used to switch to the website that you want to work on. For our example site the command would be "logon spicymeatballs". After this command the screen will appear as follows:

GenHelm IDE after logon command

Assigning Site Settings

The first GenHelm model you should use when starting a new site is called site_settings. The model is invoked using the command "edit site_settings" (the edit command can be shortened to just the letter "e").

Most of the site settings are optional however you must specify a default layout to be used for your site. In fact, you must provide the names of two default layouts:

  1. One layout to be used on mobile devices (mainly smartphones and other very small devices).
  2. Another layout to be used for all other devices (tablets, laptops, desktop devices, etc).

We will learn about layouts in detail later, for now you can just enter the layout name "standard_layout" in the Default Layout Mobile field. You can enter =m in the Default Layout Desktop field to indicate that this uses the same layout as the default mobile layout.

After entering these layouts you can stow the site settings using the command "stow" or the shortcut <ctrl>s.

Normally, when a component is being stowed for the first time, it is necessary to supply the name that you want to give to the component. Since there is only one instance of site settings per website, the name is defaulted to the standard name by the system.

The edit Command

The edit command (usually abbreviated to e) is used to edit a new or existing component. There are several variations of this command.

As we will learn, component names do not have to be unique. For example, it is possible to have a page called "testimonials" and also have, say, a list called "testimonials". In such a case, if you enter the command "e testimonials" the system will present a list of components by this name and you can pick the one you want. Alternatively, you can use another form of the edit command which is "edit model-name component-name", for example "edit list testimonials".

Yet another option is to refer to the full name of the specification including its folder location. For example, "e list/testimonials.xml".

If you are not sure of the exact name you are looking for, you can use wildcard selection in the component name. For example, "e t*" will show all components with names beginning with the letter t.

The new Command

If you are not sure of the model that you want to use, you can enter the command "new". This will present you with a list of models from which to choose. The new command can also be passed the name of a model that you want to use. For example, "new anchor" will launch the anchor model.

Creating Your First Page

One of the common "catch all" models is called "tags". This model allows you to create any set of html tags. We will use this model to create a sample home page. To do so, we can enter the command "e tags". This will present an empty specification for the tags model. For our test page we will simply enter the contents "Hello World".

Sample tags model specification

Notice that the name of the current model is shown in the information area to the right of the command line. In this case, the tags model is indicated as a hyperlink. This tells you that model-specific help is available. Click on these model name links whenever you need help related to a specific model.

Every component of your website needs to have a description before it can be saved. The description field is shown just below the command field. Enter a suitable description for your page then stow this page under the name home by using the command "stow home".

At this point you should be able to open a new browser tab and see the initial page of your site. If you are running under a server based sandbox, the url you should open will be something like http://spicymeatballs.yourserverdomain.com (or https if you have installed an ssl certificate). If you are developing on a local machine the url will be http://localhost/spicymeatballs. These urls will launch the default php script which is index.php. If no page is indicated in the url, index.php will launch the default page which is generally the page named "home".

Getting Help

Help Index

GenHelm Architecture GenHelm Architecure.
Why GenHelm? Summary of the GenHelm methodology.
Getting Started Learn how to start a new website.
Naming Conventions Naming web pages and other items.
Common Web Page Fields Descriptions of fields that are common to all page models.
Layouts Defining codeframes and layouts.
Styles and Scripts Descriptions of fields that are common to all page models.
Meta Tags How to configure meta tags for your site and specific pages.
Dollar Functions General information about dollar functions.
Navigation Tips Navigation Tips and Techniques
Favourite Icons How to configure favorite icons for your site.
Blog Maintenance Blog and post administration.
Direct Command Help Help for the direct command field.
Programming with GenHelm Writing programs that interact with the GenHelm framework.