Проект:Технические работы/Персональные скрипты/Руководство

Материал из Википедии — свободной энциклопедии
Перейти к навигации Перейти к поиску

Небольшое руководство по написанию персональных скриптов для сайтов Викимедии. Разумеется, некоторые начальные знания по HTML и Javascript необходимы.

Общие скрипты[править код]

Основные скрипты, выполняемые для каждого посетителя Википедии:

В общих «системных» .JS файлах есть полезные функции, которые вы можете использовать в своих персональных скриптах, например рассмотренные ниже addOnloadHook и addPortletLink. Рекомендуется сохранить эти файлы к себе на диск — их гораздо удобнее просматривать в редакторе с подсветкой JavaScript-синтаксиса.

Структура скрипта[править код]

В момент вызова monobook.js основные HTML элементы страницы ещё не сформированы, поэтому обычно персональные скрипты выглядят так: 

//часть 1
addOnloadHook(func_start); //означает «выполнить func_start позже»

//часть 2 — выполняется в самом конце загрузки страницы
function func_start (){

 //часто просто добавляет на страницу javascript-ссылку
 <a onclick="func_action()" href="#">
}
//и тогда ещё существует

//часть 3 — выполняется при нажатии пользователем на эту ссылку
function func_action (){
}

Основные методы[править код]

Нахождение элементов[править код]

Каждый элемент HTML страницы — это узел модели DOM, позволяющей скрипту манипулировать этим элементом. Например на странице 

<form name="frmname" id="frmid">
<textarea name="txtname" id="txtid">
<input id="neighbor">

мы можем «найти» элемент textarea:

  • по его id: document.getElementById('txtid') или $('#txtid')
  • в массиве всех узлов с тем же tag: document.getElementsByTagName('textarea')[0]
  • через соседний элемент: document.getElementById('neighbor').previousSibling
  • как «дочерний» элемент «родителя»: document.getElementById('frmid').childNodes[0]
  • как к элементу формы, используя атрибуты name: document.frmname.txtname

Подробнее про DOM узлы, их свойства и методы см. w3schools (англ.) или mozilla.org (англ.). Чтобы выяснить, как сгуппированы и называются элементы документа, просто откройте в браузере исходный HTML код страницы.

Проверка страницы[править код]

Часто скрипт должен выполнять какие-то действия только на определённых страницах вики, а на всех остальных ничего не делать. Для этого можно проверить:

  • адрес страницы
if (document.URL.indexOf('&action=history') != -1) {
  //выполнять дальнейшие действия только на страницах истории правок

if (wgCanonicalNamespace == 'User_talk') {
  //выполнять дальнейшие действия только на страницах обсуждений участников
  • наличие нужных элементов страницы (только во 2-й и 3-й частях скрипта)
function func_start () {
   if (!document.editform) return; //нет формы → выходим
   ...

addPortletLink()[править код]

Основные места для добавления своих ссылок — portlet блоки с такими id:

p-logo p-personal имя моя страница обсуждения настройки …
p-cactions статья обсуждение править …

p-navigation

 Заглавная …

p-participation
 Портал …


p-search

 

p-tb
Ссылки сюда 

Структура каждого portlet:

<div id='...' class=portlet>
 <h5>Заголовок</h5>
 <div class=pBody>
  <ul>
  <li id='...'> <a ...>  //собственно ссылки
  <li id='...'> <a ...> 
  ...


Для удобства вставки в эти блоки своих ссылок в файле wikibits.js есть специальная функция
addPortletLink (portlet, href, text, id, tooltip, accesskey, nextnode) 

//Пример: добавить в «инструменты» ссылку на свой monobook.js
addPortletLink ('p-tb', '/wiki/Special:MyPage/monobook.js', 'Мой monobook.js');

Последние четыре аргумента функции необязательны:

  • id новой ссылки — если дальше в коде вам нужно к нему обращаться через getElementById
  • tooltip — всплывающая подсказка
  • accesskey — клавиша «быстрого доступа»
  • nextnode — элемент, перед которым надо вставить ссылку, например в данном случае это мог быть document.getElementById('t-specialpages'), т.е. ссылка «Спецстраницы».


Добавление элементов[править код]

В общем случае для вставки новых элементов есть два основных способа:

1) «дописывать» innerHTML родительского элемента 

//Пример использования innerHTML для создания слева нового блока:
document.getElementById('p-participation').innerHTML += 
 '</div>'+
 '<div id=my class=portlet>'+
   '<h5>моё</h5>'+
   '<div class=pBody><ul>'+
     '<li><a href=\"/wiki/Special:MyPage/monobook.js\">Мой monobook.js</a>'+
 '</ul></div></div>';


2) использовать методы DOM: CreateElement, затем присоединить новый элемент как «дочерний» с помощью AppendChild или InsertBefore. Описание использования: addPortletLink() в wikibits.js

Удаление элементов[править код]

Для перемещения существующего элемента в другое место достаточно просто прикрепить его в новом месте с помощью AppendChild или InsertBefore.

Для того, чтобы спрятать элемент, достаточно выставить его атрибут style.display в none: 

//Пример: убрать со страницы редактирования предупреждение об авторских правах
var el = document.getElementById('editpage-copywarn');
if (el) el.style.display = 'none';

Впрочем, прятать элементы лучше с помощью вашего monobook.css: #editpage-copywarn {display:none}

Страница редактирования[править код]

Для страниц редактирования из файла MediaWiki:Common.js вызывается ещё один файл MediaWiki:Onlyifediting.js.

Манипуляции с текстом[править код]

Основной элемент в форме редактирования — это конечно само поле редактирования. Это <textarea>, к которой можно обратиться как
var txt = document.editform.wpTextbox1 или
var txt = document.getElementById('wpTextbox1')

Новый текст можно добавить в начало: txt += "новый текст" или в конец текста: txt = "новый текст" + txt

Для добавления текста в то место, где находится курсор, в wikibits.js есть специальная функция
insertTags (tagOpen, tagClose, sampleText)

Панель инструментов[править код]

Кнопки над полем редактирования находятся в контейнере <div id='toolbar'>. В своих личных настройках его можно запретить.

Стандартные кнопки при нажатии вызывают insertTags(). Они определены с помощью AddButton() прямо в коде страницы и с помощью массива mwCustomEditButtons[] в MediaWiki:Onlyifediting.js. Затем, уже после вызовов 2й части вашего скрипта через addOnloadHook, эти кнопки добавляются на панель функцией mwSetupToolbar() в wikibits.js.

Поэтому если вы хотите убрать, модифицировать или добавить некоторые стандартные кнопки, то проще всего это сделать, изменяя массив mwEditButtons[] или mwCustomEditButtons[] 

//Пример: сделать чтобы кнопка подписи вставляла    — ~~~~
 if (mwEditButtons.length >= 10 && mwEditButtons[9].tagOpen == '--~~~~')
   mwEditButtons[9].tagOpen = ' — ~~~~';

Пример добавления кнопок, выполняющих произвольное действие: marque_tab() («Таблица» и «Викификатор») в MediaWiki:Onlyifediting.js. Пример добавления текстовой кнопки: addToolbarButton() в QPreview.js

Большой набор дополнительных кнопок: en:User:MarkS/Extra_edit_buttons.

Панель вставки[править код]

Под полем редактирования есть панель «быстрой вставки» специальных символов и основных элементов вики-разметки. Она генерируется из MediaWiki:Edittools с помощью mw:Extension:CharInsert, и состоит из множества javascript-ссылок на всё ту же функцию insertTags(). 

//Пример: добавление в панель своей вставки
var specialchars = document.getElementById ('editpage-specialchars');
if (specialchars){
  specialchars.innerHTML +="<a onclick=\"insertTags('<div style=\"float:right\">','</div>','');return false\" href=\"#\">&lt;div float:right&gt;</a>";
}

Отметим, что принципиальной разницы между верхней и нижней панелями нет, добавлять свои кнопки и ссылки можно с одинаковым успехом в обе панели.

Отладка скрипта[править код]

Предпросмотром в Monobook.js[править код]

Прямо на странице редактирования вашего Monobook.js вы можете менять ваш скрипт, нажимать «Предварительный просмотр», и сразу наблюдать результат на странице предпросмотра.

Сохранением в Monobook.js[править код]

Однако если на странице редактирования нет нужных вам элементов (например вы отлаживаете скрипт, работающий со страницей истории правок), то вам придётся нажать кнопку «Записать страницу», обновить кэш браузера (обычно Ctlr-F5) и уже тогда проверять результат.

Однако этот способ не очень удобен, и создаёт излишнюю нагрузку на серверы Википедии.

Вызовом из Monobook.js[править код]

Самый удобный и рекомендованный способ — вставить в свой Monobook.js код 

document.write('<script type="text/javascript" src="http://localhost/test.js"><\/script>');

Затем запустить у себя на компьютере веб сервер и положить ему в нужную папку файл test.js, код в котором будет выполнятся так же, как если бы он находился прямо в Monobook.js

Так вы сможете править свой код в файле test.js любым текстовым редактором со всеми удобствами и с подсветкой синтаксиса. Затем сохранять изменения на диск, переключаться на окно браузера со страницей Википедии и обновлять страницу.

В качестве веб-сервера можно например использовать TinyWeb, занимающий менее 100кбайт на диске и не требующий установки. Загрузите и распакуйте файл tinyweb.zip например в папку c:\Program Files\Tinyweb, затем создайте ярлык на tiny.exe, в свойствах ярлыка добавьте как аргумент имя вашей папки, в которой лежат test.js и необходимый пустой файл index.html. Запускайте TinyWeb этим ярлыком; для выгрузки программы используйте Диспетчер Задач.

Другие способы[править код]

Можно отлаживать скрипты: 

javascript: var s = document.createElement('script');
s.src = 'file://C:/myscript.js';
document.getElementsByTagName('head')[0].appendChild(s);void 0

Однако все эти способы запускают ваш .js файл немного не в тот момент, и могут требовать некоторой модификации кода на время отладки.

Куски кода[править код]

Вы можете запускать отдельные куски кода на уже загруженной странице, например прямо в адресной строке браузера: javascript: var s = document.title; alert(s);

Или с использованием bookmarklet'a (англ.) «JavaScript Shell». Он открывает новое окно браузера, в которое можно вставлять куски кода и выполнять их по нажатию Enter.

Рекомендуется однако использование полноценного отладчика, в котором возможность выполнения кусков кода присутствует наряду со множеством других полезных функций.

Программы[править код]

Текстовый редактор[править код]

Для редактирования скрипта подойдёт любой текстовый редактор. Если вы используете строки с кириллическими буквами, то редактор должен поддерживать UTF-8.

Рекомендуется к использованию свободный редактор Notepad++, который может:

  • подсвечивать Javascript код
  • подсказывать названия основных Javascript методов по Ctrl-Enter
  • показывать «оглавление кода» как список всех функций, с возможностью быстрого перехода к ним
  • временно «сворачивать» куски кода (см en:Code_folding)

Отладчики для IE[править код]

Для отладки Javascript кода в Internet Explorer вам нужно убрать галочку «Запретить отладку скрипта» в Дополнительных настройках и затем пользоваться одним из 3х отладчиков:

  • Microsoft Script Debugger — можно скачать бесплатно после подтверждения подлинности вашей копии Windows
  • Microsoft Script Editor — включён в состав FrontPage в Microsoft Office XP/2003
  • Отладчик, идущий вместе с Visual Studio.net.

Подробнее см. IEBlog: Scripting Debugging in Internet Explorer (англ.)

Firebug[править код]

Минимальные необходимые возможности отладки в Firefox предоставляет Tools > Javascript Console. Она показывает ошибки в интерпретации Javascript и CSS на страницах, открываемых в браузере, и может быстро показать место ошибки в исходном коде.

Для серьёзной работы рекомендуется установить исключительно полезное расширение FireBug (англ.). Оно позволяет отлаживать скрипты, быстро находить нужные HTML элементы, запускать произвольные куски кода. Кроме того, оно может показывать время выполнения и все заголовки запросов к HTTP серверам.

Источник — https://ru.wikipedia.org/w/index.php?title=Проект:Технические_работы/Персональные_скрипты/Руководство&oldid=90886680