README
¶
PageView
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
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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreateImage ¶
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 ¶ added in v0.4.6
func ImageDir() string
ImageDir returns the directory used to store the generated images.
func ImageFileType ¶ added in v0.1.2
func ImageFileType() string
ImageFileType returns the type of the image files to generate.
func ImageHeight ¶ added in v0.1.2
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 ¶ added in v0.1.2
func ImageQuality() int
ImageQuality returns the desired image quality.
func ImageWidth ¶ added in v0.1.2
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 ¶ added in v0.4.0
func JavaScript() bool
JavaScript returns whether to allow JavaScript during page retrieval; defaults to `false` for safety and speed reasons.
func PathFile ¶
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 ¶ added in v0.4.6
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 ¶ added in v0.1.2
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 ¶ added in v0.1.2
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 ¶ added in v0.4.6
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 ¶ added in v0.1.2
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 ¶ added in v0.4.0
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 ¶
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 ¶ added in v0.3.0
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.
Types ¶
This section is empty.
Source Files
Directories