*Draft pages and Downloads in Knowledge Base

Writing and using plugins for Version 5 and above.
User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 06 Nov 2018 16:29

Is there any way to create a draft page in the knowledge base?

I want to draft a page describing a plugin and a set of ancillary downloads (queries, fact set, possibly .chm file) , and test everything before I release it. (The plugin will have an option to download all the other items automatically).

However I can't see any way to publish privately and test and then release when I'm happy. Am I missing something obvious?

The alternative is to do a forum post, and code the plugin to refer to links in the forum post, and later modify the plugin to refer to the wiki.

User avatar
tatewise
Megastar
Posts: 14611
Joined: 25 May 2010 11:00
Family Historian: V6.2
Location: Torbay, Devon, UK
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby tatewise » 06 Nov 2018 19:44

I suspect you really mean a 'private' page, rather than a 'draft' page.

I don't recall such a feature, but here are some ideas.
  1. If you plan to show the KB pages directly in the Plugin then use the 'Knowledge Base > Plugin Help and Advice for published Plugins' section, because they have no distracting Menu sidebar on the left.
    Add a BOLD NOTE on the first page informing users the page is under development.
  2. Otherwise, use the 'Knowledge Base > Work In Progress Plugins under development' section.
  3. I am not sure this will work, but give it a try. Create a page in the usual way by adding a hyperlink on a parent page. Bookmark the newly created sub-page URL. Then delete the parent page hyperlink. Use the bookmark to open and edit the new page until ready to pubish.
Mike Tate ~ researching the Tate and Scott family history.

User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 06 Nov 2018 20:13

No intention to show the KB files directly in the plugin -- I've never been convinced it's the right way to deliver help -- although I still need to decide how best to do it, I'm most used to delivering .chm files (which I would load into the plugin data folder and update it and when the plugin was updated).

I really want to create a page which eventually be public with the final links to downloads in it, but not make the visibly available until everything is tested.

I'll try your third option tomorrow.

User avatar
tatewise
Megastar
Posts: 14611
Joined: 25 May 2010 11:00
Family Historian: V6.2
Location: Torbay, Devon, UK
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby tatewise » 06 Nov 2018 20:53

I assume you eventually plan to publish the Plugin in the Plugin Store.
The snag I always have is that only a single Plugin Script .fh_lua file can be downloaded from the Plugin Store.
So any other required files (.chm?) must be embedded within the Plugin Script file somehow, and saved when the Plugin is run.
That means that such embedded files can only be textual, so things like screenshots are impossible.

It also means that to update associated Help & Advice, .chm, etc, using that technique would require an update to the Plugin.
Whereas, by holding the Help & Advice in the Knowledge Base it can be updated at any time without changing the Plugin.

It sounds like you are planning to save such supplemental files in the Knowledge Base and get the Plugin to download them when it is run. I have used that technique, but only for files that never change, so only need downloading once, and their existence in the filing system inhibits subsequent downloads. Also, that technique should work if the Plugin keeps track of those supplemental file versions in its sticky Plugin Data file to avoid downloading and installing them every time it is run, which may have a time penalty. But how does it discover the version of a file without downloading it? That will require a separate tiny version control file that can be downloaded quickly and compared against the Plugin Data details. I may be barking up the wrong tree, and if so, ignore the above.
Mike Tate ~ researching the Tate and Scott family history.

User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 07 Nov 2018 08:32

Not sure why I'd expect ancillary files to change once the plugin is released until a new version is released -- it's not as if Calico Pie (for example) continuously update their Help file during the life time of a version, and a plugin is most often considerably simpler.

Logic would be something like this every time plugin runs:

Check for prerequisites inside FH (existence of a Fact type, for example)

Compare version of plugin with small version file in data folder.

If prerequisites met and version hasn't changed, do nothing (this will be the most common case).

If prerequisites not met (typically first time running the plugin) download mandatory ancillary files (e.g. chm file) and offer to download and install FH queries, reports, fact type, icons or whatever or tell the user how they can download and install those files themselves if they prefer more control over what they're downloading.

If prerequisites met but version has changed, download latest versions of mandatory ancillary files (e.g. chm file) and offer to download and install any updated versions of queries, reports, fact type, icons or whatever or tell the user how they can download and install those files themselves if they prefer more control over what they're downloading. Update version file.

Yes, there's a risk that the user won't download and install the queries etc. but for this particular plugin those are optional anyway, as you can't use queries from within a plugin anyway.

User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 07 Nov 2018 09:39

Mike,

The approach you suggested has worked (create a page, bookmark it, unlink it until it's ready).

Helen

User avatar
tatewise
Megastar
Posts: 14611
Joined: 25 May 2010 11:00
Family Historian: V6.2
Location: Torbay, Devon, UK
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby tatewise » 07 Nov 2018 10:52

That is a useful trick to keep in mind.

I presume you intend to download ancillary files from the Knowledge Base so below is my Lua function to download icon images.
(Maybe this discussion should continue in the Plugin Discussions Forum?)

The icon image .jpg files exist in https://www.fhug.org.uk/wiki/doku.php?id=plugins:help:improve_htm.
They are created by editing a Knowledge Base page in that namespace and using the Media Manager.
e.g. namespace page: Knowledge Base > Improve Website or CD DVD HTML Plugin
Those icon files don't have a user download, but that is possible as in many Knowledge Base > Downloads and Links.

This function uses functions general.FlgFileExists(...) and CopyFile(...) that I can supply if required.

Code: Select all

require "iupluaole"                                       -- To access OLE subsystem
require "luacom"                                       -- To access COM subsystem

local StrIconFile = "improve_etc_icon.jpg"                        -- Default icon filename

-- Load icon files from FHUG into ProgramData --   
function DownloadIcons()
   local strIcon = StrIconFile                                 -- Icon path in FHUG Plugins and ProgramData folder
   local strFhug = "http://www.fhug.org.uk/pushfile.php?filename="..strIcon.."&name=improve_etc_icon&ns=/plugins/help/improve_html/"
   local strData = iup_gui.MachinePath.."\\"..strIcon
   local http = luacom.CreateObject("winhttp.winhttprequest.5.1")
   for intType, strType in ipairs ({"_etc_";"_pdf_";"_doc_";"_txt_";}) do
      local strSource = strFhug:gsub("_etc_",strType)               -- Check each type of icon
      local strTarget = strData:gsub("_etc_",strType)
      if not general.FlgFileExists(strTarget) then                  -- Get missing icon file from FHUG
         http:Open("GET",strSource,false)
         http:Send()
         http:WaitForResponse(30)
         if http.StatusText == "OK" then
            local strFilename = string.match(http:GetResponseHeader('Content-Disposition'),'="(.*)"')
            if strTarget:match(strFilename) then
               CopyFile(http.ResponseBody,strTarget)            -- Copy icon file to ProgramData\Plugin Data folder
            else
               error("\n\n Download icon JPG filename "..strFilename.." does not match. \n\n "..strSource.." \n\n "..strTarget.." \n " )
            end
         else
            error("\n\n Could not download icon JPG file from FHUG. \n\n "..strSource.." \n\n "..strTarget.." \n " )
         end
      end
   end
end -- function DownloadIcons
Mike Tate ~ researching the Tate and Scott family history.

User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 07 Nov 2018 11:26

Thanks, Mike. I've started coding it myself -- I think it's a simpler use case -- it's tested but I need to add in some error handling for when the download fails or the destination file can't be created because it already exists. I'll use the Penlight Path library (as it's loaded anyway) for testing if the destination file exists so that I delete it if necessary before replacing it (ditto copying files if I need to) -- it may also make sense to use Penlight to write the file as well, as it is text, which will simplify things further. I'll update the code here when I've added in the error checking.

Code: Select all

 
 
     require("lfs") -- file system access
     require ("luacom") --Microsoft's Component Object Model
     
     gcstrDownLoadLocation = "xxxxxxx" -- file download url goes here
     gcstrPluginDir = fhGetPluginDataFileName("LOCAL_MACHINE",true) --this is the destination directory
     
        local http = luacom.CreateObject("winhttp.winhttprequest.5.1")

        http:Open("GET",gcstrDownLoadLocation ,false)
        http:Send()
        local body = http.Responsetext

        -- save the content to a file
        local f = assert(io.open(gcstrPluginDir.."\\MyTaskSet.fhf", "wb")) -- open in "binary" mode
        f:write(body)
        f:close()
       
 

User avatar
tatewise
Megastar
Posts: 14611
Joined: 25 May 2010 11:00
Family Historian: V6.2
Location: Torbay, Devon, UK
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby tatewise » 07 Nov 2018 14:37

I found that the best download URL uses the pushfile mechanism and is of the form:
"http://www.fhug.org.uk/pushfile.php?filename={FHUGfilename}&name={Windowsfilename}&ns={Namespace}"
where
{FHUGfilename} is filename in Knowledge Base that is all lower case and underscores
{Windowsfilename} is filename in Windows that can be mixed case and have spaces
{Namespace} is the namespace in Knowledge Base where file exists, e.g. /plugins/help/improve_html/

I suggest that after http:Send() you include:
http:WaitForResponse(30) timeout for the response in case Internet is slow.
if http.StatusText == "OK" then check status in case of timeout or FHUG is offline, etc.

There are various response components:
http:GetResponseHeader(...)
http.ResponseBody
http.ResponseText

If you are expecting to download several files then the process needs to be a reusable Lua function.

BTW: Any text file that is always updated with each new Plugin version, and never by a user, can be embedded in the Plugin script.
StrMasterFile = [=[
{line by line text contents of file goes here}
]=]
then just save that StrMasterFile text string to the desired filename.
Mike Tate ~ researching the Tate and Scott family history.

User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 11 Nov 2018 18:29

Interesting -- why do you find the pushfile mechanism preferable to (for example)

"https://www.fhug.org.uk/wiki/lib/exe/fetch.php?media=how_to:Namespace:filename"

User avatar
tatewise
Megastar
Posts: 14611
Joined: 25 May 2010 11:00
Family Historian: V6.2
Location: Torbay, Devon, UK
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby tatewise » 11 Nov 2018 20:14

I believe the pushfile.php mechanism is the one used by default in the latest Knowledge Base > Downloads and Links for example when Knowledge Base > Add a Downloadable File is used. So if users have the option to download the same files, then that is the mechanism that will be used.

Also it offers the ability to rename the file to mixed case with spaces that is more attractive for Query, Fact Set, and other customising filenames than the purely lower case with underscores required by Knowledge Base filenames.
Mike Tate ~ researching the Tate and Scott family history.

User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 12 Nov 2018 08:01

Odd -- different pages seem to have different urls for downloads. The one I've created (for example) has urls in the form of:

Code: Select all

https://www.fhug.org.uk/wiki/lib/exe/fetch.php?media=how_to:research_task_manager:research_task_manager.fhf

User avatar
Jane
Site Admin
Posts: 7306
Joined: 01 Nov 2002 15:00
Family Historian: V6.2
Location: Somerset, England
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby Jane » 12 Nov 2018 08:53

pushfile tends to get used where links were originally on the forerunner to the Wiki. From memory both Fetch and pushfile, set the http headers to prevent the problem with "helpful" web browsers displaying the content instead of downloading it, which happened a lot with query files.
Jane
My Family History : My Photography "Knowledge is knowing that a tomato is a fruit. Wisdom is not putting it in a fruit salad."

User avatar
tatewise
Megastar
Posts: 14611
Joined: 25 May 2010 11:00
Family Historian: V6.2
Location: Torbay, Devon, UK
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby tatewise » 12 Nov 2018 10:39

As a matter of interest Helen, how did you create that fetch.php URL?

I have downloaded that research_task_manager.fhf and it installs a Fact Set named literally research_task_manager.
Whereas it would be more natural to have a name such as Research Task Manager.

The pushfile.php alternative allows that renaming to be defined according to Knowledge Base > Pushfile Plugin.
http://www.fhug.org.uk/pushfile.php?filename=research_task_manager.fhf&name=Research%20Task%20Manager&ns=/how_to/research_task_manager/
Although in some scenarios it may be necessary to gsub each %20 with a space character.
Mike Tate ~ researching the Tate and Scott family history.

User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 12 Nov 2018 11:41

Mike,

I created a page as we'd previously discussed (and marked it Fix Me just in case anyone stumbled across it). I then created a Downloads section (as it made sense within the context of the page) and added a media file using the Media Manager.

I understand the pushfile alternative, but if the standard uploading facility doesn't work that way? I can amend my plugin, but people should have the option to download directly if they care about knowing what they're getting (plus the optional queries etc. that I'm providing can only be downloaded).

User avatar
tatewise
Megastar
Posts: 14611
Joined: 25 May 2010 11:00
Family Historian: V6.2
Location: Torbay, Devon, UK
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby tatewise » 12 Nov 2018 12:13

I have had a peek at your 'hidden' page and think I understand what is happening.

If you use the default Media Manager mechanism to Insert a media file, it simply uses the standard format:
{{ :how_to:research_task_manager:research_task_manager.fhf | }}
That is the same regardless of whether the file type is an image or data.
But for image file types it invokes the display image details.php function to view the image.
Whereas for data file types it invokes the fetch.php function since no specific function is defined.
The users gets the Knowledge Base filename, which in this case is research_task_manager.fhf that I think is not ideal.

If you were to use the Knowledge Base > Add a Downloadable File process it would employ the pushfile.php function provided for the purpose, which allows more control over the downloaded filename as discussed.
See for example Knowledge Base > Fact Set ~ Travel and Knowledge Base > Fact Set ~ Contact Info.

The Knowledge Base downloads for the user and those performed by the Plugin should be designed to produce the same Windows filenames.
Mike Tate ~ researching the Tate and Scott family history.

User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 12 Nov 2018 12:20

Pardon my ignorance, but where do I specify what 'vocabulary' it sits within and how do I add it to "my" page? Dumping it in downloadable files without context doesn't make sense.

User avatar
tatewise
Megastar
Posts: 14611
Joined: 25 May 2010 11:00
Family Historian: V6.2
Location: Torbay, Devon, UK
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby tatewise » 12 Nov 2018 12:44

Not sure what you mean by 'vocabulary' but to add data media with pushfile you must manually edit the entry as explained in Knowledge Base > Pushfile Plugin using either the [[http: ... ]] or {{pushfile> ... }} form.

The folder it will download into is determined by the file type for all the FH file types such as .fhf when installed via FH.
The other file types such as .pdf or .chm either need advice given to user or only download them via your Plugin.
Mike Tate ~ researching the Tate and Scott family history.

User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 12 Nov 2018 13:09

Vocabulary? If you add media files from an 'ordinary' page, you get a vocabulary tree to choose from, e.g.

Code: Select all

[root]

    ancestralsources
    contributeyourknowledge
    fhugdownloads
    gedcomcensus
    glossary
    how_to
        about
        create_locations_database_details
        delete_data_for_living_people
        exchange_with_ftm
        importing
        make_family_tree
        my_plugin
        tabulatedmultilinetext
        v4
    info
    playground
    plugins
    research
    wiki


And the resultant 'code' when you edit the page looks like:

Code: Select all

 {{ :how_to:my_plugin:my_task_set.fhf | My Task Fact Set}}


I guess you're suggesting that I edit the link created via the 'standard' mechanism to the one in the pushfile mechanism -- although the documentation you link to doesn't explain how I include the 'vocabulary'?

User avatar
tatewise
Megastar
Posts: 14611
Joined: 25 May 2010 11:00
Family Historian: V6.2
Location: Torbay, Devon, UK
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby tatewise » 12 Nov 2018 15:24

OK, the 'vocabulary' you refer to is known as the namespace and is equivalent to folder/directory paths in PC.
If you check the wording in the Media Manager it refers to namespace in various places.

So your 'hidden' namespace is :how_to:research_task_manager or in some contexts /how_to/research_task_manager because they are actually Unix folders on the server.

The full URL for your page is https://www.fhug.org.uk/wiki/doku.php?id=how_to:research_task_manager where doku.php is the function that displays the page.

In cases where the doku wiki page has the same namespace as the download file/image, then the full namespace is not required as it defaults to the current namespace.

There is much advice in Knowledge Base > Contribute Your Knowledge and that refers to for example https://www.dokuwiki.org/namespaces that explains that topic in more detail with various shortcut options.

Moving on to file naming...
Your Research Task Manager page uses that mixed case naming style throughout, so it would be consistent if the Fact Set was also named Research Task Manager and NOT research_task_manager.
Likewise, your Queries are given mixed case names such as Pending Tasks but the downloaded Query has a different name of tasks-_pending. It would be more consistent & convenient for users if all the Queries started with the same word (as you have done with tasks-) but using mixed case and spaces to match your page descriptions, e.g. All Tasks, All Tasks Pending, All Tasks Active, All Tasks Active by Source, etc.
Mike Tate ~ researching the Tate and Scott family history.

User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 13 Nov 2018 10:26

Mike, thanks for the advice about file naming -- I knew there was a reason I wanted a page that wasn't easily accessible to develop my ideas on...

User avatar
tatewise
Megastar
Posts: 14611
Joined: 25 May 2010 11:00
Family Historian: V6.2
Location: Torbay, Devon, UK
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby tatewise » 13 Nov 2018 11:11

Jane & I introduced the Knowledge Base > Add a Downloadable File forms, which we thought would satisfy most users. As far as I am aware you are the first who needs to download files independently from the Knowledge Base > Downloads and Links section. It is not yet clear whether that would still be the best section for your user downloads that could be cross-referenced from your main pages; similar to the way my Knowledge Base > Create Work In Progress or Research To Do Lists cross-refers to Knowledge Base > Fact Set ~ To Do Lists.
Mike Tate ~ researching the Tate and Scott family history.

User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 13 Nov 2018 11:51

Mike,

As I'm producing a collection of components that are designed to be used together, I'm not sure that splitting them up within the Downloads section according to the type of Download makes sense -- if people come to them via my page, fine, but if they find a subset of the components in isolation? I'm not sure. What are they going to make of a Help file on its own -- even if the Download and Link categories catered for it?

User avatar
tatewise
Megastar
Posts: 14611
Joined: 25 May 2010 11:00
Family Historian: V6.2
Location: Torbay, Devon, UK
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby tatewise » 13 Nov 2018 12:20

Checkout my To Do Lists pages:
Mike Tate ~ researching the Tate and Scott family history.

User avatar
ColeValleyGirl
Megastar
Posts: 755
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Draft pages and Downloads in Knowledge Base

Postby ColeValleyGirl » 13 Nov 2018 12:46

Re your structure, if you go to Downloads and Links, and then Reports Types, you see two Fact Sets at the top of the list of Reports (one of which is your to-do list), which just seems... odd. It's probably a result of all the cross-linking -- but I'd rather keep things simple and in one place.

(However, which category would you put my Help file in? Bearing in mind that it's of no interest unless you've already decided to use the plugin...)


Return to “Plugin Discussions”

Who is online

Users browsing this forum: No registered users and 5 guests