The Hypothesis Annotation Framework Documentation, Release 0.0.2
Insecure Response errors in the console
You’ve built the extension with an https base URL, the extension fails to load and you see
net::ERR_INSECURE_RESPONSE errors in the console. You need to openhttps://127.0.0.1:5000 (or whatever
--service you gave) and tell Chrome to allow access to the site even though the certificate isn’t known.
Content Security Policy errors in the console
The extensionfails to load and you see Refused toload the ... because it violates the followingContent Security Policy
directive: ... errors in the console. SeeBuildingtheChromeextensionforproduction.
Empty Response errors in the console
The
extension
fails
to
load
and
you
see
GET http://127.0.0.:5000/...
net::ERR_EMPTY_RESPONSE errors in the console. This happens if you’re running h on https but you’ve built
the Chrome extension with an http base URL. Either run h on http or rebuild the extension with --service
https://....
Connection Refused errors in the console
The
extension
fails
to
load
and
you
see
GET https://127.0.0.1:5000/...
net::ERR_CONNECTION_REFUSED errors in the console. This happens if you built the extension with an
https service URL but you’re running h on http. Either run h on https (seeRunyourlocalhinstanceusing
https)orrebuildtheextensionwith--service http://....
3.5 Submitting a Pull Request
To submit code ordocumentation to h you should submit a pull request.
For trivial changes, such as documentation changes or minor errors, PRs may be submitted directly to master. This
also applies to changes made through the GitHub editing interface. Authors do not need to sign the CLA for these, or
follow fork or branch naming guidelines.
For any non-trivial changes, please create a branch for review. Fork the main repository and create a local branch.
Later, when the branch is ready for review,push it to a fork and submit a pull request.
Discussion and review in the pull request is normal and expected. By using a separate branch, it is possible to push
new commits to the pull request branch without mixing new commits from otherfeatures or mainline development.
Some things to remember when submitting or reviewing a pull request:
• Yourpull request should contain one logically separate piece of work, and not any unrelated changes.
• When writing commit messages, please bearthe following in mind:
– http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
– https://github.com/blog/831-issues-2-0-the-next-generation
Please minimize issue gardening by using the GitHub syntax forclosing issues with commit messages.
• Name yourbranchin a way that makes it easier tofollow the history back toissues. The recommendedtemplate
is <issue name>-<slug>.
Forinstance,43-browser-extensions would be a branchtoaddress issue#43,which is tocreate browser
extensions.
3.5. Submitting a Pull Request
15
Table from pdf to powerpoint - SDK application service:C# Create PDF from PowerPoint Library to convert pptx, ppt to PDF in C#.net, ASP.NET MVC, WinForms, WPF
Online C# Tutorial for Creating PDF from Microsoft PowerPoint Presentation
www.rasteredge.com
Table from pdf to powerpoint - SDK application service:VB.NET Create PDF from PowerPoint Library to convert pptx, ppt to PDF in vb.net, ASP.NET MVC, WinForms, WPF
VB.NET Tutorial for Export PDF file from Microsoft Office PowerPoint
www.rasteredge.com
The Hypothesis Annotation Framework Documentation, Release 0.0.2
• Don’t merge on feature branches. Feature branches should merge into upstream branches, but never contain
merge commits in the otherdirection. Considerusing --rebase whenpulling if youmustkeep a long-running
branch up to date. It’s better to start a new branch and, if applicable, a new pull request when performing this
action on branches you have published.
• Code should follow ourcodingstandards.
• All pull requests should come with code comments. For Python code these should be in the form of Python
docstrings.ForAngularJScodepleaseuse ngdoc.Otherdocumentationcanbeputintothedocs/subdirectory,
but is not required for acceptance.
• All pull requests should come with unit tests. For the time being, functional and integration tests should be
considered optional ifthe project does not have any harness set up yet.
For how to run the tests, seeRunningthetests.
• Your pull request should add a line to thechangelog briefly describing the change and giving its GitHub pull
request number.
3.6 Code style
Notes on code style follow for the different languages used in the project. Most important, though, is to follow the
style of the code you are modifying, if your edits are not new files.
Please stick to strict, 80-column line limits except for small exceptions that would still be readable if they were
truncated.
Eliminate trailing whitespace wherever possible.
3.6.1 Linting
We run a variety of analysis tools on the pythoncodebase using the prospectorpackage. This is run by the CI on each
push but can also be run manually via the lint make command:
$ make lint
3.6.2 Python
StrictPEP8. The project also adheres closely to theGooglePythonStyleGuide. To reformat code inPEP8style, you
can use theYAPFtool:
$ pip install yapf
$ yapf -i <Python source file>
3.6.3 JavaScript
Generally,no semi-colons are used. This maychange. Ifyou’restartinga newfile,dowhatyou like. Like withPython,
please follow theGoogleJavaScriptStyleGuide. Additionally, Python-like spacing is followed for blank lines.
We use a combination ofJSHintandJSCS for helping confirm code style conformance.
You canrun both from the root ofthe repo specifying the directory of the JavaScript files to check:
$ jshint h/static/scripts/
$ jscs h/static/scripts/
16
Chapter 3. Contributor’s guide
SDK application service:C# Word - Table Processing in C#.NET
C# Word - Table Processing in C#.NET. Provide C# Users with Variety of Methods to Setup and Modify Table in Word Document. Overview. Create Table in Word.
www.rasteredge.com
SDK application service:C# Word - Table Row Processing in C#.NET
C# Word - Table Row Processing in C#.NET. How to Set and Modify Table Rows in Word Document with C#.NET Solutions. Overview. Create and Add Rows in Table.
www.rasteredge.com
The Hypothesis Annotation Framework Documentation, Release 0.0.2
3.6.4 HTML and CSS
Once again, theGoogleHTML/CSSStyleGuideis the place to look.
3.6.5 AngularJS
Our style is loosely based on a synthesis of several community efforts to document Angular best practices.
For filesystem structure and naming see theBestPracticeRecommendationsforAngularAppStructuredocument.
Foradditional tips on writing good AngularJScode,see the following two recommended guides, which differ slightly
but are both very good.
• https://github.com/johnpapa/angularjs-styleguide
• https://github.com/toddmotto/angularjs-styleguide
3.7 Writing documentation
To build the documentation, ensure thatSphinx is installed and issue the ‘make html‘ command from the docs
directory:
cd docs/
make html
When the build finishes, you can view the documentation by running a static web server in the newly generated
_build/html/ directory. For example:
pushd _build/html/; python n -m m SimpleHTTPServer; popd
3.8 Customized embedding
To customize the application,define a function window.hypothesisConfig which returns an options object.
The constructor property should be used to select an annotation application.
Four are provided:
Annotator.Guest,Annotator.Host,Annotator.Sidebar and Annotator.PdfSidebar.
Annotator.Guestexpectstoconnecttoan annotatorwidgetrunningina different frame. Anynumberofinstances
can communicate with a single widget in orderto provide annotation ofmany frames.
Annotator.Host is an extended version of Annotator.Guest that will instantiate an annotator widget by
loading the location given by the app option inan iframe and appendingit to the document.
Annotator.Sidebar is an extended Annotator.Host that puts the widget in a sidebar interface. It loads
additional plugins that show a bar of bucket indicators,each providing the ability to select a clusterof highlights, and
atoolbar that can be used to resize the widget and control other aspects of the user interface.
Annotator.PdfSidebar is a custom version of Annotator.Sidebar with defaults tailored for use in a
PDF.js viewer.
The following is roughly the default configuration:
window.hypothesisConfig = function () {
return {
constructor: Annotator.Sidebar,
app: 'https://hypothes.is/app.html'
3.7. Writing documentation
17
SDK application service:C# Word - Table Cell Processing in C#.NET
C# Word - Table Cell Processing in C#.NET. Online Tutorial for Users to Set and Modify Table Cells in Word Document. Overview. Create and Add Cells in Table.
www.rasteredge.com
SDK application service:How to C#: Convert PDF, Excel, PPT to Word
Footnote & Endnote Processing. Table Row Processing. Table Cell Processing. VB.NET How-to, VB.NET PDF, VB.NET Word, VB.NET Excel, VB.NET PowerPoint, VB.NET Tiff
www.rasteredge.com
The Hypothesis Annotation Framework Documentation, Release 0.0.2
};
};
3.9 Serving h over SSL in development
If you want to annotate a site that’s served over HTTPS then you’ll need to serve h over HTTPS as well, since the
browser will refuse to load external scripts (eg. H’s bookmarklet) via HTTPon a page served via HTTPS.
To serve your local dev instance ofh over HTTPS:
1. Generate a private key and certificate signing request:
openssl req -newkey rsa:1024 -nodes -keyout key.pem -out req.pem
2. Generate a self-signed certificate:
openssl x509 -req -in req.pem -signkey key.pem -out server.crt
3. Run gunicorn with the certfile and keyfile options:
gunicorn --reload --paste conf/development-app.ini --certfile=server.crt --keyfile=key.pem
4. Since the certificate is self-signed, you will need to instruct your browser to trust it explicitly by visiting
https://127.0.0.1:5000andselectingtheoptiontobypassthevalidationerror.
3.9.1 Troubleshooting
Insecure Response errors in the console
The sidebar fails to load and you see net::ERR_INSECURE_RESPONSE errors in the console. You need to open
https://127.0.0.1:5000andtellthebrowsertoallowaccesstothesiteeventhoughthecertificateisn’tknown.
3.10 Making Changes to Model Code
3.10.1 Guidelines for Writing Model Code
No Length Limits on Database Columns
Don’tputanylengthlimits on yourdatabase columns(forexamplesqlalchemy.Column(sqlalchemy.Unicode(30),
...)). These can cause painful database migrations.
Always use sqlalchemy.UnicodeText() with no length limit as the type fortext columns in the database (you
can alsouse sqlalchemy.Text() if you’re sure the column will never receive non-ASCII characters).
When necessaryvalidatethe lengths of strings in Pythoncodeinstead. This can be done usingSQLAlchemyvalidators
in model code.
View callables for HTML forms should also use Colander schemas tovalidate user input,in addition to any validation
done in the model code, because Colander supports returning per-field errors to the user.
18
Chapter 3. Contributor’s guide
SDK application service:C# Word - Header & Footer Processing in C#.NET
Create and Add Table to Footer & Header. The following demo code shows how to create table in footer and header. String docFilePath
www.rasteredge.com
SDK application service:How to C#: Overview of Using XDoc.Word
Rapidly load, create, and edit Word document (pages) in C# class library. Able to render and convert Word document to/from supported document (PDF and ODT).
www.rasteredge.com
The Hypothesis Annotation Framework Documentation, Release 0.0.2
3.10.2 Creating a Database Migration Script
If you’ve made any changes to the database schema (for example: added or removed a SQLAlchemy ORM class,
or added, removed or modified a sqlalchemy.Column on an ORM class) then you need to create a database
migration script that can be used to upgrade the production database from the previous to yournewschema.
We use Alembic to create and run migration scripts. See the Alembic docs (and look at existing scripts in
h/migrations/versions)fordetails,butthebasicstepstocreateanewmigrationscriptforhare:
1. Create the revision script by running alembic revision, for example:
alembic -c conf/alembic.ini revision -m "add the e foobar r table"
This will create a new script in h/migrations/versions/.
2. Edit the generated script,fill in the upgrade() and downgrade() methods.
Seehttp://alembic.readthedocs.org/en/latest/ops.html#opsfor details.
Note: Not every migration should have a downgrade() method. For example ifthe upgrade removes a max
length constraint on a text field, so that values longer than the previous max length can now be entered, then a
downgrade that adds the constraint back may not work with data created using the updated schema.
3. Stampyour database.
Before runningany upgrades ordowngradesyouneed to stampthedatabasewith its currentrevision,soAlembic
knows which migration scripts to run:
alembic -c conf/alembic.ini stamp <revision_id>
<revision_id> should be the revision corresponding to the version of the code that was present when the
current database was created. The will usually be the down_revision from the migration script that you’ve
just generated.
4. Test your upgrade() function by upgrading your database to the most recent revision. This will run all
migration scripts newer than the revision that yourdb is currently stamped with,which usually means just your
new revision script:
alembic -c conf/alembic.ini upgrade head
After running this command inspect your database’s schema to check that it’s as expected, and run h to check
that everything is working.
Note: You should make sure that there’s some repesentative data in the relevant columns of the database
before testing upgrading and downgrading it. Some migration script crashes will only happenwhen there’s data
present.
5. Test your downgrade() function:
alembic -c conf/alembic.ini downgrade -1
Afterrunningthis commandinspect yourdatabase’s schema tocheckthat it’s as expected. Youcan thenupgrade
it again:
alembic -c conf/alembic.ini upgrade +1
3.10. Making Changes to Model Code
19
SDK application service:C# Word - Document Processing in C#.NET
0); //Save the document doc0.Save(@""). Create, Add, Delete or Modify Paragraph and Table in Word Document. If you want to create
www.rasteredge.com
SDK application service:C# Word - Word Create or Build in C#.NET
Create Word Document from Existing Files Using C#. Create Word From PDF. Create Word From PowerPoint. Create Word From Open Office Files. Table Processing.
www.rasteredge.com
The Hypothesis Annotation Framework Documentation, Release 0.0.2
Troubleshooting Migration Scripts
(sqlite3.OperationalError) near“ALTER”
SQLite doesn’t support ALTER TABLE.To get around this, useAlembic’sbatchmode.
Cannot add a NOT NULLcolumn withdefault value NULL
If you’re adding acolumntothe model withnullable=False thenwhenthe database is upgraded itneeds toinsert
values into this column for each of the already existing rows in the table, and it can’t just insert NULL as it normally
would. So you need to tell the database what default value to insert here.
default= isn’t enough (that’s only used when the application is creating data, not when migration scripts are run-
ning), you need to adda server_default= argument toyour add_column() call.
See the existing migration scripts for examples.
20
Chapter 3. Contributor’s guide
SDK application service:C# Word - Footnote & Endnote Processing in C#.NET
Create or Add Table in Footnote & Endnote. The following demo code shows how to create table in the footnote. String docFilePath
www.rasteredge.com
SDK application service:C# Word - Convert Word to PDF in C#.NET
Word: Convert Word to PDF. C# Word - Convert Word to PDF in C#.NET. Online C# Tutorial for Converting Word to PDF (.pdf) Document. Word to PDF Conversion Overview
www.rasteredge.com
CHAPTER
4
HTTP API
This document details the h application’s public HTTP API. It is targeted at developers interested in integrating
functionality fromHypothesis into their own applications.
4.1 Authorization
Some of the API URLs documented below require a valid APItoken. To use these API URLs you should:
1. Generate yourself an APItoken onyourHypothesisdeveloperpage(you must be signed in to Hypothesis to get
to this page).
2. Put the API token in the Authorization header in yourrequests to the API.
Example request:
GET /api
Host: hypothes.is
Accept: application/json
Authorization: Bearer 6879-31d62c13b0099456de5379de90f90395
(Replace 6879-31d62c13b0099456de5379de90f90395 with yourown API token.)
4.2 root
GET /api
API root. Returns hypermedia links to the rest of the API.
Example request:
GET /api
Host: hypothes.is
Accept: application/json
Example response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"links": {
"annotation": {
21
The Hypothesis Annotation Framework Documentation, Release 0.0.2
"create": {
"desc": "Create a new annotation",
"method": "POST",
"url": "https://hypothes.is/api/annotations"
},
"delete": {
"desc": "Delete an annotation",
"method": "DELETE",
"url": "https://hypothes.is/api/annotations/:id"
},
"read": {
"desc": "Get an existing annotation",
"method": "GET",
"url": "https://hypothes.is/api/annotations/:id"
},
"update": {
"desc": "Update an existing annotation",
"method": "PUT",
"url": "https://hypothes.is/api/annotations/:id"
}
},
"search": {
"desc": "Basic search API",
"method": "GET",
"url": "https://hypothes.is/api/search"
}
},
"message": "Annotator Store API"
}
Request Headers
• Accept desired response content type
Response Headers
• Content-Type response content type
Status Codes
• 200OK – no error
4.3 search
GET /api/search
Search forannotations.
Example request:
GET /api/search?limit=1000&user=gluejar@hypothes.is
Host: hypothes.is
Accept: application/json
Example response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
22
Chapter 4. HTTP API
The Hypothesis Annotation Framework Documentation, Release 0.0.2
{
"rows": [
{
"consumer": "00000000-0000-0000-0000-000000000000",
"created": "2014-01-12T18:36:15.697572+00:00",
"id": "LGVKq4E4SKKro1dBBEMwsA",
"permissions": { ... },
"references": ["6lkzoOubSOOymDNDIgazqw"],
"target": [],
"text": "Peut-etre",
"updated": "2014-01-12T18:36:15.697588+00:00",
"uri": "http://epubjs-reader.appspot.com//moby-dick/OPS/chapter_003.xhtml",
"user": "acct:gluejar@hypothes.is"
}
],
"total": 1
}
Query Parameters
• limit – The maximum
number of annotations to return, for example:
/api/search?limit=30. (Default: 20)
• offset – The minimum number of initial annotations to skip. This is used for
pagination. For example if there are 65 annotations matching our search query
and we’re retrieving up to 30 annotations at a time, then to retrieve the last 5 do:
/api/search?limit=30&offset=60. (Default: 0)
• sort – Specify which field the annotations should be sorted by. For example to sort an-
notations by the name of the user that created them, do: /api/search?sort=user
(default: updated)
• order – Specify which order (ascending or descending) the annotations should be sorted
in. Forexample tosortannotations in ascendingorderofcreated time (i.e. oldest annotations
first)do: /api/search?sort=created&order=asc. (Default: desc)
• uri
Search
for annotations
of
a
particular URI, for example
/api/search?uri=www.example.com.
URI searches will also find
annotations of equivalent URIs.
For example if the HTML document
at
http://www.example.com/document.html
includes
a
<link
rel="canonical" href="http://www.example.com/canonical_document.html">
then annotations of http://www.example.com/canonical_document.html
will also be included in the search results. Other forms of document equivalence that are
supported include rel=”alternate” links, DOIs,PDF file IDs, and more.
• user – Search for annotations by a particular user.
For example
/api/search?user=tim will find all annotations by users named tim at any
provider, /api/search?user=tim@hypothes.is will only find annotations by
tim@hypothes.is.
• text – Search for annotations whose body text contains some text, for example:
/api/search?text=foobar
• any – Search for annotations whose quote, tags, text, uri.parts or user fields
match some query text. Forexample: /api/search?any=foobar.
Todo
4.3. search
23
The Hypothesis Annotation Framework Documentation, Release 0.0.2
Document the document query parameter.
This parameter is treated specially. We’re holding off documenting it for now because upcoming work on
document equivalence is likely to change it.
You can also search for any other field that you see in annotations returned by the h API. Visit /api/search
with no parameters to see some annotations and their fields. For example to search for all annotations with the
tag “climatefeedback” do:
/api/search?tags=climatefeedback
tag also works the same as tags.
To searchforall annotations that user seanh@hypothes.is has permission to delete do:
/api/search?permissions.delete=acct:seanh@hypothes.is
You
can
give
any
query
parameter
multiple
times.
For
example
/api/search?tags=climate&tags=feedback will find all annotations that have either tag
“climate” or “feedback”.
Warning: The id field isn’t usable in searches.
Searching for an individual annotation byID:
/api/search?id=AVAqBdTCiSJM1mYBTinl
won’t returnany results. To retrieve a single annotation by ID use thereadAPI instead.
Request Headers
• Accept desired response content type
Response Headers
• Content-Type response content type
Status Codes
• 200OK – no error
• 400BadRequest errors parsing yourquery
4.4 read
GET /api/annotations/(string: id)
Retrieve a single annotation.
Example request:
GET /api/annotations/utalbWjUaZK5ifydnohjmA
Host: hypothes.is
Accept: application/json
Example response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"consumer": "00000000-0000-0000-0000-000000000000",
24
Chapter 4. HTTP API
Documents you may be interested
Documents you may be interested