pageview

README

PageView

• PageView
  • Purpose
  • Installation
  • Usage
  • Libraries
  • Credits
  • Update
  • Licence

---

Purpose

Sometimes yoo don't want just standard web links in your web pages but a preview image showing the page you`re linking to. That is where this small package comes in. It generates – by way of calling the external wkhtmltoimage commandline utility – an image of the web page a given URL addresses. Those image files are stored locally and may be used as often as you want.

Installation

You can use Go to install this package for you:

go get github.com/mwat56/pageview

After that you can import it the usual Go way to use the library.

Usage

There are only two functions you have to worry about:

// SetImageDir sets the directory to use for storing the
// generated images, returning an error if `aDirectory` can't be used.
//
//	`aDirectory` The directory to store the generated images.
func SetImageDir(aDirectory string) error { … }

This function must be called before any other one to make sure the generated images end up where you want them to be. The default is the current directory from where the program was run.

To actually create an image you'd call:

// CreateImage generates an image of `aURL` and stores it in
// `ImageDir()`, returning the file name of the saved image
// or an error in case of problems.
//
//	`aURL` The address of the web page to process.
func CreateImage(aURL string) (string, error) { … }

The returned string is the name of the generated image file. If you combine it with the directory returned by ImageDir() you get the complete path/filename to locally access the image.

Generating a preview image usually takes between one and five seconds, depending on the actual web-page in question, however, it can take considerably longer. To avoid hanging the program the wkhtmltoimage utility is called with an one minute timeout.

And, finally, not all web-pages can be rendered properly and turned into an image. In such case wkhtmltoimage just crashes and CreateImage() doesn't return a filename but an error.

There are a few more functions which you will barely need; for details refer to the source code documentation.

Libraries

The great commandline utility

• wkhtmltoimage

is required for this package to work.

Under Linux this utility is usually part of your distribution. If not, you can download wkhtmltoimage from the web and install it. Sometimes the package from the download page above is more recent than the version in your Linux distribution. If in doubt, I'd suggest to test both versions to determine which one works best for you.

Credits

Part of the code (i.e. the file wkhtmltoimage.go) started as a modified version of go-wkhtmltoimage, Copyright (c) 2015 ninetwentyfour

Update

Over the last few years in most cases wkhtmltoimage worked just fine. However, once in a while wkhtmltoimage produced a segmentation fault (core dumped) – reproducible. For a while I thought I could live with it, but over time it happened more often (i.e. with additional URLs). Fiddling around with various commandline options provided no improvement.

In the end I started to look around, searching for alternative approaches – short of writing my own URL retrieval and rendering system. That's when I found ChromeDP and hence the screenshot package came into existence which is supposed to be a replacement for this package.

Licence

    Copyright © 2019, 2022 M.Watermann, 10247 Berlin, Germany
                    All rights reserved
                EMail : <support@mwat.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program. If not, see the GNU General Public License for details.

---

Documentation

Overview

Package pageview implements a web page link preview.

Copyright © 2019, 2022 M.Watermann, 10247 Berlin, Germany
                All rights reserved
            EMail : <support@mwat.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program. If not, see the [GNU General Public License](http://www.gnu.org/licenses/gpl.html) for details.

Copyright © 2019, 2022 M.Watermann, 10247 Berlin, Germany
               All rights reserved
           EMail : <support@mwat.de>

Copyright © 2019, 2022 M.Watermann, 10247 Berlin, Germany
               All rights reserved
           EMail : <support@mwat.de>

Index

• func CreateImage(aURL string) (string, error)
• func ImageDir() string
• func ImageFileType() string
• func ImageHeight() int
• func ImageQuality() int
• func ImageWidth() int
• func JavaScript() bool
• func MaxAge() time.Duration
• func PathFile(aURL string) string
• func SetImageDir(aDirectory string) error
• func SetImageHeight(aHeight int)
• func SetImageQuality(aQuality int)
• func SetImageType(aType string)
• func SetImageWidth(aWidth int)
• func SetJavaScript(doAllow bool)
• func SetMaxAge(aLengthInSeconds time.Duration)
• func SetUserAgent(aAgent string)
• func UserAgent() string

Functions

func CreateImage

func CreateImage(aURL string) (string, error)

CreateImage generates an image of `aURL` and stores it in `ImageDirectory()`, returning the file name of the saved image or an error in case of problems.

`aURL` The address of the web page to process.

func ImageDir

func ImageDir() string

ImageDir returns the directory used to store the generated images.

func ImageFileType

func ImageFileType() string

ImageFileType returns the type of the image files to generate.

func ImageHeight

func ImageHeight() int

ImageHeight is the height in pixels of the imaginary screen used to render. The default value is `768`.

The value `0` (zero) renders the entire page top to bottom, calculating the actual height from the page content.

func ImageQuality

func ImageQuality() int

ImageQuality returns the desired image quality.

func ImageWidth

func ImageWidth() int

ImageWidth is the width in pixels of the imaginary screen used to render. The default value is `1024`. Note that this is used only as a guide line.

func JavaScript

func JavaScript() bool

JavaScript returns whether to allow JavaScript during page retrieval; defaults to `false` for safety and speed reasons.

func MaxAge

func MaxAge() time.Duration

MaxAge returns the maximum age of cached page images.

func PathFile

func PathFile(aURL string) string

PathFile returns the complete local path/file of `aURL`.

NOTE: This function does not check whether the file for `aURL` actually exists in the local filesystem.

`aURL` The address of the web page to process.

func SetImageDir

func SetImageDir(aDirectory string) error

SetImageDir sets the directory to use for storing the generated images, returning an error if `aDirectory` can't be used.

`aDirectory` The directory to store the generated images.

func SetImageHeight

func SetImageHeight(aHeight int)

SetImageHeight sets the height of the images to generate. The default value is `768`.

`aHeight` The new height of the images to generate.

func SetImageQuality

func SetImageQuality(aQuality int)

SetImageQuality changes the quality of the image to be generated. Values supported between `1` and `100`; default is `100`.

`aQuality` the new desired image quality.

func SetImageType

func SetImageType(aType string)

SetImageType changes the type of the generated images. The default type is `png`, the other options are `gif`, `jpg` and `svg`. Passing an invalid value in `aType` will result in `png` being selected.

NOTE: Depending on how your `wkhtmltoimage` binary was compiled not all formats might be supported.

`aType` is the new desired type of the images to generate.

func SetImageWidth

func SetImageWidth(aWidth int)

SetImageWidth sets the width of the images to generate. The default value is `1024`.

`aWidth` The new width of the images to generate.

func SetJavaScript

func SetJavaScript(doAllow bool)

SetJavaScript determines whether to allow JavaScript during page retrieval or not.

`doAllow` If `false` (i.e. the default) no JavaScript will be available

during page retrieval, otherwise (i.e. `true`) it will be activated.

func SetMaxAge

func SetMaxAge(aLengthInSeconds time.Duration)

SetMaxAge sets the maximum age of cached page images before they might get updated.

Usually you want this property at its default value (`0`, zero) which disables an age check because you want an image of the page at the time you linked to it.

`aLengthInSeconds` is the age a page image can have before

requesting it again.

func SetUserAgent

func SetUserAgent(aAgent string)

SetUserAgent changes the current `User Agent` setting to `aAgent`.

Note: This only affects the HTTP header send to the remote host. Unfortunately, there is no way to change the `navigator.userAgent` setting by a commandline argument. So sites requesting that value will still see the hardcoded `Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/534.34 (KHTML, like Gecko) wkhtmltoimage Safari/534.34`.

`aAgent` The new `User Agent` setting.

func UserAgent

func UserAgent() string

UserAgent returns the current `User Agent` setting.