# folderHorizon documentation

### Configuration files

- archive.json (archives configuration)
- folderHorizon.json (program configuration)

### Special features

- Add links to main menu
- Add global footer to pages
- Add contextual content to pages
- Add metadata to header
- Projects text custom placement
- File captions template (experimental)

### Development

- Assets
- Theme
- Templates

### Program

- Architecture
- License

### Configuration files

folderHorizon creates the program and the archives configuration files with default values ​​that can be modified. Configuration .json files contain "Key": "Value" and the value is editable using a simple text/code program. Just be careful not to break the double quotes and commas.

#### top

### archive.json (archives configuration)

The configuration file created in each archive folder contains the archive settings that you can customize.

    Example | with notes
    {
      "ArchiveName": "Your Archive Name",
      "ArchiveDescription": "The description of the archive",
      "ArchiveKeywords": "A list of keywords about its content",
      "ArchiveAuthor": "Maybe your name?",
    	| All self-explaining HTML page metadata.
      "ImageResizeHeight": "1200",
    	| If needed, gallery images are resized by pixel height.
    	| To avoid the resize, just set a huge number.
      "ThumbnailHeight": "400",
    	| Thumbnail images resize, 300 to 500 should be ok.
      "JPGQuality": "2",
    	| Quality of resized Jpeg images, high to low: 2 to 5.
      "ConvertPNG": true,
    	| Convert Png to Jpeg. Set false to preserve transparency.
      "MP4Quality": "19",
    	| Mp4 video quality, high to low: 18 to 24.
      "MP4Bitrate": "192",
    	| Mp4 video/audio quality, high to low: 320|256|192|128.
      "MP3Bitrate": "192",
    	| Mp3 audio quality, high to low: 320|256|192|128.
      "AudioWaveFormColor": "#333333",
    	| The color of the audio waveform generated image.
    	| See class '.audio' in 'main.css' file.
    |
    | The next three configuration values can be changed in "Live options" terminal.
    | Do not change them in archive.json.
      "AssetDirectory": "asset-default",
    	| The 'asset' directory name.
      "AssetLayoutFile": "default.css",
    	| The 'layout' .css file.
      "EnableEmptyCaptions": true,
    	| Empty caption files option.
    |
      "EnableEmbedSourcePath": false
    	| Set true to write the archive/filepaths in the HTML figures dataset.
    	| It allows to copy the filepath to clipboard by right-clicking on the file figure
    	| (it works on local and https).
    }

#### top

### folderHorizon.json (program configuration)

The program configuration file is created in the program directory at first run.
The program also create the directory for your works defined in "WorksPath".
If you want to move/rename the 'folderHorizonWorks' folder, you have to modify also the "WorksPath" value.
Of course, you can use an external Disk Drive.
Important. Do not use whitespaces in "WorksPath" and do not rename the internal folders Archives and Releases.

    Example
    {
    	"WorksPath": "/Users/*yourname*/folderHorizonWorks",
    	"ServicePort": "8080"
    }

The "ServicePort" 8080 should be ok by default. In case of error, you can set 8000/9000/9090 etc.
The service allows to write the HTML/Text of the pages in browser and save it in files named [text].html
The service also monitors the archive changes allowing to update and view in real time.

#### top

## Special features

### Add links to main menu

You can add absolute or relative link/s to the top menu navigator.
Create a file named [menu].html, edit it as the example below and set it in the archive home folder.

<li><a href="https://example.com" target="_blank">absolute url</a></li> <li><a href="(@_NAV_REF_@)the_external_archive_directory/index.html" target="_blank">relative directory</a></li> <!-- etc... -->

Relative links require the (@_NAV_REF_@) reference pattern.

#### top

### Add global footer to pages

You can add content to global footer element.
Create a file named [footer].html, edit the content and set it in the archive home folder.
The style can be defined in main.css file, footer tag (unordered list ready).

#### top

### Add contextual content to pages

You can add content on each page.
Create a file named [content].html, edit the HTML and set it in the archive home, section or project folder.
The style can be defined in main.css file, section.add-content class.

#### top

### Add metadata to header

You can add metadata to the header element (perhaps for SEO?).
Create a file named [header].html, edit the content and set it in the archive home folder.
Example:

<link rel="canonical" href="https://yourdomain.org(@_CONTEXT_REF_@)index.html"> <meta property="og:site_name" content="YOUR WEBSITE NAME"> <meta property="og:description" content="YOUR DESCRIPTION"> <meta property="og:image" content="https://yourdomain.org/archive/homepage.jpg"> <!-- etc... -->

The optional pattern (@_CONTEXT_REF_@) is replaced by the program with contextual relative paths (slashes included).

#### top

### Projects text custom placement

By default, the template project.tpl sets the main text position after the first available media file (image/gallery, video, audio).

    	<!-- ******* Media: ******* -->
    	{@_TPL_GALLERY_WRAPPER_@}
    	{@_TPL_VIDEO_WRAPPER_@}
    	{@_TPL_AUDIO_WRAPPER_@}
    	<!-- ******* Order: ******* -->
    	<!-- ${gallery,video,audio} -->
    	<!-- ********************** -->
    	{@_TPL_TEXT_@}

It's possible to change the order of the media wrappers and the comment below ${gallery,video,audio} must respect the same order.
Leaving empty brackets ${} sets the main text at bottom page by replacing {@_TPL_TEXT_@}.

#### top

### File captions template (experimental)

The empty caption files option supports a pre-formatted template.

1. Create a plain/text file named [captions-template].txt in your archive folder.
2. Edit the file with your keys, example:
   Title:
   ID:
   Description:
   Any:
3. Save it and "update changes" if required.
4. Edit your caption files, "update changes" and the text caption will appear.
5. You can enable/disable the "template caption files" option typing c + Enter.

Important
Disabling the "template captions files" option will clear only the unfilled captions.
Test this feature on a small archive with few files to understand how it works.

On Search
It is suggeted to filter the the keys: Title, ID, Description, Any (as example).
The file resources\build\asset-default\theme\js\search.js
has an empty array that you can edit for that:
searchSkipWords = [], // List of words to skip in search (case insensitive).
Example: searchSkipWords = ['Title', 'ID', 'Description', 'Any'],
If you are working on different archives with different templates, consider creating an asset for each one.

#### top

## Development

### Asset

In addiction to archive directory resources/build/ contains the 'asset' folders.
It is recommended not to work directly in asset-default directory. Make a copy of asset-default in the same folder and name it whatever you like (lowercase, no whitespaces).
On teminal "Live options", change the asset directory and select your new one.
Different archives can have different assets, always backup your asset folders!

The asset-default directory also contains
- PhotoSwipe JS that is an excellent image gallery (see configuration in gallery.js and gallery.css files).
- Fuse JS used for the static text search in pages (see configuration in search.js file).

Important. Do not delete or rename the asset-default directory: it's required for new archive creation.

#### top

### Asset theme

The asset contains the theme/css/ with all CSS files.

- css/layout/ directory contains three different layout examples.
  The word 'figure' means any supported image/video/audio file.
  You can create your custom layout .css files and set them by teminal "Live options" menu.
- css/main.css contains the root variables (font-size, colors) and all contextual instructions.
- css/gallery.css contains the projects image-gallery style.

Layout scheme

    ==================================================================
    rows/columns

      * common header: [nav title]           [nav menu sections]
      - page home:     [aside empty]         [main figure and article]
      - pages archive: [aside menu projects] [main page content]
      * common footer: [aside empty]         [optional footer content]
    ==================================================================

- layout/default.css
  Homepage and archives pages have the same structure.
- layout/home-large-figure.css
  Larger homepage figure.
- layout/home-full-figure.css
  Full homepage figure "hero style".

Layout syntax note. The *-home-* and *-archive-* patterns allow to treat homepage and archive pages with different values.

Important. Do not delete or rename the layout/default.css file in asset-default directory.

Thanks to Domenico Antonio Mancini for his precious ideas and suggestions.

#### top

### Asset templates

The directory templates/ contains the *.tpl files used to build the HTML the index.html pages.
Templates allow to completely re-design the HTML frontend.
folderHorizon reads the template files replacing three types of patterns:

    1. {@_TPL_* Nested templates
    2. [@_*     Data contained in archive.json configuration file
    3. (@_*     Archive content and HTML required data

1. Nested templates scheme

    global_header.tpl =>
    {@_TPL_TOPNAV_ITEMS_@} loads array:
    	global_nav_item.tpl + (see also chapter Add links to main menu)
    	global_nav_search.tpl

    	page home.tpl =>
    	{@_TPL_HOME_FILE_@} loads homepage figure file:
    		home_file_image.tpl or
    		home_file_video.tpl or
    		home_file_audio.tpl
    	{@_TPL_TEXT_@} [1] loads HTML/Text and wraps the editor:
    		global_text.tpl =>
    		{@_TPL_TEXTEDITOR_@} loads:
    			global_texteditor.tpl
    	(@_ADD_CONTENT_@) add custom HTML content (see chapter Add page content)

    	page search.tpl [3]

    	page section.tpl =>
    	{@_TPL_SIDENAV_@} loads wrapper:
    		sidenav_common.tpl =>
    		{@_TPL_SIDENAV_ITEMS_@} loads array:
    			global_nav_item.tpl
    	{@_TPL_SECTION_ITEMS_@} loads array:
    		section_item.tpl
    	{@_TPL_TEXT_@} ...same as above
    	(@_ADD_CONTENT_@) ...same as above

    	page project.tpl =>
    	{@_TPL_SIDENAV_@} ...same as above

    	{@_TPL_GALLERY_WRAPPER_@} loads wrapper:
    		project_gallery_oneimage.tpl IF only one image is set
    	ELSE
    		project_gallery_wrapper.tpl =>
    		{@_TPL_GALLERY_ITEMS_@} loads array:
    			project_gallery_item.tpl
    	AND in both cases
    		{@_TPL_TEXT_@} [2] optional

    	{@_TPL_VIDEO_WRAPPER_@} loads wrapper:
    		project_video_wrapper.tpl =>
    		{@_TPL_VIDEO_ITEMS_@} loads array:
    			project_video_item.tpl
    		{@_TPL_TEXT_@} [2] optional

    	{@_TPL_AUDIO_WRAPPER_@} loads wrapper:
    		project_audio_wrapper.tpl =>
    		{@_TPL_AUDIO_ITEMS_@} loads array:
    			project_audio_item.tpl
    		{@_TPL_TEXT_@} [2] optional

    	{@_TPL_TEXT_@} [2] optional

    	(@_ADD_CONTENT_@) ...same as above

    	{@_TPL_DOCUMENT_WRAPPER_@} loads wrapper:
    		project_document_wrapper.tpl =>
    		{@_TPL_DOCUMENT_ITEMS_@} loads array:
    			project_document_item.tpl
    			(@_FILE_TYPE_@) for css class="icon-*type*"

    	global_service.tpl [4]

    global_footer.tpl
    (@_ADD_FOOTER_@) see chapter Add global footer

    Notes

    [1] The template 'global_texteditor.tpl' (HTML/Text editor) is not loaded in release.
    [2] The HTML/Text in project pages is placed after the first available media item.
        See chapter Set projects main text position
    [3] The 'search' page does not load 'global_service.tpl'.
    [4] The template 'global_service.tpl' (editor & status service) is not loaded in release.

2. Data contained in 'archive.json' configuration file (only in global_header.tpl)

    [@_ARCHIVE_NAME_@]        "ArchiveName" value (the archive name as title)
    [@_ARCHIVE_DESCRIPTION_@] "ArchiveDescription" value
    [@_ARCHIVE_KEYWORDS_@]    "ArchiveKeywords" value
    [@_ARCHIVE_AUTHOR_@]      "ArchiveAuthor" value

3. Archive content and HTML required data

    Content

    (@_PAGE_TITLE_@) The title of page
    (@_PAGE_TEXT_@) The [text].html files content

    (@_FILE_TITLE_@) and (@_FILE_DESCRIPTION_@) File title and description from *.txt caption files
    	(@_FILE_CAPTION_@) The sum of the two above

    (@_FILE_GALLERY_REF_@) Full size image source file reference
    	(@_FILE_GALLERY_WIDTH_@) and (@_FILE_GALLERY_HEIGHT_@) Full size image required size
    (@_FILE_THUMBNAIL_REF_@) Thumbnail image source file reference
    (@_IMG_TITLE_@) img tag title
    (@_FILE_REF_@) Video, audio and document source file reference
    (@_FILE_POSTER_REF_@) Video 'poster/preview' image source file reference (generated or custom)
    (@_FILE_WAVEFORM_REF_@) Audio waveform image source file reference (generated)
    (@_FILE_NAME_@) Document file name
    (@_FILE_TARGET_@) Document download or new tab for .pdf files

    (@_PROJECT_REF_@) Link to project in 'sections' pages
    	(@_PROJECT_NAME_@) Text of link
    	(@_PROJECT_IMAGE_REF_@) Image source file reference of project

    Navigators

    (@_NAV_REF_@) Link to relative index.html page
    	(@_NAV_NAME_@) Page name
    	(@_NAV_SELECTION_@) Current/selected page (css)

    Paths

    (@_HOME_REF_@)    Homepage link/reference
    (@_BACK_REF_@)    Parent references: ../../ etc.
    (@_ASSET_DIR_@)   The asset directory name [1]
    (@_LAYOUT_DIRFILE_@) The css layout file link in global_header.tpl [1]

    [1] Layout file can be changed by terminal "Live options" menu.
        While working, the path is '../css/layout/*layout-file*.css'.
        On release is directly saved as '../css/layout.css'.

    Var
    (@_ADD_META_@) Adds custom metatags in global_header.tpl (see chapter Add metadata to header)
    (@_WRAPPER_CONTEXT_CLASS_@) Adds the page context css class (.home .archive) in global_header.tpl
    (@_PAGE_TEXT_FILE_@) JS editor. The path to [text].html file in source archive
    (@_PAGE_INDEX_FILE_@) JS status. The path to index.html file in build directory
    (@_SERVICE_PORT_@) JS editor and status. The local service port
    (@_FILE_ARCHIVE_SOURCE_@) On "EnableEmbedSourcePath": true, it writes the source archive filepath in the projects figure tag dataset

#### top

## Program

### Architecture

folderHorizon is developed with Golang v1.20 (standard library).
It uses:

- FFmpeg to convert/resize media files. The binary static (version 7.0.1) is downloaded from...
  - Win: https://gyan.dev/ffmpeg/builds
  - Mac: https://evermeet.cx/ffmpeg
  - Linux: https://johnvansickle.com/ffmpeg
  - We sincerely wish these three urls a long life.
- Jodit JS to edit the HTML/Text of pages (see configuration in service.js file).

#### top

### License

The folderHorizon directories theme/ and templates/ are public domain (PD).

Generally. The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. in no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

(c) LL 2024