Name: igemwiki-api
Owner: igemuoftATG
Description: NodeJS API and CLI for developing an iGEM wiki (downloading/uploading pages/stylesheets/scripts/templates/images)
Created: 2016-09-13 19:57:35.0
Updated: 2017-10-05 20:21:28.0
Pushed: 2017-10-30 23:22:07.0
Size: 3113
Language: JavaScript
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
NodeJS and CLI API for interacting with an igem wiki (downloading/uploading pages/stylesheets/scripts/templates/images, etc.)
install -g igemwiki-api
TL;DR: Install Node, see upload-conf
See Recipes.
Runs igemwiki.downloadALL({ dir })
behind the scenes.
e:
emwiki backup [OPTIONS] [ARGS]
ons:
, --year [NUMBER] Year to download pages from (Default is current year)
, --teamName STRING Team name
, --dir [DIR] Download directory (Default is ./backups)
, --help Display help and usage details
This is the simplest way to get going. By writing a small yaml file and installing this tool via npm or Docker, you can begin uploading your entire wiki in minutes.
This will read from a yaml file with pages
, templates
, stylesheets
,
scripts
being an array that each have objects including source
and dest
.
If the value does not contain :
then it will be evaluated as a glob pattern
(and dest
will be created just as it were in upload-glob
). Else, the format
is source:dest
. INDEX
is a special dest that will map to your team home
page. Explicit mappings with source:dest
where source
is the same as
something that was encountered with a glob pattern will take precedence. This
lets you glob the majority of files and be explicit to “fix the odd ones”.
An example igemwiki-conf.yaml
might look like:
lates:
- ./build-live/templates/*.html
esheets:
- ./build-live/css/*_css
pts:
- ./build-live/js/*_js
s:
- ./build-live/*.html
- ./build-live/index.html:INDEX
- ./build-live/HP-Silver.html:HP/Silver
- ./build-live/HP-Gold.html:HP/Gold
es:
- ./images/*.{png,jpg}
See igemwiki-conf.yml for Toronto's 2016 wiki.
First get a preview of the { type, source, dest }
options array:
wiki upload-conf -n Toronto --conf igemwiki-conf.yml -p
And then upload each file:
wiki upload-conf -n Toronto --conf igemwiki-conf.yml
e:
emwiki upload-conf [OPTIONS] [ARGS]
ons:
, --year [NUMBER] Year to download pages from (Default is current year)
, --team STRING Team name
, --force BOOL Force upload
, --conf PATH YAML configuration file
, --preview BOOL Preview source/dest pairs before uploading
, --help Display help and usage details
e:
emwiki upload [OPTIONS] [ARGS]
ons:
, --year [NUMBER] Year to download pages from (Default is current year)
, --teamName STRING Team name
, --source STRING Source file
, --dest STRING Destination
, --type STRING Type (page, template, stylesheet, script, or image)
, --force BOOL Force upload
, --help Display help and usage details
stylesheet
emwiki upload -n Toronto --type stylesheet --source ./test/files/test-stylesheet.css --dest test-stylesheet
ped[889ms] ./test/files/test-stylesheet.css -> http://2016.igem.org/Template:Toronto/css/test-stylesheet
script
emwiki upload -n Toronto --type script --source ./test/files/test-script.js --dest test-script -f
aded[1451ms] ./test/files/test-script.js -> http://2016.igem.org/Template:Toronto/js/test-script
template
emwiki upload -n Toronto --type template --source ./test/files/test-template.html --dest test-template
ped[476ms] ./test/files/test-template.html -> http://2016.igem.org/Template:Toronto/test-template
page
emwiki upload -n Toronto --type page --source ./test/files/test-upload.html --dest test-upload
aded[2092ms] ./test/files/test-upload.html -> http://2016.igem.org/Team:Toronto/test-upload
image (use filename extension in dest!)
emwiki upload -n Toronto --type image --source ./test/files/igem-logo.png --dest igem-logo.png
ped[1401ms] ./test/files/igem-logo.png -> http://2016.igem.org/wiki/images/4/4d/T--Toronto--2016_igem-logo.png
emwiki upload -n Toronto --type image --source ./test/files/igem-logo.png --dest igem-logo.png -f
aded[3382ms] ./test/files/igem-logo.png -> http://2016.igem.org/wiki/images/4/4d/T--Toronto--2016_igem-logo.png
Upload files matching a pattern with globby.
Dest will be produced by stripping the basename of paths with the appropiate extension for that type. Thus this method will fail if you wish to have control over special destinations for some files, in which case upload-conf is recommended.
For example, if ./css/*.css
produces [ './css/styles.css',
'./css/vendors.css' ]
the dests will be [ 'styles', 'vendors' ]
e:
emwiki upload-glob [OPTIONS] [ARGS]
ons:
, --year [NUMBER] Year to download pages from (Default is current year)
, --teamName STRING Team name
, --glob STRING Glob pattern for sources
, --type STRING Type (page, template, stylesheet, script, or image)
, --force BOOL Force upload
, --help Display help and usage details
When you require this module, it returns a function which takes one parameter, which is an object of options.
t igemwiki = require('igemwiki-api')({
year: 2016,
teamName: 'Toronto'
Note
const
does not mean “constant”. It can have its properties modified, but cannot be reassigned.
The year
can actually be omitted, and the current year (new Date().getFullYear()
) will be used instead.
t igemwiki = require('igemwiki-api')({ teamName: 'Toronto' })
The teamName
needs to be exactly as it is on your wiki page, so: http://2016.igem.org/Team:${teamName}
.
Once you require the module and call it with options, the rest of the API becomes available.
Logging in is required for most actions. It resolves to a cookie jar.
t igemwiki = require('igemwiki-api')({ year: 2016, teamName: 'Toronto' })
wiki.login({
ername: 'randomuser',
ssword: 'password'
hen(function (jar) {
nsole.log('Login was successful, received cookie jar: ', jar)
atch((error) => {
nsole.log('Something went wrong: ', error)
Obviously you would not want to expose your username
and password
. As such,
if one of username
or password
is not passed in, you will be asked to enter
them in a prompt:
wiki.login().then(jar => console.log('Cookie jar: ', jar))
However the prompt method fails on a serverside or continuous integration
platform. It also just annoying to repeatedly enter the same login information
over and over. As per the Twelve-Factor App, sensitive
configuration should be stored in the enviroment. If a .env
file is present,
igemwiki-api
will pick values out of there if they are not provided as
options. To enable this, copy sample.env into .env
(and do
not ever commit .env) and change the values. Make sure to leave no spaces
around =
in key=val
. Instead of using .env
file, you can also just export
the variable in your current shell:
rt username=jmazz
rt password=superSecretPassword
These variables will then be available from process.env.username
and
process.env.password
within Node. In fact, then .env
method just uses
dotenv to load key/value pairs from the
.env
file into process.env
. The benefit of providing the .env
method is
that sample.env
makes it clear which values need to be set.
Then you can login like this and won't be prompted:
wiki.login()
TODO take this out. Make it so year
and teamName
NEED to be passed in.
The teamName
is also present in the environment configuration. So you can require the module like so:
t igemwiki = require('igemwiki-api')({})
See login.spec.js.
Use these to get all page urls from your team.
wiki.getTeamPages().then(pages => console.log(pages)) // array of urls
wiki.getTeamTemplates().then(templates => console.log(templates)) // array of urls as well
ou should .catch(function (error) { /* ... */ }) in real code.
See all-pages.spec.js.
Not just a simple curl
. Pulls out content of text box from ?action=edit
page. Takes dir
(download directory) in options. Use downloadAll
to download
all team pages and templates.
t path = require('path')
t { downloadAll } = require('igemwiki-api')()
loadAll({ dir: path.resolve(__dirname, './downloads') }).then(function (results) {
nsole.log('Download results: ', results)
There is also downloadPage
to download one page at a time. It takes page
and dir
:
loadPage({
ge: 'http://2016.igem.org/Team:Toronto/test-upload',
r: downloadDir
hen(result => console.log('Download: ', result))
See download.spec.js.
Upload file contents into pages, templates, or images. If local content matches
existing live content, the upload will be skipped, unless force: true
is set.
eed cookie jar from login
n()
n(function(jar) {
Everything is an ES2015 Promise!
turn upload({
jar: jar,
type: 'page', // or stylesheet, script, template, image
dest: 'test-upload', // will create Team:${teamName}/${dest} for 'page', or Template:${teamName}/{css|js}/..
source: './src/mypage.html', // the source for upload. what is entered into update page text box.
force: false // force upload even if live/local content match, default is false
n(function(results) {
nsole.log('Upload results:', results)
See upload.spec.js for the API calls which produce the
test pages below. The page
example shows how to load in CSS, Javascript, and a
template. The test-upload-undated.html
file has {{ DATE }}
replaced with the
current date when tests are ran.
| Type | Source | Destination |
|————–|——————————————————————-|—————————————————————————————————|
| stylesheet
| test-stylesheet.css | Template:Toronto/css/test-stylesheet |
| script
| test-script.js | Template:Toronto/js/test-script |
| template
| test-template.html | Template:Toronto/test-template |
| page
| test-upload-undated.html | Team:Toronto/test-upload |
Just need to set type
to image. dest
must be the image
filename, including extension.
n().then(jar => upload({
pe: 'image',
st: 'igem-logo.png', // Note full file name including extension
urce: './images/igem-logo.png' // Good idea to match this to dest,
r // with ES2015, this is the same as jar: jar
then(results => console.log(results.target)) // results.target is the direct image link