siftal/src/js/docs/contextmenu.md

CSS Framework, not bad ;)

کلیک راست
===
این ماژول برای نمایش منوی کلیک راست خاص روی عناصر استفاده می‌شود که استفاده ساده‌ای دارد.

نحوه کار
---

روش کار این ماژول به این صورت است که ابتدا عنصر دربر گیرنده‌ای برای آیتم‌ها را با متد `createWrapper` میسازد،  سپس رویداد `contextmenu:init` جرقه می‌خورد. 

در مرحله بعد، بر روی رویداد `contextmenu` شنود می‌کند و در این رویداد، با استفاده از متد `open` منو را باز، و با رویداد `close` که توسط فایل `modal.js` جرقه می‌خورد، با متد `close` بسته می‌شود.

سپس روی رویداد `keydown` پنجره شنود می‌کند تا بتواند به کلید‌ها پاسخ مناسب دهد. در صورت باز بودن منو، فرمان‌های کلیدی کار می‌کنند. برای مثال میتوانید با استفاده از دکمه‌های جابجایی فلشی بین گزینه‌ها جابجا شوید و با دکمه‌ی `enter` گزینه‌ی فعال را انتخاب کنید، همچنین می‌توانید با کلید `esc` منو را ببندید. کلید‌های میانبر تعیین شده با `hotkey` هم با فشردن کلید مورد نظر فعال می‌شوند.

سپس منتظر بارگزاری کامل صفحه (`document.ready`) می‌شویم و عنصر دربرگیرنده را به بدنه صفحه اضافه می‌کنیم و رویداد `contextmenu:appended` جرقه می‌خورد.

استفاده
---

برای استفاده از این ماژول از متد `ctxMenu` اشیاء جی‌کوری استفاده کنید که تنها یک آرگومان قبول می‌کند که یک شی تنظیمات است که بعد از مثال توضیح داده شده است.

```javascript
$('ul').ctxMenu({
    items: [
        {
            text: 'Open',
            hotkey: 'O'
        },
        {
            text: 'First Element',
            hotkey: '1'
        },
        {
            text: 'About',
            link: 'http://talambar.com',
            hotkey: 'T'
        }
    ],
    item: {
        link: false
    }
});
```
######items
لیستی از آیتم‌های منو که شامل اشیایی با تنظیمات مورد نیاز است. تنظیمات پیش‌فرض آیتم‌ها در `item` توضیح داده شده‌اند. همیشه میتوانید بعد از ساخت منو آیتم‌هایی به آن اضافه و یا کم کنید.

######item
این شی تعیین کننده تنظیمات پیش‌فرض آیتم‌ها است که در صورت معین نبودن در شی آیتم، به آن اضافه می‌شوند (با استفاده از `underscore.defaults`).

این تنظیمات بسته به نحوه‌ی سایت عناصر است که در متد `createItems` تعیین می‌شود، تنظیمات پیش‌فرض شامل تنظیمات زیر است:

* text متن قرار گرفته در آیتم
* link مقدار مشخصه `href` که به آیتم داده می‌شود

جدا از این تنظیمات که مختص `createItems` است، مشخصه `hotkey` وجود دارد که تعیین می‌کند کدام دکمه کیبورد این آیتم را فعال می‌کند. دقت کنید که نمایش خط زیر این کاراکتر در متن آیتم بر عهده‌ی `createItems` است.


متد‌ها
---

######add → index
######(item: Object)
این متد آیتم جدیدی را اضافه می‌کند و اندیس آیتم جدید را باز‌میگرداند که در متد حذف قابل استفاده است.

رویداد:‌ `contextmenu:update`

######remove → items.length
######(index: Number)
این متد آیتم موجود در اندیس مورد نظر را حذف می‌کند و تعداد آیتم‌های در حال حاظر را باز می‌گرداند.

رویداد: `contextmenu:update`

######open
######(event: Event)
این متد برای باز کردن منو در محل مورد نظر استفاده می‌شود. توجه کنید این متد برای استفاده با رویداد‌های موس طراحی شده است و ورودی شما باید یک شی `Event` و یا مشابه آن باشد که مشخصه‌های `pageX` و `pageY` داشته باشد.

پس از باز شدن، مقدار مشخصه `status` شی به  ۱ تغییر می‌کند.

رویداد: `contextmenu:open`

######close
این متد منو با می‌بندد و آیتم‌ها را از حالت فعال خارج می‌کند.

پس از بسته شدن مقدار مشخصه `status` شی به ۰ تغییر می‌کند.

رویداد:‌ `contextmenu:close`

######createItems → jQuery
این متد آیتم‌ها را می‌سازد که میتوانید آن را بازنویسی کنید.

مقدار بازگشتی باید مقداری باشد که بتوان با استفاده از متد `jQuery.append`‌ از آن استفاده کرد.

######createWrapper → jQuery
این متد یک عنصر دربرگیرنده آیتم‌ها را میسازد. دلیل جدایی این متد از `createItems` نبود نیاز به دوباره سازی این عنصر در تغییرات آیتم‌ها است که از مصرف بی‌رویه منابع جلوگیری می‌کند.

مقدار بازگشتی باید مقداری باشد که بتوان با استفاده از `jQuery.append` از آن استفاده کرد.

######clone → ContextMenu
######(element: Element/jQuery/Selector)
 این متد یک منوی جدید با آیتم‌های منوی حاظر برای عناصر تعیین شده در آرگومان می‌سازد. این آرگومان باید توسط `jQuery` قابل تبدیل به عنصر باشد.
 
رویداد‌ها
---

با جابجایی بین آیتم‌ها با استفاده از دکمه‌های فلش‌های جابجایی، رویداد `contextmenu:selection:change` با آرگومانی که تعیین‌ کننده عنصر انتخاب شده است جرقه می‌خورد.

همچنین هنگام فعال سازی هر آیتم، چه با کلیک و چه با کیبورد، رویداد `contextmenu:selection:trigger` با  آرگومانی حاوی اندیس آیتم انتخاب شده جرقه می‌خورد. همچنین رویدادی برای هر اندیس جرقه می‌خورد که به این شکل است:

`contextmenu:selection:trigger:<index>` مثلا `contextmenu:selection:trigger:2`
 
 مثال
---

 این مثال در فایل `index.html` در پوشه‌ی ماژول‌ها موجود است.
 
 
 ```javascript
var header = $('header').ctxMenu({
    items: [
        {text: 'Salam', hotkey: 's'},
        {text: 'Talambar', link: 'http://talambar.com', hotkey: 't'},
        {text: 'Option 1', hotkey: '1'}
    ]
});

header.on('contextmenu:selection:trigger:2', function(e) {
    alert('Option 1 chosen');
});

var footer = header.clone('footer');

footer.add({
    text: 'Footer\'s special item',
    hotkey: 'f'
});

footer.on('contextmenu:selection:trigger:3', function() {
    alert('Footer!');
})
 ```